create-win-project 1.3.0

package/playbooks/platform/laravel-ui/inertia-react/runtime.md

@@ -0,0 +1,5 @@
+# Inertia React Runtime
+
+Use Inertia navigation/forms for Laravel routes and writes. Form Requests remain authoritative;
+React validation is UX only. Keep shared props small, send only necessary fields, use local/URL state
+for browser concerns, and add an API client only for a genuinely external browser-side service.

package/playbooks/platform/laravel-ui/inertia-react/security.md

@@ -0,0 +1,5 @@
+# Inertia React Security
+
+Props and browser bundles are public and modifiable. Laravel re-checks Policies/Gates beside every
+operation. Keep CSRF and secure session cookies, avoid broad CORS, allowlist redirects, and never put
+models, hidden fields, reset tokens, credentials, or unnecessary PII into page props.

package/playbooks/platform/laravel-ui/inertia-react/structure.md

@@ -0,0 +1,5 @@
+# Inertia React Structure
+
+Use `resources/js/pages` for route pages, `features/<name>` for reusable feature UI/hooks/types,
+`components/ui` for primitives, `layouts` for shells, and `lib` for adapters. Laravel-owned page data
+arrives as props; do not generate frontend repositories, stores, services, or API clients by habit.

package/playbooks/platform/laravel-ui/inertia-react/testing.md

@@ -0,0 +1,5 @@
+# Inertia React Testing
+
+Laravel feature tests prove route middleware, validation, authorization, component selection, safe
+prop shape, redirects, and writes. React Testing Library proves accessible rendering/interactions.
+Playwright covers critical navigation and auth journeys; Large checks public feature imports.

package/playbooks/platform/laravel-ui/livewire/architecture.md

@@ -0,0 +1,5 @@
+# Livewire Architecture
+
+Livewire components are server-driven UI adapters. Small may coordinate simple CRUD directly;
+Medium calls Actions/Services for meaningful workflows; Large namespaces components by module and
+enforces boundaries. Public component state is never a trusted domain boundary.

package/playbooks/platform/laravel-ui/livewire/runtime.md

@@ -0,0 +1,5 @@
+# Livewire Runtime
+
+Treat synchronized properties, event payloads, route values, and action arguments as untrusted.
+Validate and authorize every callable mutation, keep state small, and put transactions in the called
+application operation. Handle loading, empty, stale, retry, forbidden, and error states deliberately.

package/playbooks/platform/laravel-ui/livewire/security.md

@@ -0,0 +1,5 @@
+# Livewire Security
+
+Re-authorize every protected component action. Never expose sensitive model fields or secrets in
+public state or markup. Keep framework session/CSRF protections enabled, validate uploads and event
+arguments, throttle abuse-sensitive actions, and treat Alpine/browser JavaScript as untrusted.

package/playbooks/platform/laravel-ui/livewire/structure.md

@@ -0,0 +1,5 @@
+# Livewire Structure
+
+Choose one consistent supported component format. Route-level components own pages; interactive
+components own focused reactive state; Blade components own static reusable markup. Extract Form
+objects only for substantial form state, and align Large namespaces with module ownership.

package/playbooks/platform/laravel-ui/livewire/testing.md

@@ -0,0 +1,5 @@
+# Livewire Testing
+
+Component tests exercise public interactions, validation, authorization, state, upload handling,
+and rendered behavior. Test Actions, Services, Policies, transactions, and queries independently.
+Use Playwright only for critical complete journeys and verify Large module boundaries separately.

package/playbooks/platform/mobile.manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "mobile-platform",
+  "kind": "platform",
+  "label": "Mobile Platform",
+  "appliesTo": { "platform": ["mobile"] },
+  "deps": [],
+  "devDeps": [],
+  "env": [],
+  "clientEnv": [],
+  "constraints": [
+    "Treat the installed application as an untrusted public client",
+    "Handle foreground, background, offline, and deep-link lifecycle explicitly"
+  ],
+  "concerns": [
+    { "id": "mobile-platform", "required": true, "playbook": "platform/mobile.md", "sections": ["Device Boundary", "Lifecycle and Links"] }
+  ]
+}

