create-win-project 1.4.0 → 2.0.0

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/{CONTRIBUTING.md → maintainers/contributing.md}

@@ -1,6 +1,6 @@
 # Contributing
 
-See `docs/ARCHITECTURE.md` for completed source ownership and `docs/DEPENDENCY_MAINTENANCE.md` for profile promotion. This file is the workflow, not the design.
+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
 
@@ -60,7 +60,7 @@ If a new stack needs a runtime (`node`, `java`, `php`), add its version to `libr
   - `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/CONTENT_MODEL.md` — every concern section must match a Markdown heading (numbered headings normalized).
+- 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.
 
@@ -124,15 +124,15 @@ npm run verify:generated -- --profile=$(jq -r .defaultProfile library/tested-ver
 
 - `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/CI_STRATEGY.md`.
+- 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/ARCHITECTURE.md` only if source ownership or the generation pipeline changed — not for every stack. If you added concerns/playbooks, verify `docs/CONTENT_MODEL.md` checklist (concern has one home, `RULES.md` sections resolve).
+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/CI_STRATEGY.md`:
+- 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)
 
@@ -142,7 +142,7 @@ Update `docs/ARCHITECTURE.md` only if source ownership or the generation pipelin
 
 ## 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/DEPENDENCY_MAINTENANCE.md` for current/previous profile promotion and Renovate flow.
+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
 
@@ -151,4 +151,4 @@ Exact versions belong only to `library/tested-versions.json`. Never add a versio
 - `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/ARCHITECTURE.md` first, then this file.
