create-win-project 1.3.0 → 2.0.0

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/maintainers/architecture.md

@@ -0,0 +1,161 @@
+# Architecture
+
+`create-win-project` composes a validated project specification into two coordinated outputs:
+
+1. a small executable application that establishes the stack's real conventions;
+2. a task-routed documentation layer for humans and coding agents.
+
+Executable behavior, tests, and framework configuration are the source of truth. Playbooks explain and extend that behavior; they must not contradict it.
+
+## Generation pipeline
+
+```text
+CLI interview
+    ↓
+validated answers
+    ↓
+available-stacks + resolve-project + load-library + tested-versions
+    ↓
+resolved stack descriptor
+    ├── 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
+```
+
+### Source ownership (completed)
+
+Three explicit source boundaries. No `lib/` directory exists — `src/` is canonical.
+
+- `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.
+
+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.
+
+`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.
+
+### Catalog and resolution
+
+`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' }],
+  }
+})
+```
+
+- **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 (`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:
+
+- identity and compatibility (`id`, `kind`, `appliesTo`);
+- dependency names and scripts (never dependency versions);
+- semantic environment names and which ones are client-visible;
+- supported architecture profiles, conditional playbooks, and optional templates;
+- constraints shown to the agent;
+- concerns and their playbook sections.
+
+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 (stack-owned vertical)
+
+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
+
+`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; 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
+
+| File | Responsibility |
+|------|----------------|
+| `AGENTS.md` | Small always-on command, workflow, safety, and definition-of-done contract. |
+| `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 generator (ARCHITECTURE, CONTRIBUTING, etc.), not generic framework teaching. |
+| `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.
+
+## Testing strategy
+
+The generator itself has three verification levels:
+
+1. unit tests for catalog composition and template rendering;
+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 (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.
+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/maintainers/ci-strategy.md

@@ -0,0 +1,46 @@
+# CI and Branch Protection
+
+`dev` is the integration branch and `main` is the protected release-ready branch. Use merge
+commits for feature branches so contribution history remains visible.
+
+## Required checks
+
+| Pull request | Required checks | Coverage |
+|---|---|---|
+| feature → `dev` | `quality`, `compatibility-gate` | Repository tests plus 10 current-profile smoke projects |
+| `dev` → `main` | `quality`, `compatibility-gate` | Every current/previous contract plus representative native and container lanes |
+
+Configure both branches to require pull requests, resolve conversations, reject force pushes and
+deletions, and require branches to be current before merging. Restrict direct pushes to `main`.
+Do not require individual matrix job names; require the stable `compatibility-gate` aggregator.
+
+Required workflows intentionally have no path filters. A skipped workflow cannot report its check,
+which can leave a required pull request waiting forever or accidentally encourage bypasses.
+
+## Manual verification
+
+`Generated compatibility` can be started with `workflow_dispatch`. Choose `full` before changing a
+compatibility default or investigating a release candidate; choose `smoke` for a quick diagnostic.
+The pull-request base branch still determines automatic scope: `dev` gets smoke, `main` gets full.
+
+The quality suite runs once per revision. The full matrix generates every supported combination
+and checks its metadata contract. Representative risk-bearing lanes additionally install and run
+native tooling; one current-profile lane per container family builds images. This avoids repeating
+the same expensive installation or image build across hundreds of structurally equivalent cases.
+
+## Definition of done for generated behavior
+
+Repository unit tests are necessary but are not sufficient evidence for a generator change. For
+each affected stack shape, verification must generate a project in a temporary directory and use
+that project's native tools to exercise the behavior users receive:
+
+1. Install the exact profile dependencies without weakening install-script controls.
+2. Run the generated formatter, linter, type checker, and tests.
+3. Apply migrations to the declared database, then check for migration drift.
+4. Build the application and validate Compose; build containers for full verification.
+5. Exercise each affected root layout, architecture profile, and authentication model.
+
+A warning may be reported separately, but a failed native command is a failed implementation.
+Do not approve a PR based only on generated file presence, string assertions, fixture hashes, or
+the agent's completion statement. The stable `compatibility-gate` is the executable acceptance
+boundary.

package/docs/{CONTENT_MODEL.md → maintainers/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.

package/docs/maintainers/contributing.md

@@ -0,0 +1,154 @@
+# Contributing
+
+See `docs/maintainers/architecture.md` for source ownership and `docs/maintainers/dependencies.md` for profile promotion. This file is the workflow, not the design.
+
+## Quick start
+
+1. Fork and create a feature branch from `dev`.
+2. `npm ci` — Node 22.14+ with npm 11.19+ required (tested on Node 24).
+3. `npm test` must stay green. No global `prettier`/`eslint`/`typescript` needed — they are generated inside your project.
+
+## Adding a stack — plan first, then declare, then build
+
+A stack is **planned content first, then a declaration in `library/`, then executable code in `src/stacks/`**. `library/` never contains business entities — it declares *what* the stack supports; `src/stacks/<id>/create-files.js` implements *how* those files are generated. Do not start with code; start with the content model.
+
+### 0. Plan your stack's content (before touching `library/`)
+
+Answer these 5 questions and write them down (a short RFC or issue is enough). If you can't answer them, you can't write a `definition.json` yet.
+
+**a. Identity & compatibility:** What `id` (`django`, `nuxt`), `kind` (`frontend`|`backend`|`data`), `label` (`Django (Python)`), and which existing stacks can it pair with? Example: `nextjs` pairs with `none,postgres,supabase,springboot,laravel`; `react-native` pairs with `none,supabase,springboot,laravel`; `laravel` pairs with `nextjs,react,react-native,no-frontend,laravel-ui`.
+
+**b. Shapes:** Which **applicationShapes** does it enable? Shapes are the *deployment layout*, not the framework. They determine valid `frontend + backend` combos via `lib/application-shapes.js` → `src/engine/project-shapes.js`:
+
+| Shape | Meaning | Example combos |
+|-------|---------|---------------|
+| `fullstack` | One project owns website + server | `nextjs+none`, `nextjs+postgres`, `laravel-ui+laravel` |
+| `separate` | Two apps via API: frontend + backend API | `nextjs+springboot`, `react+supabase`, `react+laravel` |
+| `api` | Backend API only, no generated website | `no-frontend+springboot`, `no-frontend+laravel` |
+| `mobile` | Expo app + API/managed data | `react-native+supabase`, `react-native+springboot` |
+| `frontend` | Browser-only, no generated server | `react+none` |
+
+You don't invent a new shape — you pick from these 5. If `nextjs+django` should be fullstack, add `django` to `fullstack`'s `VALID_COMBINATIONS`. `inferApplicationShape({frontend,backend})` will then infer it; `validateApplicationShape` rejects invalid pairings.
+
+**c. Architecture & auth:** Which `architectureProfiles` (`small,medium,large` — all 3 required for frontends/backends) and which `authenticationModels` (`public,undecided,supabase,session,oidc,laravel-session,sanctum-spa,laravel-oidc`)? Example: `supabase` → `supabase`, `springboot` website → `session`, `springboot` multi-client → `oidc`.
+
+**d. Playbooks & concerns:** Which 5 facets does the stack need? Every stack needs `architecture.md, structure.md, runtime.md, security.md, testing.md` under `playbooks/stack/<id>/`. Which optional concerns (validation `zod`, state `zustand`, etc.) will it surface? Each concern has one home — don't duplicate prose in `AGENTS.md`.
+
+**e. Dependencies & env:** Which npm/composer package *names* and *scripts* will this stack generate, and which env var *names* (semantic, no prefix)? Example: `deps: ["next","react"]`, `env: ["DATABASE_URL"]`, `clientEnv: ["API_URL"]` — the engine will prefix `API_URL` once (`NEXT_PUBLIC_API_URL`). Never put a version here.
+
+If a new stack needs a runtime (`node`, `java`, `php`), add its version to `library/tested-versions.json` (current profile), not to the definition.
+
+### 1. Declare capability in `library/` (no executable logic yet)
+
+- Add `library/stacks/<id>/definition.json`:
+
+  ```json
+  {
+    "id": "django",
+    "kind": "backend",
+    "label": "Django (Python)",
+    "appliesTo": { "frontend": ["nextjs","react","no-frontend"] },
+    "architectureProfiles": ["small","medium","large"],
+    "playbooks": ["stack/django/architecture.md","stack/django/structure.md","stack/django/runtime.md","stack/django/security.md","stack/django/testing.md"],
+    "deps": ["django"],
+    "env": ["DATABASE_URL"],
+    "clientEnv": [],
+    "concerns": [{ "id": "validation", "required": false, "when": "runtime validation needed", "sections": ["Zod for Runtime Validation"] }]
+  }
+  ```
+
+  - `deps`/`devDeps` are **names only** — never versions or ranges. Exact versions live only in `library/tested-versions.json`.
+  - `env` are semantic names (`DATABASE_URL`); `clientEnv` subset gets the frontend prefix (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`).
+
+- Add `playbooks/stack/<id>/{architecture,structure,runtime,security,testing}.md` — the five facets. Keep each file focused; route concerns via definition `concerns[]`, not duplication. Check `docs/maintainers/content-model.md` — every concern section must match a Markdown heading (numbered headings normalized).
+
+- Run: `node checks/check-library.js` — catches duplicate ids, unknown dep names, `clientEnv` not in `env`, missing labels, heading mismatches.
+
+### 2. Create stack directory (one place, owns everything specific to that stack)
+
+```
+src/stacks/<frontends|backends>/<id>/
+  index.js            # defineStackAdapter({ id, kind, label, compatibleWith, capabilities, contributes })
+  create-files.js     # (answers, context) -> FileMap — ALL files this stack generates (pure function)
+  dependencies.js     # optional: { deps: [], devDeps: [], scripts: {} } — names/scripts only
+  environment.js      # optional: ["API_URL","DATABASE_URL"] — semantic env names
+  auth/               # for Laravel-style stacks: session.js, sanctum.js, oidc.js, public.js
+  ui/                 # for Laravel-style stacks: blade.js, livewire.js, inertia-react.js, shared.js
+```
+
+Use `src/stacks/backends/laravel/` as the reference (13 files, 363-line `create-files.js` + `auth/` + `ui/` + `composer.js` + `architecture.js`). `src/stacks/frontends/nextjs/` is the minimal vertical.
+
+`create-files.js` receives a read-only context from `src/stacks/available-stacks.js` + `src/engine/load-library.js` — it returns contributions, it never writes files or installs tools directly.
+
+```js
+// src/stacks/backends/django/index.js
+import { defineStackAdapter } from '../../rules.js'
+export const djangoAdapter = defineStackAdapter({
+  id: 'django', kind: 'backend', label: 'Django (Python)',
+  compatibleWith: { frontend: ['nextjs','react','no-frontend'] },
+  capabilities: { applicationShapes: ['fullstack','api'], architectureProfiles: ['small','medium','large'], authenticationModels: ['public','undecided','session'] },
+  contributes: {
+    environment: () => ['DATABASE_URL'],
+    install: () => [{ cwd: 'backend', command: 'pip', args: ['install','-r','requirements.txt'] }],
+    docker: () => [{ template: 'django', developmentPath: 'Dockerfile.dev' }],
+    ci: () => [{ template: 'django', path: '.github/workflows/ci-backend.yml' }],
+  }
+})
+```
+
+### 3. Register once (explicit, no scanning)
+
+`src/stacks/available-stacks.js` — add one import and one array entry:
+
+```js
+import { djangoAdapter } from './backends/django/index.js'
+export const stackRegistry = createStackRegistry([..., djangoAdapter])
+```
+
+This is the **only** list of available adapters. Adding a file never silently activates a stack.
+
+### 4. Add tests and matrix entries
+
+- `tests/stacks/<id>/` — at least: files exist, env prefix, large-arch boundary, auth metadata.
+- `checks/check-compatibility.js` — add `'<frontend>-<backend>'` to `cases[]` and to `smokeSelections[]`.
+- `templates/` — add `docker/dockerfile/django.dev.dockerfile`, `templates/ci/django.yml` etc. as static templates.
+
+### 5. Verify (focused, not full matrix every time)
+
+```bash
+npm test
+node checks/check-library.js
+node checks/check-compatibility.js --scope=stack --stack=<id> | head
+npm run verify:generated -- --profile=$(jq -r .defaultProfile library/tested-versions.json) --case=<frontend>-<backend> --architecture=medium --authentication=yes
+```
+
+- `verify:generated` compares byte-identical output via `generateProject` vs legacy shim for your new stack.
+- Run `npm run matrix:smoke` (10 smoke projects) before any `feature -> dev` PR.
+- Full matrix `npm run matrix:full` (every profile x stack x arch x auth, with install/build/Maven/Expo/Compose checks) is only required on `dev -> main` promotion per `docs/maintainers/ci-strategy.md`.
+
+### 6. Docs (only if ownership changed)
+
+Update `docs/maintainers/architecture.md` only if source ownership or the generation pipeline changed — not for every stack. If you added concerns/playbooks, verify `docs/maintainers/content-model.md` checklist (concern has one home, `RULES.md` sections resolve).
+
+## Testing and PRs
+
+- Required checks per `docs/maintainers/ci-strategy.md`:
+  - `feature -> dev`: `quality` + `compatibility-gate` (repository tests + 10 smoke projects)
+  - `dev -> main`: `quality` + `compatibility-gate` (every profile x stack x arch x applicable auth)
+
+- Contribution history: use merge commits for feature branches so history remains visible. Do not require individual matrix job names; require the stable `compatibility-gate` aggregator.
+
+- `tests/architecture-boundaries.test.js` enforces `src/engine` not importing `cli`/`stacks/frontends|backends` and `src/stacks` not importing `cli`/`engine` (except `shared/scaffold` allowlist). `tests/architecture/no-lib-legacy.test.js` bans `src/** -> lib/**` imports and one-line wrapper regressions (no `lib/` exists).
+
+## Version ownership
+
+Exact versions belong only to `library/tested-versions.json`. Never add a version to a `definition.json` or a `create-files.js`. `packageVersion(profile, name, capability)` and `composerPackageVersion(profile, name)` are the only version sources; they reject ranges and unknown package requests. See `docs/maintainers/dependencies.md` for current/previous profile promotion and Renovate flow.
+
+## Docs workflow
+
+- `AGENTS.md` — tiny always-on contract; keep short.
+- `RULES.md` — lazy index `concern -> playbook §`; generated per project, read only what you touch.
+- `playbooks/` — reusable standards; add the five facets per stack (`architecture.md`, `structure.md`, `runtime.md`, `security.md`, `testing.md`).
+- `docs/guides/` inside generated projects — architecture, API, setup, deployment for *this* product.
+
+Do not advertise a capability solely because a playbook mentions it. A generated capability must have executable configuration and contract coverage. For questions, read `docs/maintainers/architecture.md` first, then this file.

package/docs/{DEPENDENCY_MAINTENANCE.md → maintainers/dependencies.md}

@@ -1,6 +1,6 @@
 # Dependency maintenance
 
-`compatibility/profiles.json` is the only owner of versions emitted into generated applications. Stack and concern manifests declare package names and capabilities, never ranges or versions. Direct npm dependencies are generated as exact versions, and consumers commit the lockfile created by their first install.
+`library/tested-versions.json` is the only owner of versions emitted into generated applications. Stack and concern definitions declare package names and capabilities, never ranges or versions. Direct npm dependencies are generated as exact versions, and consumers commit the lockfile created by their first install.
 
 ## Profile policy
 

package/docs/migration-v2.md

@@ -0,0 +1,13 @@
+# Migrating from 1.x to 2.0
+
+Version 2 never overwrites or automatically upgrades an existing project. Commit or back up the project first, generate a new version-2 project with equivalent stack choices, and compare it with the existing application.
+
+1. Run `create-win-project upgrade-report .` when a profile exists; otherwise inventory runtimes, direct dependencies, authentication, CI, deployment, and operations manually.
+2. Adopt `create-win-project.profile.json` schema 2 and record the stack, dated compatibility profile, production baseline, and capabilities.
+3. Replace optional/no-test paths with the stack default: full web coverage (including Playwright) or Jest plus React Native Testing Library for Expo.
+4. Install exact direct versions in a clean working tree and commit the package-manager lockfile. Review resolved transitive and peer changes.
+5. Port hardened production artifacts and operations guidance. Keep development Docker optional.
+6. Select uploads, queues, or mobile offline behavior only when required; do not infer them from 1.x advisory concerns.
+7. Run lint, typecheck, tests, production builds/exports, Compose parsing, and relevant container/database/capability checks before replacing the old baseline.
+
+Treat generated files as reference implementations during migration. Merge application-specific behavior deliberately and record approved architecture, provider, authentication, data, or major dependency deviations in `CONTEXT.md`.

package/docs/production-contract.md

@@ -0,0 +1,24 @@
+# Version 2 production contract
+
+Version 2 generates a tested, stack-appropriate production baseline. It guarantees deterministic files for the recorded schema-v2 profile, exact tested direct dependency requests, standard tests and CI, production builds, security rules, operations guidance, and cloud-neutral Docker artifacts for deployable web stacks. Expo projects receive an EAS-ready baseline, not automatic store submission.
+
+The guarantee is a starting contract, not a claim that an unfinished product is safe to launch. Teams still own domain authorization, infrastructure sizing, secrets, observability targets, data classification, compliance, external-provider configuration, device verification, deployment, backups, and restore drills.
+
+## Dependency ownership
+
+`library/tested-versions.json` owns exact direct npm and Composer versions for current and retained profiles. npm and Composer validate peer ranges, resolve transitive packages, and create lockfiles during installation. Generated projects own and commit those lockfiles; the generator does not freeze or silently upgrade their transitive graph.
+
+## Standard baseline
+
+- Tests, lint/type checks, production builds, CI, security rules, environment validation, and operations documentation are standard.
+- Vite production uses non-root nginx with SPA fallback, security headers, safe cache policy, and API `no-store`; Next.js retains framework-native caching.
+- Server/database stacks document readiness, graceful shutdown, pooling, migration preflight, encrypted backups, restore verification, retention, deployment, and rollback.
+- Development Docker remains optional. Shared Redis caching, queues, object storage, offline synchronization, and malware scanning appear only for a supported explicit requirement.
+
+## Conditional capabilities
+
+Private uploads define authorization, size/signature checks, generated names, quarantine/scanning, cleanup, and rejection tests. Queues define bounded retry, idempotency, timeouts, failed-job handling, correlation, and replay. Mobile cache/sync defines ownership, key namespaces, TTL, invalidation, privacy, reconnect states, and conflict handling. Unsupported combinations fail before any destination is written.
+
+## Support and recovery
+
+The current and previous dated profiles are supported through their catalog dates. Run `create-win-project upgrade-report [path]` for a read-only comparison; it never modifies an existing project. Major deviations require approval and a decision record in generated `CONTEXT.md`.