package/playbooks/platform/mobile.md

@@ -0,0 +1,15 @@
+# Mobile Platform
+
+## Device Boundary
+
+An installed application cannot keep a server secret. Ship only public client identifiers; keep authorization and privileged operations on the server or in database policies. Store sessions in platform-protected secure storage, never plain preferences or AsyncStorage.
+
+## Lifecycle and Links
+
+Bind session refresh, subscriptions, and reconnect behavior to foreground/background lifecycle. Register exact application schemes and universal/app links. Validate every incoming deep link and allow only known destinations.
+
+Design remote work for intermittent connectivity, retries, duplicate delivery, and cancellation. Large offline-capable applications require explicit conflict resolution and observable synchronization state.
+
+## Device Experience
+
+Respect safe areas, text scaling, accessibility roles, reduced motion, permissions, and platform navigation conventions. Test behavior on representative devices; a web export is useful but does not replace native verification.

package/playbooks/platform/web.manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "web-platform",
+  "kind": "platform",
+  "label": "Web Platform",
+  "appliesTo": { "platform": ["web"] },
+  "deps": [],
+  "devDeps": [],
+  "env": [],
+  "clientEnv": [],
+  "constraints": [
+    "Treat browser code and browser-visible environment variables as public",
+    "Preserve semantic HTML, keyboard access, and progressive failure behavior"
+  ],
+  "concerns": [
+    { "id": "web-platform", "required": true, "playbook": "platform/web.md", "sections": ["Browser Boundary", "Navigation and Accessibility"] }
+  ]
+}

package/playbooks/platform/web.md

@@ -0,0 +1,17 @@
+# Web Platform
+
+## Browser Boundary
+
+Anything shipped to the browser is observable and modifiable. Public environment prefixes are configuration, never secret storage. Enforce authentication, resource authorization, validation, and trusted side effects on a server or at the data policy boundary.
+
+Use secure, HttpOnly cookies for server-managed sessions. Keep CSRF protection for cookie-authenticated mutations. Token refresh belongs to the selected identity SDK or server session implementation; do not add a competing generic interceptor.
+
+## Navigation and Accessibility
+
+Use links for navigation and buttons for actions. Preserve focus, keyboard operation, semantic landmarks, labels, loading feedback, and actionable errors. Prefer platform behavior over custom keyboard or history handling.
+
+Validate redirect targets against explicit same-origin allowlists. Do not accept arbitrary callback or `next` URLs.
+
+## Runtime Failures
+
+Model loading, empty, error, offline, unauthorized, and forbidden states explicitly. Cancel obsolete requests where the framework supports it, and do not display success before a trusted boundary confirms the mutation.

package/playbooks/stack/expo/architecture.md

@@ -0,0 +1,27 @@
+# Expo Architecture
+
+## Profiles
+
+### Small
+
+```text
+Expo Router screen → feature component → api/data function → trusted backend
+```
+
+### Medium (default)
+
+Features own their components, hooks, API/data functions, runtime schemas, and types.
+Platform session storage and lifecycle adapters remain shared infrastructure. Client
+Services may coordinate device/UI workflows but never replace server authorization.
+
+### Large
+
+Keep the Medium tree and add explicit feature public APIs, sync/offline policy, background
+tasks, platform adapters, contract tests, and native-device E2E. Add these only when the
+product needs them.
+
+## Dependency Direction
+
+Routes compose screens. Screens call features. Features call shared platform/transport
+adapters. Transport code never imports navigation or visual components. The backend or
+Supabase RLS remains the trusted policy boundary.

package/playbooks/stack/expo/runtime.md

