create-win-project 1.4.0 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Win
+Copyright (c) 2026 itsw1n
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,178 +1,85 @@
 <div align="center">
   <img src="./public/logo.svg" alt="W1N Project logo" width="160">
   <h1>W1N PROJECT</h1>
-  <p>Production-ready project scaffolding.</p>
+  <p>Generate a tested, production-oriented web or mobile project with stack-specific code, CI, deployment artifacts, documentation, and agent guidance.</p>
 </div>
 
-# Are you confused creating architecture rules, AGENTS.md, and folder structures from scratch every time you pick a new stack?
+## Start
 
-> **Just answer what tech stack you want.** `create-win-project` turns your answers into a runnable, tested, agent-ready foundation — not an empty folder with a giant doc dump.
-
-Stop bikeshedding folders for 3 days. Stop pasting a 500-line `AGENTS.md` that burns tokens and still lets the agent hallucinate your stack. Your stack, your rules, already wired.
-
-[![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)
-[![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)
-
-Next.js · React + Vite · Expo (React Native) · Spring Boot · Supabase · PostgreSQL · Tailwind · CSS Modules
-
----
-
-## Why this exists
-
-You were that dev who rebuilt the same foundation twice — Next.js App Router one week, Expo the next, Spring Boot after that. Same questions: where do components live? How does auth refresh? What goes in `AGENTS.md` without drowning the context window?
-
-**The fix:** answer a short, plain-language interview and get **two coordinated outputs**:
-
-1. **A small runnable app** — real page/screen, strict TypeScript, ESLint, health endpoint, tests, and the exact config for your stack.
-2. **A task-routed docs layer** — a tiny always-on `AGENTS.md` + a lazy `RULES.md` (`concern → playbook §`). The agent reads only what it touches, when it touches it.
-
-Manifests declare capabilities and package names. A tested compatibility profile owns every exact version, so generated stacks are declarative without letting version strings drift.
-
-## Prerequisites — what you actually need to install
-
-### Lane 1 — To run *this generator*
-**Node 24 LTS *OR* Docker — that's it.**
+```bash
+npx create-win-project@latest
+```
 
-- 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.
+Answer product questions, choose whether dependencies should be installed, then follow the generated project README. Existing non-empty destinations are never overwritten.
+
+```text
+my-project/
+├── application source and tests
+├── .github/workflows/       CI and security checks
+├── Dockerfile / eas.json    production artifacts when applicable
+├── AGENTS.md                small agent operating contract
+├── RULES.md                 task-to-playbook router
+├── CONTEXT.md               product decisions and approved deviations
+├── playbooks/               selected stack guidance
+└── create-win-project.profile.json
+```
 
-### 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 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 |
+## Supported stacks
 
-**Hybrid:** the exact commands for *your* stack live in the README inside `./your-project` and `docs/guides/setup.md` — no duplication here. If you didn't enable Docker/Make, no compose file is generated.
+| Application | Backends and data |
+|---|---|
+| Next.js | None, Supabase, PostgreSQL, Spring Boot, Laravel, FastAPI |
+| React + Vite | None, Supabase, Spring Boot, Laravel, FastAPI |
+| Expo / React Native | None, Supabase, Spring Boot, Laravel, FastAPI |
+| Laravel UI | Blade, Livewire, or Inertia React with Laravel |
+| API only | Spring Boot, Laravel, or FastAPI |
 
-## Quick start
+Authentication follows the chosen stack and audience: Supabase Auth, server sessions, Sanctum SPA, or OIDC validation where supported.
 
-**Fastest (no clone required):**
+## Production-oriented by default
 
-```bash
-npx create-win-project@latest
-```
+Version 2 generates stack-appropriate tests, CI and security checks, production builds, environment guidance, operations documentation, and cloud-neutral deployment artifacts. Web tests include Playwright; Expo uses Jest and React Native Testing Library.
 
-**From a clone with Node:**
+Optional complexity remains requirement-driven:
 
-```bash
-npm ci
-npm run doctor
-npm start
-```
+- Private object-storage uploads appear only when uploads are required.
+- Durable queue conventions appear only when background jobs are required.
+- Offline cache or synchronization appears only for mobile when selected.
+- Development Docker and Make remain optional.
 
-**Docker-first (no host Node or Make needed):**
+The baseline is not a substitute for product authorization, infrastructure sizing, compliance, secrets, monitoring, deployment approval, backups, or restore drills. See the [production contract](./docs/production-contract.md).
 
-```bash
-git clone https://github.com/itsw1n/create-win-project && cd create-win-project
-docker compose build
-docker compose run --rm app
-```
+## Agent-flexible defaults
 
-`docker compose run` creates a disposable CLI container and reuses the existing image. It does not rebuild an existing image unless you explicitly build again. On systems with Make, `make build` and `make generate` are shortcuts; `make run` remains an alias for `make generate`.
+Agents may propose different architecture, providers, authentication, data boundaries, or major dependencies, but must obtain approval and record the decision in `CONTEXT.md` before changing them.
 
-<details>
-<summary>Prefer host Node?</summary>
+Exact tested direct versions come from dated profiles. Package managers resolve transitive dependencies and create project-owned lockfiles. Existing projects can run a read-only comparison:
 
 ```bash
-npx create-win-project --install      # install generated dependencies now
-npx create-win-project --no-install   # generate files only
-npx create-win-project doctor         # diagnose available tools
-# then follow the same interview
+create-win-project upgrade-report .
 ```
 
-Requires Node 24 LTS. Still dockerizes the *generated* app only if you enabled it.
+## Documentation
 
-</details>
+- [Documentation map](./docs/README.md)
+- [Getting started](./docs/getting-started.md)
+- [Production contract](./docs/production-contract.md)
+- [Stacks and capabilities](./docs/capabilities.md)
+- [Understanding a generated project](./docs/generated-project.md)
+- [Compatibility and upgrades](./docs/compatibility.md)
+- [Migrating from version 1](./docs/migration-v2.md)
 
-**Then run what you generated:**
+## Development
 
 ```bash
-# Next.js or Expo
-cd your-project
-npm install
-npm run dev
-
-# React + Vite (frontend workspace)
-cd your-project/frontend
-npm install
-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
-
-- **Three frontend families** — Next.js App Router, React + Vite, and Expo Router.
-- **Optional backends** — every frontend can choose no backend, Supabase, PostgreSQL where supported, or Spring Boot.
-- **Styling** — Tailwind CSS or CSS Modules (native-styles for Expo).
-- **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.
-- **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, definition ↔ heading checks, and a generated-output matrix covering every pairing, architecture profile, and applicable auth model.
-
-## What you get
-
-| File | Purpose |
-|------|---------|
-| `AGENTS.md` | Lean, always-loaded guidance for your coding agent. |
-| `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 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. |
-| `Makefile` / `docker-compose.yml` / `.github/workflows` | Optional, interview-toggled. |
-
-## How it works
-
-The generator never hardcodes the folder or playbook list. It loads `library/**/definition.json` and resolves a *stack*:
-
-```jsonc
-// library/stacks/nextjs/definition.json (excerpt)
-{
-  "id": "nextjs",
-  "kind": "frontend",
-  "label": "Next.js",
-  "appliesTo": { "backend": ["none", "supabase", "springboot", "postgres"] },
-  "architectureProfiles": ["small", "medium", "large"],
-  "playbooks": [
-    "stack/nextjs/architecture.md",
-    "stack/nextjs/structure.md",
-    "stack/nextjs/runtime.md",
-    "stack/nextjs/security.md",
-    "stack/nextjs/testing.md"
-  ],
-  "deps": ["next", "react", "react-dom"],
-  "concerns": [
-    { "id": "validation", "required": false, "when": "runtime validation needed", "sections": ["Zod for Runtime Validation"] }
-  ]
-}
+git clone https://github.com/itsw1n/create-win-project
+cd create-win-project
+npm ci
+npm test
 ```
 
-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 · definition-driven · lean documentation · lazy rules index
-
-## Contributing
-
-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).
+See the [maintainer documentation](./docs/maintainers/contributing.md) before changing manifests, generated behavior, compatibility profiles, or CI.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE) if added, otherwise free to use and adapt.
+Licensed under the [MIT License](./LICENSE). Copyright © 2026 itsw1n.