+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/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`.

package/library/INDEX.md

@@ -55,4 +55,4 @@ Manifests compose capabilities; `lib/scaffold.js` owns their executable minimum.
 - `playbooks/`: only selected reusable guidance.
 - `docs/`: setup, API, architecture, auth, and deployment for the generated product.
 
-See `docs/CONTENT_MODEL.md` for authoring and deduplication rules and `docs/ARCHITECTURE.md` for the generation pipeline.
+See `docs/maintainers/content-model.md` for authoring and deduplication rules and `docs/maintainers/architecture.md` for the generation pipeline.

package/library/compatibility-impact.json

@@ -0,0 +1,14 @@
+{
+  "stacks": {
+    "nextjs": ["src/stacks/frontends/nextjs/", "library/stacks/nextjs/", "templates/agents/nextjs.", "templates/ci/nextjs."],
+    "react": ["src/stacks/frontends/react-vite/", "library/stacks/react-vite/", "templates/agents/react-vite.", "templates/ci/vite."],
+    "react-native": ["src/stacks/frontends/react-native/", "library/stacks/expo/", "templates/agents/react-native.", "templates/ci/expo."],
+    "springboot": ["src/stacks/backends/springboot/", "library/stacks/springboot/", "library/features/flyway/", "templates/ci/springboot."],
+    "fastapi": ["src/stacks/backends/fastapi/", "library/stacks/fastapi/", "library/features/sqlalchemy-alembic.md", "templates/ci/fastapi."],
+    "laravel": ["src/stacks/backends/laravel/", "library/stacks/laravel/", "library/features/laravel", "templates/ci/laravel."],
+    "supabase": ["src/stacks/backends/supabase/", "library/features/supabase/"],
+    "postgres": ["src/stacks/backends/postgres/", "library/features/postgresql/", "library/features/prisma/"],
+    "none": ["src/stacks/backends/none/"]
+  },
+  "shared": ["library/tested-versions.json", "lib/", "src/engine/", "src/stacks/shared/", "templates/docker/", "templates/gitignore/", "templates/makefile/", "checks/check-compatibility.js", "checks/check-generated-project.js"]
+}

package/library/development-tools/devops/makefile/commands.md

@@ -0,0 +1,11 @@
+# Make commands
+
+## Core Rules
+
+- Targets wrap documented project commands; they do not hide different behavior.
+- Declare non-file targets with `.PHONY`.
+- Use tabs for recipes and `$(VARIABLE)` for configurable values.
+- Keep the default target safe and read-only; `help` or `check` is preferred.
+- Fail on command errors and preserve the underlying exit status.
+
+Use small targets such as `install`, `dev`, `lint`, `test`, `build`, and `check`. Compose them instead of duplicating recipes.

package/library/development-tools/devops/makefile/definition.json

@@ -2,10 +2,10 @@
   "id": "makefile",
   "kind": "devops",
   "label": "Makefile",
-  "file": "devops/makefile.md",
+  "playbooks": ["capabilities/devops/makefile/commands.md", "capabilities/devops/makefile/docker.md", "capabilities/devops/makefile/validation.md"],
   "required": false,
   "folders": [],
   "concerns": [
-    { "id": "makefile", "required": true, "sections": ["Core Rules"] }
+    { "id": "makefile", "required": true, "playbook": "capabilities/devops/makefile/commands.md", "sections": ["Core Rules"] }
   ]
 }

package/library/development-tools/devops/makefile/docker.md

@@ -0,0 +1,9 @@
+# Make and Docker
+
+## Docker Targets
+
+- Keep image building separate from container startup.
+- `build` may run `docker compose build`; `run` must not rebuild implicitly.
+- Use the generated Compose file as the source of service names and profiles.
+- Never interpolate secrets into command output.
+- Destructive volume or database targets require explicit names and confirmation.

package/library/development-tools/devops/makefile/validation.md

@@ -0,0 +1,5 @@
+# Make validation
+
+## Validation Targets
+
+`check` should compose the same lint, typecheck, test, and build commands used by CI. Keep focused targets independently runnable, and avoid suppressing failures with leading `-`, `|| true`, or unconditional success messages.

package/library/features/sqlalchemy-alembic.md

@@ -0,0 +1,17 @@
+# SQLAlchemy and Alembic
+
+## Session Ownership
+
+Use SQLAlchemy 2 async sessions with `asyncpg`. Services own session and transaction
+boundaries spanning multiple writes or read-modify-write behavior. Routers never manage
+sessions directly; they receive a session dependency from shared core infrastructure.
+
+Database unique/check/foreign-key constraints are the final concurrency boundary; map
+expected constraint conflicts to stable application errors.
+
+## Migrations
+
+Alembic owns all schema changes. Generate revisions explicitly and apply them with
+`alembic upgrade head` from the backend directory. Application startup must not
+automatically migrate production databases. Verify migration configuration and upgrade
+checks in CI before container builds.

package/library/optional-features/concerns/zod/errors.md

@@ -0,0 +1,5 @@
+# Zod validation errors
+
+## Safe Validation Errors
+
+Convert issues to stable field/code structures at the boundary. Do not expose internal paths, secrets, provider payloads, or raw exception text. Log diagnostic context server-side with request correlation and privacy filtering.

package/library/optional-features/concerns/zod/testing.md

@@ -0,0 +1,5 @@
+# Testing Zod schemas
+
+## Schema Tests
+
+Test valid boundaries, missing required values, wrong types, limits, unknown keys, and security-sensitive malformed input. Prefer small representative fixtures and assert stable error codes rather than complete library messages.

package/library/optional-features/concerns/zod/validation.md

@@ -0,0 +1,21 @@
+# Runtime validation with Zod
+
+## Agent Quick Reference
+
+Parse untrusted values once at their owning boundary, use the inferred type internally, and return safe structured errors.
+
+## Schema First, Always
+
+Define the runtime contract before consuming external data. Use strict schemas for requests, environment variables, persisted data, and provider responses. Apply coercion only when the transport contract explicitly permits it.
+
+## Zod Schema Placement
+
+Place a schema at the boundary that owns the contract. Feature schemas stay with the feature; shared protocol schemas live in a dependency-neutral contract module. Export inferred types rather than duplicating shapes.
+
+## Web Form (React Hook Form)
+
+Use the schema resolver at submission boundaries, show field errors accessibly, and validate again on the server. Client validation improves feedback but never establishes trust.
+
+## React Native Form (React Hook Form + Controller)
+
+Wrap controlled native inputs with `Controller`, preserve accessible labels and errors, and validate the same transport contract again at the trusted server boundary.

package/library/optional-features/styling/css-modules/definition.json

@@ -2,10 +2,11 @@
   "id": "css-modules",
   "kind": "styling",
   "label": "CSS Modules",
-  "file": "styling/css-modules-extensions.md",
+  "playbooks": ["styling/css-modules/theme.md", "styling/css-modules/responsive.md"],
   "required": false,
   "folders": [],
   "concerns": [
-    { "id": "styling", "required": true, "sections": ["Dark Mode with CSS Variables", "Responsive in Module File"] }
+    { "id": "styling-theme", "required": true, "playbook": "styling/css-modules/theme.md", "sections": ["Dark Mode with CSS Variables"] },
+    { "id": "styling-responsive", "required": true, "playbook": "styling/css-modules/responsive.md", "sections": ["Responsive in Module File"] }
   ]
 }

package/library/optional-features/styling/css-modules/responsive.md

@@ -0,0 +1,5 @@
+# CSS Modules responsive layout
+
+## Responsive in Module File
+
+Keep component breakpoints beside the component styles. Start with the narrow layout, add only measured breakpoints, and prefer container-aware layout when the component is reusable. Avoid global selectors and viewport assumptions inside modules.

package/library/optional-features/styling/css-modules/theme.md

@@ -0,0 +1,7 @@
+# CSS Modules theming
+
+## Dark Mode with CSS Variables
+
+Define semantic color and spacing variables at the application theme boundary. Switch variable values through the selected theme mechanism; components consume semantic tokens and must not duplicate light/dark selectors.
+
+Respect system preference by default, preserve explicit user choice, and maintain accessible contrast in every supported theme.

package/library/stacks/expo/definition.json

@@ -4,7 +4,7 @@
   "label": "React Native (Expo)",
   "language": "TypeScript",
   "platform": "mobile",
-  "appliesTo": { "backend": ["supabase", "springboot", "laravel", "none"] },
+  "appliesTo": { "backend": ["supabase", "springboot", "laravel", "none", "fastapi"] },
   "port": 8081,
   "needsDocker": false,
   "frontendDir": "",
@@ -44,6 +44,6 @@
     { "id": "http-client", "required": false, "when": "The app adopts Axios for a REST API", "playbook": "concerns/axios.md", "sections": ["One Shared Client", "Service Calls apiClient, Hook Calls Service"] },
     { "id": "query", "required": false, "when": "The app needs cached remote server state", "playbook": "concerns/tanstack-query.md", "sections": ["Read Hook", "Mutation Hook", "QueryClient Setup"] },
     { "id": "state", "required": false, "when": "Shared state across multiple screens", "playbook": "concerns/zustand.md", "sections": ["Store Setup", "Auth Store Pattern"] },
-    { "id": "validation", "required": false, "when": "Project has forms", "playbook": "concerns/zod.md", "sections": ["Schema First, Always", "React Native Form (React Hook Form + Controller)"] }
+    { "id": "validation", "required": false, "when": "Project has forms", "playbook": "concerns/zod/validation.md", "sections": ["Schema First, Always", "React Native Form (React Hook Form + Controller)"] }
   ]
 }

package/library/stacks/fastapi/architecture.md

@@ -0,0 +1,40 @@
+# FastAPI Architecture
+
+## Profiles
+
+### Small
+
+Use a compact application package with configuration, database, security, and route
+modules. Do not add service/repository layers that have only one caller or split a
+simple operation into ceremonial layers.
+
+```text
+HTTP → Router → Service function → AsyncSession → PostgreSQL
+```
+
+### Medium (default)
+
+Keep feature-oriented routers, services, repositories, schemas, and shared core
+infrastructure explicit. Services own transaction boundaries and reusable operations.
+Features communicate through clear service APIs rather than reaching into repositories.
+
+### Large
+
+Build bounded feature modules with explicit public module interfaces. A feature exposes
+a small router/service API and keeps repository and schema implementation internal.
+Verify no cycles, no access to internals, and only declared module dependencies with
+the generated architecture-boundary tests. Large does not mean microservices.
+
+## Dependency Direction
+
+```text
+web/API → application operation → domain policy → persistence/external adapter
+```
+
+- Routers translate HTTP and never touch the database session directly.
+- Services do not return HTTP responses or depend on route details.
+- Repositories contain persistence queries, not application policy.
+- Cross-feature work calls a public operation or publishes a deliberate event.
+- External side effects are not assumed successful merely because a transaction commits.
+
+Start at the selected project baseline and let each feature create only the files it uses.

package/library/stacks/fastapi/definition.json

@@ -0,0 +1,39 @@
+{
+  "id": "fastapi",
+  "kind": "backend",
+  "label": "FastAPI",
+  "language": "Python",
+  "appliesTo": { "frontend": ["nextjs", "react", "react-native", "no-frontend"] },
+  "port": 8000,
+  "needsDocker": true,
+  "architectureProfiles": ["small", "medium", "large"],
+  "playbooks": [
+    "stack/fastapi/architecture.md",
+    "stack/fastapi/structure.md",
+    "stack/fastapi/runtime.md",
+    "stack/fastapi/security.md",
+    "stack/fastapi/testing.md",
+    "capabilities/sqlalchemy-alembic.md",
+    { "file": "capabilities/auth/oidc-resource-server.md", "appliesWhen": { "authentication": "oidc" } }
+  ],
+  "makefileTemplate": "fastapi",
+  "folders": [],
+  "deps": [],
+  "devDeps": [],
+  "env": ["API_URL", "DATABASE_URL", "POSTGRES_USER", "POSTGRES_PASSWORD", "POSTGRES_DB", "OIDC_ISSUER", "OIDC_AUDIENCE", "OIDC_ALGORITHMS", "OIDC_JWKS_URL", "CORS_ALLOWED_ORIGINS"],
+  "clientEnv": ["API_URL"],
+  "constraints": [
+    "FastAPI owns server-side business logic, authorization, and data access",
+    "Security starts deny-by-default; add authentication through OIDC bearer validation rather than hand-rolled token code",
+    "Application startup must not automatically migrate production databases"
+  ],
+  "concerns": [
+    { "id": "architecture", "required": true, "playbook": "stack/fastapi/architecture.md", "sections": ["Profiles", "Dependency Direction"] },
+    { "id": "structure", "required": true, "playbook": "stack/fastapi/structure.md", "sections": ["Package by Feature"] },
+    { "id": "runtime", "required": true, "playbook": "stack/fastapi/runtime.md", "sections": ["Configuration and Lifecycle", "Errors and Observability"] },
+    { "id": "stack-security", "required": true, "playbook": "stack/fastapi/security.md", "sections": ["Authentication Models", "Authorization"] },
+    { "id": "stack-testing", "required": true, "playbook": "stack/fastapi/testing.md", "sections": ["Test Layers"] },
+    { "id": "persistence", "required": true, "playbook": "capabilities/sqlalchemy-alembic.md", "sections": ["Session Ownership", "Migrations"] },
+    { "id": "oidc-auth", "required": true, "appliesWhen": { "authentication": "oidc" }, "playbook": "capabilities/auth/oidc-resource-server.md", "sections": ["Provider and API Responsibilities", "Required Tests"] }
+  ]
+}

package/library/stacks/fastapi/runtime.md

@@ -0,0 +1,25 @@
+# FastAPI Runtime
+
+## Configuration and Lifecycle
+
+Configuration comes from validated Pydantic Settings and environment-specific deployment
+values. The application exposes public `GET /health` and dependency-aware `GET /ready`
+readiness separately. Readiness verifies dependencies required to serve traffic.
+
+Manage dependencies with uv and a frozen lockfile (`uv sync --frozen`). Run with
+Uvicorn. Keep schema changes owned by Alembic migrations invoked explicitly via
+`alembic upgrade head`; application startup must not automatically migrate production
+databases.
+
+## Errors and Observability
+
+Services raise typed application exceptions with stable error codes and no HTTP types.
+Exception handlers map them to RFC 9457 problem details. Include a safe code and
+trace ID; never expose stack traces, SQL, internal hosts, credentials, or sensitive fields.
+
+Use structured PII-safe events. Do not log whole requests, passwords, tokens, cookies, or
+email addresses by default.
+
+Configure exact-origin CORS from `CORS_ALLOWED_ORIGINS`. Store uploads outside the
+application tree under generated object keys; validate size and content and route
+untrusted files through the product's scanning/quarantine process.

package/library/stacks/fastapi/security.md

@@ -0,0 +1,26 @@
+# FastAPI Security
+
+## Authentication Models
+
+The generated authentication choice is authoritative:
+
+- `public`: no user accounts; generated application endpoints are intentionally public.
+- `undecided`: health is public and every other endpoint is denied until auth is designed.
+- `oidc`: an external identity provider owns login, refresh, rotation, and revocation;
+  FastAPI validates bearer issuer, audience, algorithm, JWKS signature, expiry, and claims
+  on every protected API request. Session authentication is not offered.
+
+Never turn the API into a home-grown authorization server from a short JWT example.
+
+## Authorization
+
+Route dependencies provide a broad baseline. Enforce feature permissions and resource
+ownership at the application operation or protected data boundary with explicit
+dependencies. Test unauthenticated, authenticated-but-forbidden, and allowed cases.
+
+- Keep public health endpoints separate from protected API routes.
+- Configure OIDC issuer, audience, allowed algorithms, JWKS retrieval, and claim
+  validation from environment; deny by default.
+- Configure exact-origin CORS. Never combine credentials with wildcard origin.
+- Rate limit login, recovery, and other abuse-sensitive operations.
+- Treat role claims as inputs to server policy, not proof of resource ownership.

package/library/stacks/fastapi/structure.md

@@ -0,0 +1,27 @@
+# FastAPI Structure
+
+## Package by Feature
+
+Place the application entrypoint in the `app` package. Organize business code below it by
+feature, never in one global router/service/repository layer.
+
+```text
+app/
+├── main.py
+├── core/               settings, database, security, logging (Medium/Large)
+├── modules/status/     router, service, repository, schemas (Large)
+├── features/status/    router, service, repository, schemas (Medium)
+└── routes_health.py    public health/readiness (Small)
+```
+
+Small may keep the few feature modules directly under `app/`. Medium uses the named
+`features/` packages when multiple files make ownership clearer. Large exposes types in
+the module base/`__init__.py` public interface and places implementation in submodules
+as required by the generated boundary tests.
+
+Backend-only projects live at the repository root. Paired backends live under `backend/`.
+
+- Use explicit imports; re-export only the public module interface from `__init__.py`.
+- Prefer Pydantic v2 models for transport schemas; keep ORM models persistence-only.
+- Do not invent users, products, or other business entities in the baseline.
+- Use database-native identity types and constraints deliberately.

package/library/stacks/fastapi/testing.md

@@ -0,0 +1,23 @@
+# FastAPI Testing
+
+## Test Layers
+
+| Risk | Test |
+|---|---|
+| Pure policy/value object | pytest unit test |
+| Service orchestration/error code | Focused unit test with boundary fakes |
+| Router validation/error/security | HTTPX async test without a database |
+| Custom repository/Alembic/constraints | PostgreSQL integration test |
+| Feature module | Module integration test |
+| Large boundaries | Generated boundary test (no internal imports) |
+
+Do not use SQLite as proof that PostgreSQL queries or migrations work. Standard CRUD
+methods need no dedicated test, but custom queries, constraints, locking, and migrations do.
+
+Test behavior and risk rather than every public function or mock call. Authentication tests
+cover missing bearer tokens and invalid issuer, audience, signature, expiry, and required
+claims. Authorization tests include resource ownership, not roles alone.
+
+Every profile runs `ruff check`, `ruff format --check`, `mypy`, and `pytest`. Full testing
+runs PostgreSQL integration tests; Large additionally fails on cycles and access to
+module internals.

package/library/stacks/nextjs/definition.json

@@ -4,7 +4,7 @@
   "label": "Next.js",
   "language": "TypeScript",
   "platform": "web",
-  "appliesTo": { "backend": ["none", "supabase", "springboot", "postgres", "laravel"] },
+  "appliesTo": { "backend": ["none", "supabase", "springboot", "postgres", "laravel", "fastapi"] },
   "port": 3000,
   "needsDocker": false,
   "frontendDir": "",
@@ -38,7 +38,7 @@
     { "id": "runtime", "required": true, "playbook": "stack/nextjs/runtime.md", "sections": ["Server and Client", "Caching and Mutations"] },
     { "id": "stack-security", "required": true, "playbook": "stack/nextjs/security.md", "sections": ["Authorization", "Sessions"] },
     { "id": "stack-testing", "required": true, "playbook": "stack/nextjs/testing.md", "sections": ["Test Layers"] },
-    { "id": "validation", "required": false, "when": "Project has forms / runtime input", "playbook": "concerns/zod.md", "sections": ["Schema First, Always", "Zod Schema Placement"] },
+    { "id": "validation", "required": false, "when": "Project has forms / runtime input", "playbook": "concerns/zod/validation.md", "sections": ["Schema First, Always", "Zod Schema Placement"] },
     { "id": "query", "required": false, "when": "Client needs cached server state", "playbook": "concerns/tanstack-query.md", "sections": ["Read Hook", "Mutation Hook"] },
     { "id": "state", "required": false, "when": "Shared non-server UI state", "playbook": "concerns/zustand.md", "sections": ["Store Setup"] },
     { "id": "env", "required": false, "when": "Validating env vars at build time", "playbook": "concerns/t3-env.md", "sections": ["Setup"] },

package/library/stacks/no-frontend/definition.json

@@ -3,7 +3,7 @@
   "kind": "frontend",
   "label": "No frontend",
   "platform": "api",
-  "appliesTo": { "backend": ["springboot", "laravel"] },
+  "appliesTo": { "backend": ["springboot", "laravel", "fastapi"] },
   "port": 0,
   "needsDocker": false,
   "frontendDir": "",

package/library/stacks/react-vite/definition.json

@@ -4,7 +4,7 @@
   "label": "React + Vite",
   "language": "TypeScript",
   "platform": "web",
-  "appliesTo": { "backend": ["none", "supabase", "springboot", "laravel"] },
+  "appliesTo": { "backend": ["none", "supabase", "springboot", "laravel", "fastapi"] },
   "port": 5173,
   "needsDocker": false,
   "frontendDir": "frontend",
@@ -39,7 +39,7 @@
     { "id": "stack-security", "required": true, "playbook": "stack/react-vite/security.md", "sections": ["Browser Trust Boundary"] },
     { "id": "stack-testing", "required": true, "playbook": "stack/react-vite/testing.md", "sections": ["Test Layers"] },
     { "id": "http-client", "required": false, "when": "The app adopts Axios instead of the native fetch client", "playbook": "concerns/axios.md", "sections": ["One Shared Client", "Service Calls apiClient, Hook Calls Service"] },
-    { "id": "validation", "required": false, "when": "Project has forms / runtime input", "playbook": "concerns/zod.md", "sections": ["Schema First, Always", "Web Form (React Hook Form)"] },
+    { "id": "validation", "required": false, "when": "Project has forms / runtime input", "playbook": "concerns/zod/validation.md", "sections": ["Schema First, Always", "Web Form (React Hook Form)"] },
     { "id": "query", "required": false, "when": "Client needs cached server state", "playbook": "concerns/tanstack-query.md", "sections": ["Read Hook", "Mutation Hook"] },
     { "id": "state", "required": false, "when": "Shared UI state across pages", "playbook": "concerns/zustand.md", "sections": ["Store Setup"] }
   ]