@@ -0,0 +1,14 @@
+# Expo Runtime
+
+## Lifecycle and Remote State
+
+- Re-evaluate session and stale remote state when the app returns to the foreground.
+- Cancel work that outlives a screen; do not retry writes without idempotency analysis.
+- Design loading, offline, empty, error, retry, and conflict states.
+- Persist only the minimum state that must survive termination.
+- Use route params for navigation state, a query cache for remote state when justified,
+  and a client store only for genuinely cross-screen client state.
+- Every `EXPO_PUBLIC_` value is embedded in the application and is not secret.
+
+Web export proves bundling, not native correctness. Test Android and iOS behavior before
+release, including permissions, safe areas, text scaling, links, and background changes.

package/playbooks/stack/expo/security.md

@@ -0,0 +1,18 @@
+# Expo Security
+
+## Mobile Trust Boundary
+
+The installed application is an untrusted client. Never embed database passwords,
+service-role keys, OAuth client secrets, or signing keys. UI role checks do not authorize
+API or Supabase requests.
+
+## Session Storage
+
+Use a maintained provider with Authorization Code + PKCE. Store persistent session
+material in SecureStore, never AsyncStorage. The provider owns refresh-token rotation;
+the app handles expiry, revocation, logout, foreground resume, and retry without refresh
+loops. Validate registered deep-link callback schemes and reject arbitrary return URLs.
+
+Supabase projects use the generated SecureStore adapter. Spring multi-client projects use
+the chosen OIDC provider; Spring validates access tokens and never receives refresh tokens.
+Redact tokens, recovery links, authorization headers, and personal data from diagnostics.

package/playbooks/stack/expo/structure.md

@@ -0,0 +1,26 @@
+# Expo Structure
+
+## Expo Router
+
+Routes live in `app/`; `_layout.tsx` composes navigation and installed providers. Validate
+route and deep-link parameters before use. Navigation belongs in screens or explicit user
+action handlers, never deep inside data utilities.
+
+## Feature Ownership
+
+```text
+app/                       route files
+features/tasks/
+├── components/
+├── hooks/
+├── api.ts                 REST protocol, when used
+├── data.ts                Supabase access, when used
+├── schema.ts
+└── types.ts
+components/ui/             reusable native primitives
+lib/                       transport, secure storage, platform adapters
+config/                    validated public runtime configuration
+```
+
+Create only needed folders. Large features expose an `index.ts` public API and may add
+`sync/`, `background/`, or `platform/` after the corresponding runtime behavior exists.

package/playbooks/stack/expo/testing.md

@@ -0,0 +1,13 @@
+# Expo Testing
+
+## Test Layers
+
+- Unit-test schemas, state transitions, and pure sync/conflict policies.
+- Use React Native Testing Library for accessible screen behavior.
+- Contract-test API/data functions and offline/error normalization.
+- Test SecureStore through an adapter, never by exposing real session material.
+- Test foreground/background expiry and ensure refresh failures cannot loop.
+- Large projects add native-device E2E for critical flows.
+
+Every profile passes typecheck, Jest, `expo install --check`, and web export. These checks
+do not replace Android and iOS release verification.

package/playbooks/stack/laravel/architecture.md

@@ -0,0 +1,34 @@
+# Laravel Architecture
+
+## Profiles
+
+### Small
+
+`Route → Form Request when needed → Controller → Eloquent → Resource/View`.
+Use Laravel conventions directly. Do not add Actions, Services, repositories, or DTO
+folders for trivial CRUD.
+
+### Medium (Recommended)
+
+`Route → Form Request → Controller/UI adapter → Action or Service → Eloquent`.
+An Action owns one meaningful use case. A Service owns a reusable capability shared by
+several use cases. The coordinating operation owns multi-write transactions.
+
+### Large
+
+Keep the Medium vocabulary inside a modular monolith. Modules expose small public APIs
+and keep application, domain, persistence, jobs, and UI adapters private. Enforce module
+dependencies automatically. Large does not mean repository-per-model or microservices.
+
+## Dependency Direction
+
+HTTP, CLI, jobs, and UI components call application behavior. Application behavior may
+use Eloquent or an explicit external adapter; it never depends on controllers, requests,
+Blade, Livewire, or Inertia.
+
+## Escalation
+
+Eloquent is the default persistence abstraction. Add a repository or query object only
+for complex repeated queries, multiple data sources, or a boundary with measurable value.
+Create a directory only with its first real file.
+