package/checks/check-compatibility.js

@@ -7,20 +7,21 @@ if (!['none', 'smoke', 'stack', 'full'].includes(scope)) throw new Error('--scop
 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',
-  'react-none', 'react-supabase', 'react-springboot', 'react-laravel',
-  'react-native-none', 'react-native-supabase', 'react-native-springboot', 'react-native-laravel',
+  'nextjs-none', 'nextjs-supabase', 'nextjs-springboot', 'nextjs-postgres', 'nextjs-laravel', 'nextjs-fastapi',
+  'react-none', 'react-supabase', 'react-springboot', 'react-laravel', 'react-fastapi',
+  'react-native-none', 'react-native-supabase', 'react-native-springboot', 'react-native-laravel', 'react-native-fastapi',
   'laravel-api', 'laravel-blade', 'laravel-livewire', 'laravel-inertia-react',
+  'fastapi-api',
 ]
 
 function authChoices(caseName) {
   const mobile = caseName.startsWith('react-native')
-  const nonBrowser = mobile || caseName === 'laravel-api'
+  const nonBrowser = mobile || caseName === 'laravel-api' || caseName === 'fastapi-api'
   const base = ['not-yet', 'none'].map((authentication) => ({ authentication, audience: nonBrowser ? 'multi-client' : 'website' }))
   if (caseName.includes('supabase')) base.push({ authentication: 'yes', audience: mobile ? 'multi-client' : 'website' })
-  if (caseName.includes('springboot') || caseName.includes('laravel')) {
+  if (caseName.includes('springboot') || caseName.includes('laravel') || caseName.includes('fastapi')) {
     if (caseName.startsWith('laravel-') && caseName !== 'laravel-api') base.push({ authentication: 'yes', audience: 'website' })
-    else if (mobile || caseName === 'laravel-api') base.push({ authentication: 'yes', audience: 'multi-client' })
+    else if (mobile || caseName === 'laravel-api' || caseName === 'fastapi-api') base.push({ authentication: 'yes', audience: 'multi-client' })
     else base.push({ authentication: 'yes', audience: 'website' }, { authentication: 'yes', audience: 'multi-client' })
   }
   return base
@@ -44,9 +45,22 @@ const smokeSelections = [
   ['laravel-livewire', 'medium', 'none', 'website'],
   ['laravel-inertia-react', 'large', 'yes', 'website'],
   ['react-laravel', 'medium', 'yes', 'website'],
+  ['nextjs-fastapi', 'small', 'none', 'website'],
+  ['nextjs-fastapi', 'medium', 'yes', 'website'],
+  ['fastapi-api', 'medium', 'not-yet', 'multi-client'],
+  ['fastapi-api', 'large', 'yes', 'multi-client'],
 ]
 const matchesSmoke = (entry) => smokeSelections.some(([caseName, architecture, authentication, audience]) =>
   entry.case === caseName && entry.architecture === architecture && entry.authentication === authentication && entry.audience === audience)
+const containerSelections = new Set([
+  'nextjs-none:small:not-yet:website',
+  'react-springboot:large:yes:website',
+  'laravel-inertia-react:large:yes:website',
+  'nextjs-fastapi:medium:yes:website',
+])
+const verifiesContainers = (entry) => entry.profile === current && containerSelections.has(
+  `${entry.case}:${entry.architecture}:${entry.authentication}:${entry.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.
@@ -62,5 +76,20 @@ function belongsToStack(caseName, 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` }))))
+const selected = (scope === 'full' ? full : scope === 'stack' ? stack : smoke)
+  .map((entry) => ({
+    ...entry,
+    native: scope === 'smoke' || matchesSmoke(entry),
+    containers: verifiesContainers(entry),
+  }))
+const shards = Array.from({ length: 4 }, (_, index) => ({ shard: index + 1, cases: [] }))
+const containerCases = selected.filter((entry) => entry.containers)
+const nativeCases = selected.filter((entry) => entry.native && !entry.containers)
+const contractCases = selected.filter((entry) => !entry.native)
+containerCases.forEach((entry, index) => shards[index % shards.length].cases.push(entry))
+nativeCases.forEach((entry, index) => shards[index % shards.length].cases.push(entry))
+contractCases.forEach((entry) => {
+  const shortest = shards.reduce((best, shard) => shard.cases.length < best.cases.length ? shard : best)
+  shortest.cases.push(entry)
+})
+process.stdout.write(JSON.stringify(shards.filter(({ cases }) => cases.length)))

