create-win-project 1.3.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,187 +1,85 @@
-```
- ██╗    ██╗  ██╗ ███╗  ██╗
- ██║    ██║ ███║ ████╗ ██║
- ██║ █╗ ██║ ╚██║ ██╔██╗██║
- ██║███╗██║  ██║ ██║╚████║
- ╚███╔███╔╝  ██║ ██║ ╚███║
-  ╚══╝╚══╝   ╚═╝ ╚═╝  ╚══╝
-
- █▀█ █▀█ █▀█   █ █▀▀ █▀▀ ▀█▀
- █▀▀ █▀█ █ █   █ █▀  █    █
- █   █ █ █▄█ █▄█ █▄▄ █▄▄  █
-```
-
-# Are you confused creating architecture rules, AGENTS.md, and folder structures from scratch every time you pick a new stack?
-
-> **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)
-[![Manifest-driven](https://img.shields.io/badge/architecture-manifest--driven-blue)](./playbooks)
-[![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
-
----
+<div align="center">
+  <img src="./public/logo.svg" alt="W1N Project logo" width="160">
+  <h1>W1N PROJECT</h1>
+  <p>Generate a tested, production-oriented web or mobile project with stack-specific code, CI, deployment artifacts, documentation, and agent guidance.</p>
+</div>
 
-## Why this exists
+## Start
 
-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` — they are generated inside your project (`package.json` devDeps + `.prettierrc` + `.editorconfig` + `eslint.config` via `lib/scaffold.js`).
-- 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 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 |
-| **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.
-
-> 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.
-- **Manifest-driven** — `*.manifest.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.
-
-## 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 manifest. |
-| `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 `playbooks/**/*.manifest.json` and resolves a *stack*:
-
-```jsonc
-// playbooks/stack/nextjs.manifest.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 `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.
-
-## 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
-
-## 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 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

@@ -0,0 +1,95 @@
+import fs from 'fs-extra'
+
+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'
+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', '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' || 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') || caseName.includes('fastapi')) {
+    if (caseName.startsWith('laravel-') && caseName !== 'laravel-api') base.push({ authentication: 'yes', audience: 'website' })
+    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
+}
+
+const current = catalog.defaultProfile
+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'],
+  ['nextjs-supabase', 'medium', 'yes', 'website'],
+  ['react-springboot', 'large', 'yes', 'website'],
+  ['react-native-supabase', 'medium', 'yes', 'multi-client'],
+  ['react-native-springboot', 'small', 'yes', 'multi-client'],
+  ['laravel-api', 'medium', 'not-yet', 'multi-client'],
+  ['laravel-blade', 'small', 'yes', 'website'],
+  ['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.
+const full = [...currentFull, ...allProfiles.filter((entry) => entry.profile !== current && matchesSmoke(entry))]
+
+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)
+  .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/{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) => {
@@ -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: 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] [--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/{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}`)
     }
   }
@@ -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('stack/') || relative.startsWith('platform/') || relative.startsWith('capabilities/') ? 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

@@ -0,0 +1,29 @@
+import { pathToFileURL } from 'node:url'
+import impact from '../library/compatibility-impact.json' with { type: 'json' }
+
+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) => 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(([, 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
+  }
+  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/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.