package/playbooks/stack/laravel/runtime.md

@@ -0,0 +1,27 @@
+# Laravel Runtime
+
+## Request Lifecycle
+
+Validate untrusted input with Form Requests, authorize the resource and operation, invoke
+application behavior, then return an intentional Resource, DTO, redirect, or view. Never
+serialize a complete Eloquent model accidentally.
+
+## Transactions and Side Effects
+
+The application operation coordinating related writes owns the transaction. Dispatch
+jobs and listeners after commit when they depend on committed state. Use idempotency and
+an outbox when cross-system delivery must survive process failure.
+
+## Queries
+
+Load relationships intentionally, prevent N+1 behavior, validate pagination, and allowlist
+filter and sorting fields. Database constraints remain authoritative under races.
+
+## Configuration and Failures
+
+Read server configuration through Laravel config, fail safely when required values are
+missing, and never expose secrets to browser assets. Map expected failures to stable safe
+responses; unexpected failures receive a trace identifier and server-side diagnostics.
+
+Use Composer, Artisan, the generated npm scripts, and Pint. Never edit `vendor/`.
+

package/playbooks/stack/laravel/security.md

@@ -0,0 +1,23 @@
+# Laravel Security
+
+## Trust Boundaries
+
+Form Request validation is not authorization. Enforce Gates/Policies beside every
+protected read or side effect, including resource ownership; hiding UI is never enough.
+Guard mass assignment and return intentional Resources/props/view data.
+
+## Authentication Models
+
+- Laravel-owned Blade, Livewire, and Inertia sites use secure server sessions and CSRF.
+- A separate first-party SPA on the same parent domain uses Sanctum stateful cookies.
+- Independent mobile/multi-client APIs validate access tokens from an external OIDC
+  provider; that provider owns issuance, refresh, rotation, and revocation.
+- Sanctum personal access tokens are credentials, not a refresh-token system.
+- Passport is opt-in only when the product truly operates an OAuth2 server.
+
+Cookie settings, CORS origins, redirect destinations, and callback URLs are explicit
+allowlists. Throttle login, recovery, uploads, and abuse-sensitive mutations. Uploaded
+files are untrusted and require type, size, ownership, storage, and download controls.
+
+Never log passwords, cookies, bearer tokens, reset links, secrets, or unnecessary PII.
+

package/playbooks/stack/laravel/structure.md

@@ -0,0 +1,29 @@
+# Laravel Structure
+
+## Package by Feature
+
+Keep Laravel's conventional entry points and group meaningful application behavior by
+feature when the codebase grows.
+
+```text
+app/
+├── Http/Controllers/       # HTTP coordination
+├── Http/Requests/          # trust-boundary validation
+├── Http/Resources/         # intentional API shapes
+├── Models/                 # Eloquent models
+├── Policies/               # resource authorization
+├── Actions/                # real named use cases only
+├── Services/               # shared capabilities only
+└── Jobs/                   # real background work only
+database/{migrations,factories,seeders}/
+routes/{web,api}.php
+tests/{Feature,Unit}/
+```
+
+Small generates only conventional files required by its example. Medium adds an Action
+or Service only for a real workflow. Large aligns namespaces with modules and exposes an
+explicit public module API. Repositories, Queries, DTOs, Events, and Jobs remain
+demand-driven in every profile.
+
+Never create empty placeholder trees. Use normal Laravel and PSR naming conventions.
+

package/playbooks/stack/laravel/testing.md