package/checks/check-generated-project.js

@@ -25,6 +25,10 @@ const cases = {
   'react-native-springboot': { frontend: 'react-native', backend: 'springboot', packageName: 'com.example' },
   'react-native-none': { frontend: 'react-native', backend: 'none' },
   'react-native-laravel': { frontend: 'react-native', backend: 'laravel', applicationShape: 'mobile' },
+  'react-native-fastapi': { frontend: 'react-native', backend: 'fastapi', applicationShape: 'mobile' },
+  'nextjs-fastapi': { frontend: 'nextjs', backend: 'fastapi', styling: 'tailwind' },
+  'react-fastapi': { frontend: 'react', backend: 'fastapi', styling: 'tailwind', applicationShape: 'separate' },
+  'fastapi-api': { frontend: 'no-frontend', backend: 'fastapi', applicationShape: 'api' },
   'laravel-api': { frontend: 'no-frontend', backend: 'laravel', applicationShape: 'api' },
   'laravel-blade': { frontend: 'laravel-ui', backend: 'laravel', applicationShape: 'fullstack', laravelUi: 'blade', styling: 'tailwind' },
   'laravel-livewire': { frontend: 'laravel-ui', backend: 'laravel', applicationShape: 'fullstack', laravelUi: 'livewire', styling: 'tailwind' },
@@ -32,7 +36,7 @@ const cases = {
 }
 
 if (!args.profile || !cases[args.case]) {
-  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]`)
+  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] [--native=true|false]`)
 }
 
 const architecture = args.architecture || 'medium'