@@ -0,0 +1,22 @@
+# Laravel Testing
+
+## Risk-Based Layers
+
+| Risk | Test |
+|---|---|
+| Pure PHP/domain rule | Pest/PHPUnit unit test |
+| Validation, middleware, Resource contract | HTTP feature test |
+| Policy/resource ownership | unauthenticated, forbidden, allowed tests |
+| Eloquent query or migration | target PostgreSQL integration test |
+| Queue dispatch/retry | focused job test plus integrated boundary test |
+| Browser behavior | component test or Playwright critical journey |
+| Large module dependency | automated architecture check |
+
+Use factories for intent and `RefreshDatabase` with an isolated test database. SQLite may
+support fast framework-independent tests, but it is not evidence for PostgreSQL-specific
+SQL, constraints, locking, or migrations.
+
+Test safe failures, conflicts, transaction rollback, login/logout, session expiry, CSRF,
+and resource authorization according to the selected authentication model. Do not mock
+Eloquent merely to satisfy a unit-test percentage.
+

package/playbooks/stack/laravel-ui.manifest.json

@@ -0,0 +1,42 @@
+{
+  "id": "laravel-ui", "kind": "frontend", "label": "Laravel full-stack UI", "platform": "web",
+  "appliesTo": { "backend": ["laravel"] }, "port": 8000, "needsDocker": false, "frontendDir": "",
+  "architectureProfiles": ["small", "medium", "large"],
+  "playbooks": [
+    { "file": "platform/laravel-ui/blade/architecture.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "file": "platform/laravel-ui/blade/structure.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "file": "platform/laravel-ui/blade/runtime.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "file": "platform/laravel-ui/blade/security.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "file": "platform/laravel-ui/blade/testing.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "file": "platform/laravel-ui/livewire/architecture.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "file": "platform/laravel-ui/livewire/structure.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "file": "platform/laravel-ui/livewire/runtime.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "file": "platform/laravel-ui/livewire/security.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "file": "platform/laravel-ui/livewire/testing.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "file": "platform/laravel-ui/inertia-react/architecture.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "file": "platform/laravel-ui/inertia-react/structure.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "file": "platform/laravel-ui/inertia-react/runtime.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "file": "platform/laravel-ui/inertia-react/security.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "file": "platform/laravel-ui/inertia-react/testing.md", "appliesWhen": { "laravelUi": "inertia-react" } }
+  ],
+  "stylingOptions": ["tailwind"], "scripts": {}, "ciTemplate": "none", "envPrefix": "VITE_",
+  "folders": [], "deps": [], "devDeps": [], "env": [], "clientEnv": [],
+  "constraints": ["Laravel owns routing, authentication, authorization, and persistence"],
+  "concerns": [
+    { "id": "ui-architecture", "required": true, "playbook": "platform/laravel-ui/blade/architecture.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "id": "ui-structure", "required": true, "playbook": "platform/laravel-ui/blade/structure.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "id": "ui-runtime", "required": true, "playbook": "platform/laravel-ui/blade/runtime.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "id": "ui-security", "required": true, "playbook": "platform/laravel-ui/blade/security.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "id": "ui-testing", "required": true, "playbook": "platform/laravel-ui/blade/testing.md", "appliesWhen": { "laravelUi": "blade" } },
+    { "id": "ui-architecture", "required": true, "playbook": "platform/laravel-ui/livewire/architecture.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "id": "ui-structure", "required": true, "playbook": "platform/laravel-ui/livewire/structure.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "id": "ui-runtime", "required": true, "playbook": "platform/laravel-ui/livewire/runtime.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "id": "ui-security", "required": true, "playbook": "platform/laravel-ui/livewire/security.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "id": "ui-testing", "required": true, "playbook": "platform/laravel-ui/livewire/testing.md", "appliesWhen": { "laravelUi": "livewire" } },
+    { "id": "ui-architecture", "required": true, "playbook": "platform/laravel-ui/inertia-react/architecture.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "id": "ui-structure", "required": true, "playbook": "platform/laravel-ui/inertia-react/structure.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "id": "ui-runtime", "required": true, "playbook": "platform/laravel-ui/inertia-react/runtime.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "id": "ui-security", "required": true, "playbook": "platform/laravel-ui/inertia-react/security.md", "appliesWhen": { "laravelUi": "inertia-react" } },
+    { "id": "ui-testing", "required": true, "playbook": "platform/laravel-ui/inertia-react/testing.md", "appliesWhen": { "laravelUi": "inertia-react" } }
+  ]
+}

package/playbooks/stack/laravel.manifest.json

@@ -0,0 +1,35 @@
+{
+  "id": "laravel",
+  "kind": "backend",
+  "label": "Laravel (PHP)",
+  "appliesTo": { "frontend": ["nextjs", "react", "react-native", "no-frontend", "laravel-ui"] },
+  "port": 8000,
+  "needsDocker": true,
+  "makefileTemplate": "laravel",
+  "architectureProfiles": ["small", "medium", "large"],
+  "playbooks": [
+    "stack/laravel/architecture.md",
+    "stack/laravel/structure.md",
+    "stack/laravel/runtime.md",
+    "stack/laravel/security.md",
+    "stack/laravel/testing.md",
+    "capabilities/laravel/database.md",
+    "capabilities/laravel/migrations.md",
+    { "file": "capabilities/laravel/session-auth.md", "appliesWhen": { "authentication": "laravel-session" } },
+    { "file": "capabilities/laravel/sanctum-spa.md", "appliesWhen": { "authentication": "sanctum-spa" } },
+    { "file": "capabilities/laravel/oidc-resource-server.md", "appliesWhen": { "authentication": "laravel-oidc" } }
+  ],
+  "folders": [], "deps": [], "devDeps": [],
+  "env": ["DATABASE_URL", "POSTGRES_USER", "POSTGRES_PASSWORD", "POSTGRES_DB", "APP_KEY", "APP_URL"],
+  "clientEnv": [],
+  "constraints": [
+    "Laravel owns trusted server behavior and resource authorization",
+    "PostgreSQL migrations are the generated schema source of truth"
+  ],
+  "concerns": [
+    { "id": "architecture", "required": true, "playbook": "stack/laravel/architecture.md", "sections": ["Profiles", "Dependency Direction"] },
+    { "id": "stack-security", "required": true, "playbook": "stack/laravel/security.md", "sections": ["Trust Boundaries", "Authentication Models"] },
+    { "id": "stack-testing", "required": true, "playbook": "stack/laravel/testing.md", "sections": ["Risk-Based Layers"] },
+    { "id": "migrations", "required": true, "playbook": "capabilities/laravel/migrations.md", "sections": ["Development", "Production"] }
+  ]
+}

package/playbooks/stack/nextjs/architecture.md

@@ -0,0 +1,62 @@
+# Next.js Architecture
+
+## Profiles
+
+The selected profile is a baseline for the project, not permission to create empty layers.
+
+### Small
+
+Keep routing and route composition in `src/app`. A route may call a feature query or
+server-only data function directly. A Server Function may perform a simple validated
+mutation directly through the secure data-access boundary. Do not create a Service for
+trivial mapping or a Repository without persistence.
+
+```text
+Server Component → Query/DAL → owned data
+Form → Server Function → DAL → owned data
+```
+
+### Medium (default)
+
+Group application code by feature. Entry points call a reusable Service when an
+operation contains policy, coordination, or is shared. Reads use feature Queries.
+
+```text
+Web Action ──────┐
+Route Handler ───┼──→ Service → Repository → Next-owned database
+Job ─────────────┘
+
+Page → Query → Repository → Next-owned database
+Page/Action → Service when useful → API client → Spring or external API
+```
+
+A Repository means owned persistence. A remote HTTP client belongs in `api/`; do not
+rename transport code to make every diagram look identical.
+
+### Large
+
+Keep the Medium vocabulary. Add an explicit feature public API, domain policies where
+real domain behavior exists, jobs/events, contract tests, observability, and automated
+cross-feature import checks. Large means enforced boundaries, not extra synonyms for
+Service and Repository.
+
+## Dependency Direction
+
+```text
+app routing → feature entry points/UI → application operations → data/API boundary
+shared UI   → no feature imports
+feature A   → feature B public API only (Large)
+```
+
+- `app/` owns URLs, layouts, metadata, loading, errors, and composition.
+- Actions and Route Handlers are untrusted entry points, not business operations.
+- Services do not import React components or route modules.
+- Repositories and API clients do not import UI.
+- Do not duplicate the same operation across Actions, handlers, and jobs.
+
+## Escalation Rules
+
+Add a Service for meaningful rules, multi-step coordination, reuse, transactions, or
+independent testing. Add a Repository when Next owns persistence. Add a domain policy
+when behavior has a stable business name and invariants. Never add a folder only because
+the selected profile lists it.

package/playbooks/stack/nextjs/runtime.md

@@ -0,0 +1,31 @@
+# Next.js Runtime
+
+## Server and Client
+
+Server Components are the default. Add `'use client'` only for state, effects, event
+handlers, browser APIs, or client-only libraries, and keep that boundary narrow.
+
+- Read initial data directly on the server; do not fetch the app's own HTTP route.
+- Keep database clients, secret environment variables, and privileged SDKs server-only.
+- Treat every `NEXT_PUBLIC_` value as public.
+- Route Handlers exist for real HTTP consumers such as mobile apps, webhooks, and third
+  parties—not as mandatory internal indirection.
+
+## Caching and Mutations
+
+Caching is an explicit data decision. Document whether a read is request memoized,
+cross-request cached, revalidated, or dynamic. After a mutation, invalidate the narrowest
+tag or path that represents the changed data. Never cache permission checks or mutable
+user-specific results without a reviewed key and lifetime.
+
+Server Functions are public server entry points even when their call sites are internal.
+They validate input, authenticate and authorize, call an operation, invalidate affected
+data, and return a small serializable result.
+
+## Configuration and Failures
+
+- Validate required environment variables at startup/build boundaries.
+- Use `loading.tsx`, Suspense, and error boundaries where their scope is meaningful.
+- Log structured server events with request/trace identifiers; never log credentials,
+  cookies, authorization headers, reset links, or full personal objects.
+- Production builds, lint, typecheck, and tests are part of the runtime contract.

package/playbooks/stack/nextjs/security.md

@@ -0,0 +1,32 @@
+# Next.js Security
+
+## Authorization
+
+Proxy and layouts may make optimistic navigation decisions, but secure authorization is
+performed again in every Server Function, Route Handler, DAL/Repository, or protected
+side effect. Check both the authenticated principal and access to the requested resource.
+
+Treat Server Functions as public endpoints. Validate runtime input and return DTOs with
+only fields the caller may receive. Never pass whole database entities into Client
+Components.
+
+## Sessions
+
+Session behavior is selected by the authentication capability:
+
+- Supabase SSR uses cookie-aware clients and Proxy-driven refresh with `getClaims()`.
+- A Spring-backed browser session is owned by Spring; Next acts as UI/BFF and does not
+  invent a second refresh-token protocol.
+- OIDC access tokens come from the identity provider; the resource API validates them.
+- `not-yet` means no login exists. Do not add fake role flags or trusted client state.
+
+Cookies carrying credentials must be `HttpOnly`, `Secure` in production, and use an
+appropriate `SameSite` policy. Cookie-authenticated writes require CSRF protection.
+Validate every redirect/return path as an application-relative destination.
+
+## Server Boundaries
+
+- Use `server-only` for repositories, admin clients, and secret configuration.
+- Never expose a service-role key, database URL, refresh token, or private API key.
+- Rate limit expensive and abuse-sensitive public operations at a trusted boundary.
+- Add security headers deliberately; CSP must match the assets and scripts actually used.