@@ -67,7 +71,7 @@ try {
     authentication,
     authAudience,
     testing: selected.frontend === 'react-native' ? 'basic' : 'full',
-    docker: selected.frontend !== 'react-native' || selected.backend === 'laravel',
+    docker: selected.frontend !== 'react-native' || ['laravel', 'fastapi'].includes(selected.backend),
     makefile: false,
     githubActions: true,
     expectedConcerns: [],
@@ -80,6 +84,9 @@ try {
       metadata.authentication.intent !== authentication || metadata.authentication.audience !== authAudience) {
     throw new Error('Generated profile metadata does not match the requested matrix entry')
   }
+  if (args.native === 'false') {
+    console.log(`Generated contract verified: ${projectName}`)
+  } else {
   const packageRoot = selected.frontend === 'react' ? path.join(projectRoot, 'frontend') : projectRoot
   const publicEnv = {
     NEXT_PUBLIC_SUPABASE_URL: 'https://example.supabase.co',
@@ -94,7 +101,7 @@ try {
     POSTGRES_USER: 'postgres',
     POSTGRES_PASSWORD: 'compatibility-test',
     POSTGRES_DB: projectName.replaceAll('-', '_'),
-    DATABASE_URL: `postgresql://postgres:compatibility-test@localhost:5432/${projectName.replaceAll('-', '_')}`,
+    DATABASE_URL: `postgresql+asyncpg://postgres:compatibility-test@localhost:5432/${projectName.replaceAll('-', '_')}`,
     SPRING_PROFILES_ACTIVE: 'test',
     OIDC_ISSUER_URI: 'http://localhost:9090/realms/app',
     OIDC_AUDIENCE: 'api',
@@ -140,6 +147,22 @@ try {
     }
   }
 
+  if (selected.backend === 'fastapi') {
+    const backendRoot = selected.frontend === 'no-frontend' ? projectRoot : path.join(projectRoot, 'backend')
+    run('uv', ['sync'], backendRoot)
+    run('docker', ['compose', 'up', '-d', '--wait', 'db'], projectRoot, publicEnv)
+    try {
+      run('uv', ['run', 'ruff', 'check', '.'], backendRoot)
+      run('uv', ['run', 'ruff', 'format', '--check', '.'], backendRoot)
+      run('uv', ['run', 'mypy', '.'], backendRoot)
+      run('uv', ['run', 'pytest'], backendRoot, publicEnv)
+      run('uv', ['run', 'alembic', 'upgrade', 'head'], backendRoot, publicEnv)
+      run('uv', ['run', 'alembic', 'check'], backendRoot, publicEnv)
+    } finally {
+      run('docker', ['compose', 'down', '--volumes'], projectRoot, publicEnv)
+    }
+  }
+
   if (selected.frontend !== 'react-native') {
     run('docker', ['compose', 'config'], projectRoot, publicEnv)
     if (args.containers === 'true') {
@@ -147,6 +170,7 @@ try {
       if (selected.backend === 'postgres') run('docker', ['build', '-t', `${projectName}:compat`, '.'], projectRoot, publicEnv)
     }
   }
+  }
 } finally {
   process.chdir(root)
   await fs.remove(fixtureRoot)

package/checks/check-library.js

@@ -23,10 +23,10 @@ const authIntents = ['not-yet', 'none']
 for (const frontend of catalog.frontends) {
   for (const backend of frontend.appliesTo?.backend || []) {
     const authCases = [...authIntents]
-    if (['supabase', 'springboot'].includes(backend)) authCases.push('yes')
+    if (['supabase', 'springboot', 'fastapi'].includes(backend)) authCases.push('yes')
     for (const architecture of architectures) {
       for (const authentication of authCases) {
-        const audiences = authentication === 'yes' && backend === 'springboot'
+        const audiences = authentication === 'yes' && ['springboot', 'fastapi'].includes(backend)
           ? ['website', 'multi-client']
           : [frontend.platform === 'mobile' ? 'multi-client' : 'website']
         for (const authAudience of audiences) {
@@ -48,8 +48,12 @@ 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('stacks/') || relative.startsWith('platforms/') || relative.startsWith('features/') ? 250 : 650
+  const limit = 200
   if (content.split('\n').length > limit) errors.push(`${relative}: exceeds ${limit} lines`)
+  const headings = [...content.matchAll(/^#{1,2}\s+(.+)$/gm)].map((match) => match[1].trim().toLocaleLowerCase('en'))
+  for (const heading of new Set(headings.filter((value, index) => headings.indexOf(value) !== index))) {
+    errors.push(`${relative}: duplicate heading ${heading}`)
+  }
   for (const match of content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
     const target = match[1].split('#')[0]
     if (!target || /^(?:https?:|mailto:)/.test(target)) continue
@@ -64,8 +68,14 @@ for (const directory of [path.join(root, 'README.md'), path.join(root, 'docs'),
     ? (await fs.readdir(directory, { recursive: true, withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.endsWith('.md')).map((entry) => path.join(entry.parentPath, entry.name))
     : [directory]
   for (const file of files) {
+    if (path.relative(root, file).startsWith(`docs${path.sep}superpowers${path.sep}`)) continue
     const content = await fs.readFile(file, 'utf8')
     for (const stale of staleClaims) if (content.includes(stale)) errors.push(`${path.relative(root, file)}: stale reference ${stale}`)
+    for (const match of content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+      const target = match[1].split('#')[0]
+      if (!target || /^(?:https?:|mailto:)/.test(target)) continue
+      if (!await fs.pathExists(path.resolve(path.dirname(file), target))) errors.push(`${path.relative(root, file)}: broken link ${match[1]}`)
+    }
   }
 }
 

package/checks/check-package.js

@@ -0,0 +1,15 @@
+import { execFileSync } from 'node:child_process'
+
+const [{ files = [] } = {}] = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--json'], { encoding: 'utf8' }))
+const names = new Set(files.map(({ path }) => path))
+const required = ['index.js', 'package.json', 'README.md', 'LICENSE', 'src/cli/main.js', 'library/tested-versions.json']
+const missing = required.filter((name) => !names.has(name))
+const forbidden = [...names].filter((name) => name.startsWith('.github/') || name.startsWith('tests/') || name.includes('.env'))
+
+if (missing.length || forbidden.length) {
+  if (missing.length) console.error(`Missing package files: ${missing.join(', ')}`)
+  if (forbidden.length) console.error(`Forbidden package files: ${forbidden.join(', ')}`)
+  process.exitCode = 1
+} else {
+  console.log(`Package contents verified (${names.size} files).`)
+}

package/checks/classify-changes.js

@@ -1,28 +1,18 @@
 import { pathToFileURL } from 'node:url'
+import impact from '../library/compatibility-impact.json' with { type: 'json' }
 
-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\//],
-]
+const DOCUMENTATION = /^(?:AGENTS\.md|README\.md|LICENSE|docs\/|\.github\/ISSUE_TEMPLATE\/|\.github\/PULL_REQUEST_TEMPLATE)/
+const STACK_PATHS = Object.entries(impact.stacks)
 
 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' }
+  if (changed.some((file) => impact.shared.some((prefix) => file.startsWith(prefix)))) 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)
+    const matches = STACK_PATHS.filter(([, prefixes]) => prefixes.some((prefix) => file.startsWith(prefix))).map(([stack]) => stack)
     if (matches.length) matches.forEach((stack) => stacks.add(stack))
     else if (!DOCUMENTATION.test(file)) hasOrdinaryChange = true
   }

package/checks/run-compatibility-shard.js

@@ -0,0 +1,21 @@
+import { spawnSync } from 'node:child_process'
+
+const cases = JSON.parse(process.env.COMPATIBILITY_CASES || '[]')
+if (!Array.isArray(cases) || !cases.length) throw new Error('COMPATIBILITY_CASES must contain at least one case')
+
+for (const testCase of cases) {
+  const args = [
+    'checks/check-generated-project.js',
+    `--profile=${testCase.profile}`,
+    `--case=${testCase.case}`,
+    `--architecture=${testCase.architecture}`,
+    `--authentication=${testCase.authentication}`,
+    `--auth-audience=${testCase.audience}`,
+    `--native=${testCase.native !== false}`,
+  ]
+  if (testCase.native !== false && testCase.containers && process.env.VERIFY_CONTAINERS === 'true') args.push('--containers=true')
+  console.log(`::group::${testCase.profile} ${testCase.case} ${testCase.architecture} ${testCase.authentication}`)
+  const result = spawnSync(process.execPath, args, { stdio: 'inherit' })
+  console.log('::endgroup::')
+  if (result.status !== 0) process.exit(result.status ?? 1)
+}

package/docs/README.md

@@ -0,0 +1,20 @@
+# Documentation
+
+## Using create-win-project
+
+- [Getting started](getting-started.md) — install the CLI and create the first project.
+- [Production contract](production-contract.md) — guarantees and team-owned work.
+- [Stacks and capabilities](capabilities.md) — supported combinations and conditional features.
+- [Generated project](generated-project.md) — files and next steps after generation.
+- [Compatibility and upgrades](compatibility.md) — versions, lockfiles, support, and reports.
+- [Version 1 migration](migration-v2.md) — adopt version 2 without overwriting a project.
+
+## Maintaining the generator
+
+- [Architecture](maintainers/architecture.md)
+- [Content model](maintainers/content-model.md)
+- [CI strategy](maintainers/ci-strategy.md)
+- [Dependency maintenance](maintainers/dependencies.md)
+- [Contributing](maintainers/contributing.md)
+
+The `library/` directory contains manifest-selected knowledge copied into generated projects for coding agents. It is not general user documentation.

package/docs/capabilities.md

@@ -0,0 +1,13 @@
+# Stacks and capabilities
+
+Frontends include Next.js, React with Vite, Expo/React Native, and Laravel Blade, Livewire, or Inertia React. Server/data boundaries include none, Supabase, PostgreSQL through Prisma, Spring Boot, Laravel, and FastAPI (Python with uv, async SQLAlchemy/PostgreSQL, and Alembic). Unsupported pairings fail before files are written.
+
+Authentication is intent-based. The generator selects Supabase Auth, a server-managed browser session, Sanctum SPA, or OIDC validation according to stack and audience. FastAPI uses OIDC bearer validation only; it does not offer session authentication.
+
+## Conditional capabilities
+
+- `--uploads=object-storage` adds private-upload authorization, limits, signature verification, generated names, quarantine/scanning, cleanup, and test expectations.
+- `--background-jobs=queue` adds bounded retry, timeouts, idempotency, failed jobs, observability, and replay rules.
+- `--offline=cache|sync` is mobile-only and defines ownership, keys, TTL, invalidation, privacy, reconnect states, and conflicts.
+
+Shared server caching is not automatic. Add it only for a measured use case with recorded ownership, keys, TTL, invalidation, privacy, and multi-instance behavior.

package/docs/compatibility.md

@@ -0,0 +1,13 @@
+# Compatibility profiles and upgrades
+
+Dated current and previous profiles own exact direct npm, Composer, and Python versions plus tested runtime and container versions. Definitions request package names only. Package managers validate peers, resolve transitive dependencies, and generate project-owned lockfiles (`package-lock.json`, `composer.lock`, `uv.lock`).
+
+Profiles are tested starting points, not permanent locks. Support and successor dates are recorded in `library/tested-versions.json`; promotion requires generated-project coverage and migration review.
+
+Existing projects are never modified automatically:
+
+```bash
+create-win-project upgrade-report .
+```
+
+The report describes profile, runtime, security-contract, and migration differences without writing files. Review dependency release notes and resolved lockfile changes before upgrading.

package/docs/generated-project.md

@@ -0,0 +1,12 @@
+# Understanding a generated project
+
+Every project contains runnable source, tests, stack-specific CI and security workflows, environment examples, setup and operations guides, plus production Docker or EAS files where applicable.
+
+`create-win-project.profile.json` records schema version 2, stack, dated profile, architecture, authentication, production guarantees, capabilities, and runtimes. It enables read-only comparisons without controlling future project changes.
+
+- `AGENTS.md` is the small always-on operating and authority contract.
+- `RULES.md` maps tasks to exact selected playbook sections.
+- `playbooks/` contains only knowledge applicable to the stack.
+- `CONTEXT.md` records product goals, decisions, capabilities, and approved deviations.
+
+Application behavior, tests, and framework configuration remain the source of truth when prose drifts.

package/docs/getting-started.md

@@ -0,0 +1,26 @@
+# Getting started
+
+Run the generator with Node.js 24 LTS or Docker. Generated projects list their own runtime requirements in `docs/guides/setup.md`.
+
+```bash
+npx create-win-project@latest
+```
+
+The interview asks for application shape, framework, backend/data boundary, architecture, authentication, and applicable capabilities. It can install dependencies and create lockfiles immediately.
+
+For development from a clone:
+
+```bash
+npm ci
+npm run doctor
+npm start
+```
+
+For a containerized generator:
+
+```bash
+docker compose build
+docker compose run --rm app
+```
+
+After generation, enter the new directory and follow its README. The CLI stages files before moving them into place and refuses to overwrite a non-empty destination.

package/docs/{ARCHITECTURE.md → maintainers/architecture.md}

@@ -1,4 +1,4 @@
-# Architecture (completed — v1.4.0 target)
+# Architecture
 
 `create-win-project` composes a validated project specification into two coordinated outputs:
 
@@ -124,7 +124,7 @@ Exactly one profile is `current` and one is `previous`. The current profile is t
 | `RULES.md` | Generated concern-to-playbook section router. |
 | `playbooks/` | Reusable standards, recipes, rationale, and stack guidance. |
 | `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. |
+| `docs/maintainers/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.
 
@@ -147,7 +147,7 @@ Canonical Markdown code examples should progressively move into extracted fixtur
 
 ## Extension workflow
 
-When adding a stack or capability (see `docs/CONTRIBUTING.md` for the full checklist):
+When adding a stack or capability (see `docs/maintainers/contributing.md` for the full checklist):
 
 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.