coding-os 0.3.2__py3-none-any.whl

templates/nextjs/scaffold/docs/engineering/accessibility-web.md

@@ -0,0 +1,56 @@
+<!-- domain:FRONTEND | layer:reference | ssot:true | updated:2026-03-23 -->
+# Accessibility (a11y) Checklist — WCAG 2.1 AA
+
+Purpose: Living checklist for accessibility compliance across the frontend.
+Read when: Building or reviewing any interactive component.
+Skip when: Working on backend-only tasks.
+Read next: `./frontend-rules.md` for general frontend conventions.
+
+> Nav: [Docs Index](../00-index.md) | [Frontend Rules](./frontend-rules.md)
+
+---
+
+## Interactive Elements
+
+- All icon-only buttons MUST have `aria-label` describing the action
+- All form inputs MUST have associated `<label>` elements (htmlFor + id)
+- Required form fields MUST have `aria-required="true"`
+- Form validation errors MUST be linked to inputs via `aria-describedby`
+- Custom interactive elements (drawers, modals, dropdowns) MUST have `role` attributes
+- Modal/drawer close buttons MUST have `aria-label="Close"`
+
+## Dynamic Content
+
+- Toast notifications use Sonner which provides aria-live regions automatically
+- Cart count badge changes should be announced via `aria-live="polite"`
+- Form error messages should use `aria-live="assertive"`
+
+## Keyboard Navigation
+
+- Tab order follows logical reading order (no `tabindex > 0`)
+- All interactive elements activatable via Enter or Space
+- Escape closes modals and drawers
+- Focus trap active inside open modals
+- Visible focus indicator on all interactive elements (`:focus-visible`)
+
+## Color Contrast (WCAG AA)
+
+- Normal text (< 18px): 4.5:1 minimum contrast ratio
+- Large text (>= 18px bold or >= 24px): 3:1 minimum contrast ratio
+- Interactive elements: 3:1 against adjacent colors
+- Focus indicators: 3:1 against background
+
+## Current Status
+
+- 26 files with aria-label attributes
+- Sonner toast library provides built-in aria-live support
+- shadcn/ui components include keyboard navigation by default
+- Cookie consent banner has `role="dialog"` and `aria-label`
+- Honeypot field has `aria-hidden="true"` and `tabindex="-1"`
+
+## Remaining Items
+
+- Audit form inputs for missing aria-required on required fields
+- Verify Tab order on checkout flow
+- Color contrast verification with automated tool (axe-core or Lighthouse)
+- Add skip-to-content link at top of page

templates/nextjs/scaffold/docs/engineering/copywriting-standard.md

@@ -0,0 +1,102 @@
+<!-- domain:PRODUCT | layer:policy | ssot:true | updated:2026-03-16 -->
+
+# Copywriting Standard
+
+Purpose: Define the quality bar, tone rules, and review rubric for all user-facing copy across ExampleApp.
+Read when: Writing or reviewing marketing copy, product descriptions, docs copy, UI text, legal language, or CTAs.
+Skip when: Working on code, infra, or backend-only tasks with no user-facing strings.
+Read next: `../pages-content-spec/00-index.md`, `../../STYLE_GUIDE.md`
+
+> Nav: [Docs Index](../00-index.md) | [Content Specs Index](../pages-content-spec/00-index.md)
+
+---
+
+## Why/What/How Framework
+
+Every piece of copy must answer three questions in the user's mind:
+
+> **Why** — Why does the user care? What pain point or aspiration does this address?
+> **What** — What is being offered? (product, feature, benefit, action)
+> **How** — How does the user get it? (clear next step, CTA, or process)
+
+Copy that skips any of these three leaves friction.
+
+---
+
+## Quality Rubric (Target: 9/10)
+
+Evaluate all user-facing copy against these five dimensions:
+
+- Clarity → 2pts: instantly understandable, no jargon, reader knows what to do
+- Tone-fit → 2pts: matches context (formal=docs, conversational=marketing, clear=errors, plain=legal)
+- SEO → 2pts: target keywords natural, meta descriptions compelling, headings signal hierarchy
+- Persuasion → 2pts: creates desire, addresses objections, clear CTA, tangible benefits
+- Correctness → 1pt: no grammar/spelling/factual errors, verifiable statements, consistent tone
+
+A score of 9 means one minor flaw that doesn't block understanding or action.
+
+---
+
+## Brand Voice & Tone
+
+**ExampleApp is: premium but accessible, expert but friendly, modern but trustworthy.**
+
+- **Premium** → polished, confident, quality-first. No typos, no filler, no bargain-bin energy.
+- **Accessible** → no gatekeeping language or jargon. A high schooler should understand pricing and value props.
+- **Expert** → back claims with specifics. Show domain knowledge in templates, design, AI, digital tools.
+- **Friendly** → conversational. Contractions okay. Personality welcome.
+- **Modern** → current references, clean language, no outdated metaphors.
+- **Trustworthy** → clarity over hype. Tell the truth about limitations. Don't overpromise.
+
+Tone depends on context — keep it consistent within a page or section:
+
+- **Marketing** (landing pages, product cards, emails) → conversational, confident, benefit-focused. Use "you." Create desire without being pushy.
+- **Documentation** (guides, API docs, onboarding) → formal, precise, action-oriented. Use imperative voice.
+- **Error messages** (validation, failures, warnings) → clear, helpful, non-blaming. Always include recovery action.
+- **Legal** (ToS, Privacy, Disclaimers) → formal, factual, plain language. Be exhaustive but readable.
+
+---
+
+## Copy Rules
+
+1. **Active voice** over passive. "Download your template" not "Your template can be downloaded."
+2. **Second person ("you")** for user-facing copy. "You get lifetime access" not "Users get lifetime access."
+3. **Short sentences.** Average max 25 words. Vary length to maintain rhythm.
+4. **Heading case:** H1 & H2 → Title Case; H3+ → Sentence case.
+5. **CTAs use imperative verbs.** "Get started," "Download now," "Browse templates" — not "Click here" or "Learn more" alone.
+6. **No unsupported superlatives.** Not "the best templates on the web" — instead "templates rated 4.9/5 by 12K+ creators."
+7. **Price display:** Always show currency symbol. Omit cents for round numbers ("$29/mo" not "$29.00/mo").
+8. **Avoid:** generic AI-sounding copy ("leverage synergies"), clickbait without substance, excessive exclamation marks (max one per section), unexplained buzzwords.
+
+---
+
+## Examples: Good vs Bad
+
+- Bad: "This template helps you. It has lots of features." → Good: "Save 8 hours on your next project. 40+ pre-built blocks, customizable themes, and Figma source files. Get started in under 5 minutes."
+- Bad: "Invalid email. Error." → Good: "That email is already linked to an account. Log in, or try a different email."
+- Bad: "The best AI templates platform. We help creators achieve amazing things." → Good: "Design faster. 10,000+ creators save 12 hours per project with ExampleApp templates. Explore free — no credit card required."
+
+---
+
+### Error Messages
+
+- Error messages are user-facing copy — they must be clear, non-technical, and actionable.
+- Good: "Email already registered. Try logging in instead."
+- Bad: "Duplicate entry in users table for email field."
+- Always tell the user what to do next, not just what went wrong.
+- Empty state messages should be encouraging, not negative: "No reviews yet — be the first!" not "No data found."
+
+---
+
+## Checklist Before Publishing
+
+- [ ] Copy passes 9/10 rubric (or documented exception)
+- [ ] Why/What/How framework is complete
+- [ ] Tone matches context (marketing/docs/error/legal)
+- [ ] Active voice is primary
+- [ ] Shortest sentence average is <25 words
+- [ ] CTA is clear and imperative
+- [ ] No superlatives without supporting evidence
+- [ ] No grammar, spelling, or factual errors
+- [ ] Brand voice is consistent (premium, accessible, expert, friendly)
+- [ ] SEO keywords appear naturally (if applicable)

templates/nextjs/scaffold/docs/engineering/formatting-rules.md

@@ -0,0 +1,89 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-03-18 -->
+# Documentation Formatting Rules
+
+Purpose: Token-efficient formatting standards for all project documentation.
+Read when: Creating or editing any .md file in the docs system.
+Skip when: File content is unchanged and formatting is not in scope.
+Read next: `docs-system.md` for layer model and naming rules.
+> Nav: [Docs Index](../00-index.md) | [Docs System](../governance/docs-system.md)
+
+## File Standard
+
+Every `.md` file in `docs/` starts with a UFS header:
+
+```html
+<!-- domain:DOMAIN | layer:LAYER | ssot:true|ref | updated:YYYY-MM-DD -->
+```
+
+**Domain values:** ALL, AUTH, CATALOG, COMMERCE, PAYMENTS, DOWNLOADS, CONTENT, EMAIL, REVIEWS, ANALYTICS, ADMIN, INFRA, DOCS
+
+**Layer values:** index, playbook, spec, policy, reference, adr, task
+
+**ssot values:**
+- `true` → canonical source for its topic
+- `ref` → references other SSOT files
+
+## Format Conversion Rules
+
+### Rule 1 — Two-column data: Arrow notation
+
+```markdown
+<!-- Prefer arrow notation -->
+- Name → Django
+```
+
+### Rule 2 — Settings/config: Annotated code blocks
+
+```python
+# Before: | SECURE_SSL_REDIRECT | True | Force HTTPS |
+# After:
+SECURE_SSL_REDIRECT = True       # Force HTTPS
+```
+
+### Rule 3 — Package/dependency lists: Structured bullets
+
+```markdown
+- `django-environ` 0.13.x — CRITICAL
+  Loads env vars, parses DATABASE_URL.
+```
+
+### Rule 4 — Tables ARE justified when
+
+- Schema definitions (column name, type, constraints, description)
+- Comparison matrices (3+ items x 3+ dimensions)
+- Status/enum mappings with 3+ fields
+
+### Rule 5 — Collapse completed sections
+
+Use `<details>` for any section that is 100% completed but kept for reference.
+
+## General Rules
+
+- Use bullet lists over tables when data has ≤ 2 columns.
+- Keep GitHub-flavored Markdown; no HTML unless rendering requires it.
+- Prefer `key → value` arrow notation for two-column mappings.
+- File size limit: **300 lines max**. Split into sub-files with index if exceeded.
+- Relative links only — no absolute paths to local files.
+
+## File Header Format
+
+Every `.md` file in `docs/` starts with a UFS metadata header (see `docs/governance/docs-system.md` for the full contract):
+
+```html
+<!-- domain:DOMAIN | layer:LAYER | ssot:true|ref | updated:YYYY-MM-DD -->
+```
+
+Immediately after the H1 heading, include the opening block: `Purpose`, `Read when`, `Skip when`, `Read next`. These lines let an agent decide within the first screenful whether to keep reading.
+
+## Script Output Format
+
+All infrastructure scripts source `_lib.sh` and use standardized prefixes:
+
+| Prefix | Use | Stream |
+| --- | --- | --- |
+| `OK:` | Success result | stdout |
+| `INFO:` | Informational data | stdout |
+| `WARN:` | Non-fatal warning | stderr |
+| `ERROR:` | Fatal error (exits) | stderr |
+
+Scripts that produce structured output begin with a `=== script-name ===` header line.

templates/nextjs/scaffold/docs/engineering/frontend-rendering-rules.md

@@ -0,0 +1,80 @@
+<!-- domain:ALL | layer:policy | ssot:true | updated:2026-03-16 -->
+# Frontend Rendering Rules
+
+Purpose: Canonical server-first rendering, data-fetching, performance, and testing policy for the frontend.
+Read when: A task affects rendering strategy, data access, caching, or test scope.
+Skip when: You only need dependency or styling rules.
+Read next: `frontend-rules.md` for the broader frontend guardrails.
+
+> Nav: [Frontend Rules](./frontend-rules.md) | [Docs Index](../00-index.md)
+
+## 4) Rendering & Data Strategy (Server-First)
+
+Prefer:
+
+- Server Components for pages, layouts, and data fetching.
+- Route-level UX files: `loading.tsx`, `error.tsx`, and `not-found.tsx`.
+- `Suspense` boundaries for streaming where beneficial.
+- Server Actions for mutations and form submissions.
+- A data-access layer in `@/lib/server/data-access.ts`.
+- React 19 hooks like `use()` and `useOptimistic()` where appropriate.
+- URL search params for filter/pagination state instead of unnecessary client state.
+
+### 4.1 API Client Architecture
+
+**Server-Side Client (`lib/api/server.ts`)** — Server Components & Route Handlers.
+Reads JWT from `cookies()`, forwards as `Authorization: Bearer`. Base URL: `BACKEND_INTERNAL_URL` (Docker internal). Error handling: 401 → redirect `/login`, 403 → throw `ForbiddenError`, 404 → `notFound()`, 5xx → throw `ServerError`. Generic typed responses: `apiGet<T>(path)`, `apiPost<T>(path, body)`. No CSRF (server-to-server).
+
+**Client-Side Client (`lib/api/client.ts`)** — Client Components (`'use client'`).
+Browser sends JWT via httpOnly cookie (`credentials: 'include'`). Base URL: relative (`/api/v1/...`). CSRF: read `csrftoken` cookie → send as `X-CSRFToken` on mutating methods. Token refresh: on 401 → `POST /api/v1/auth/token/refresh/` → retry once → else redirect `/login`. Rate limit (429): exponential backoff (1s, 2s, 4s), max 3 retries. Timeout: 10s default, 30s uploads.
+
+**Shared Error Handler (`lib/api/errors.ts`)** — Parses API error format per `docs/api-contracts/error-format.md`. Maps to i18n user-friendly messages. Toast for recoverable (400, 422), redirect for auth (401, 403), PostHog `api_error` for 5xx.
+
+**SSE Client (`lib/sse/useEventStream.ts`)** — React hook wrapping `EventSource`. Auto-reconnect; fallback to polling after 5 consecutive failures. Auth via `withCredentials: true`. Ref: `docs/architecture/11-realtime-sse.md`.
+
+**Type Safety** — API response types from backend OpenAPI schema (future: `/api/v1/schema/`); until then manually in `lib/api/types.ts` matching `docs/api-contracts/shared-types-contract.md`. All API functions return typed responses. Never expose Django or Stripe secrets to client bundle.
+
+### 4.2 Client Component Rules
+
+Avoid unless necessary: `'use client'` at page/layout level, `useEffect` for primary data fetching, global client state for server-derived data.
+
+When client components are required: keep them small and isolated, pass server-fetched data down, wrap expensive UI in lightweight suspense boundaries, use `next/dynamic` only when client-only loading is required.
+
+### 4.3 Rendering Strategy Matrix
+
+| Page Type | Strategy | Implementation | Revalidation |
+| :------------------- | :-------- | :------------------------------------ | :------------ |
+| **Home** | ISR | `export const revalidate = 3600` | 1 hour |
+| **Product LP** | ISR | `export const revalidate = 3600` | 1 hour |
+| **Products Catalog** | ISR | `export const revalidate = 1800` | 30 min |
+| **Blog Posts** | SSG + ISR | `generateStaticParams()` + revalidate | On publish |
+| **Blog Hub** | ISR | `export const revalidate = 1800` | 30 min |
+| **Cart** | SSR | `dynamic = 'force-dynamic'` | Every request |
+| **Checkout** | SSR | `dynamic = 'force-dynamic'` | Every request |
+| **Account Pages** | SSR | Cookie-based auth required | Every request |
+| **Admin Pages** | SSR | Protected, real-time data | Every request |
+| **Legal Pages** | SSG | Build-time only | On deploy |
+| **404 / Error** | SSG | Build-time only | On deploy |
+
+### 4.4 Rendering Implementation Patterns
+
+- **ISR** (marketing pages): Set `export const revalidate = <seconds>` at route level. Use `generateStaticParams()` for dynamic slugs.
+- **SSR** (dynamic/protected pages): Set `export const dynamic = 'force-dynamic'`. Fetch authenticated data in the server component, pass to client views.
+- **SSG** (static legal pages): Plain component export, no data fetching. Rebuilt on deploy only.
+- **On-demand revalidation**: Call `revalidatePath()` or `revalidateTag()` inside Server Actions after mutations.
+
+## 5) Performance & Robustness
+
+- Minimize client bundle size and isolate `'use client'`.
+- Optimize images through `next/image` with explicit `sizes` and good formats.
+- Choose caching/revalidation strategy deliberately.
+- Wrap external calls in `try/catch`; handle timeouts, null data, and permission edges.
+- Handle errors per rendering strategy: SSR pages show `error.tsx`, ISR pages show stale-while-revalidate fallback, client fetches show inline error with retry.
+- Null/undefined data from API must be guarded — use optional chaining and nullish coalescing, never trust API response shape.
+- If proposing optimization, include a measurement plan such as Lighthouse or bundle analysis.
+
+## 6) Testing (Only Where It Pays)
+
+- Add unit tests for critical or fragile logic.
+- Do not add trivial tests for static markup.
+- Prioritize checkout, auth, entitlement, and other security-relevant flows.

templates/nextjs/scaffold/docs/engineering/frontend-rules.md

@@ -0,0 +1,183 @@
+<!-- domain:ALL | layer:policy | ssot:ref | updated:2026-03-16 -->
+# Frontend Engineering Rules
+
+Purpose: Routing hub for frontend implementation policy, dependency discipline, code style, and rendering rules.
+Read when: A frontend task needs canonical engineering guidance.
+Skip when: A narrower frontend sub-file already answers the question.
+Read next: This file for core guardrails, then `frontend-rendering-rules.md` for rendering/data strategy.
+
+> Nav: [Docs Index](../00-index.md) | [Code Style](../../CodeStyle.md) | [STYLE_GUIDE](../../STYLE_GUIDE.md)
+
+## 1) Non-Negotiables (Frontend)
+
+- Follow requirements exactly; if details are missing, log assumptions and choose safe defaults.
+- Output complete working code: no TODOs, placeholders, or missing edge cases.
+- Prefer readability and correctness over cleverness.
+- Use strict TypeScript everywhere; avoid `any`.
+- Prefer Server Components and SSR/streaming; isolate `'use client'`.
+- Always include loading, error, and empty states.
+- Use semantic HTML and accessible interactions.
+- Styling: Tailwind only unless the task explicitly requires custom CSS.
+- Validate inputs with Zod and never leak secrets.
+- New greenfield apps use `create-next-app` with TypeScript and Tailwind.
+
+### Mandatory Engineering Rules
+
+- **Money** → use integer cents only
+- **Truth** → webhooks are the source of truth for payments and entitlements
+- **Idempotency** → payment and webhook handlers must be idempotent
+- **Secrets** → never expose backend or Stripe secrets to the browser
+- **Cookie security** → `httpOnly`, `secure` in production, `sameSite: strict`
+- **Dynamic settings** → operational toggles belong in DB-backed `site_settings`
+
+## 2) Dependency Discipline
+
+Before adding a library: explain need, list built-in alternative, confirm RSC/SSR compat, check redundancy, keep count minimal. Use the MCP server for shadcn/ui component operations; plan with higher-level blocks before atoms.
+
+### Dependency Selection by Category
+
+| Purpose | Recommended | Why | Avoid |
+| ----------------- | --------------------- | ----------------------------------- | ---------------- |
+| **UI Components** | shadcn/ui v3 + Radix | Copy-paste, no lock-in | MUI, Chakra |
+| **Form Ops** | React Hook Form + Zod | Minimal, best DX | Formik |
+| **Auth** | Django + allauth headless (ADR-019) | API-first, built-in JWT | NextAuth |
+| **Date** | date-fns / Day.js | Modular, lightweight | moment.js |
+| **Icons** | Iconify (Solar) | PRD standard | Font Awesome |
+| **Animation** | Framer Motion | PRD standard | jQuery, GSAP |
+| **Editor** | Tiptap | Headless, ProseMirror-based | Quill, Draft.js |
+| **Captcha** | react-turnstile | Privacy-friendly | ReCaptcha |
+
+## 3) Code Style & Tailwind
+
+- Functional, declarative TypeScript; avoid classes. Use guard clauses and early returns.
+- Prefer `const fn = () => {}`; type explicitly when it improves clarity.
+- Organize imports: React/Next → third-party → internal → utils/types.
+- Avoid unnecessary abstractions; components should have a single clear responsibility.
+- Mobile-first responsive layout. Avoid ternaries inside `className`; use a `cn()` helper.
+- Keep UI consistent via shadcn/ui components and design tokens.
+- Primary CTAs must remain prominent, accessible, and mobile-friendly.
+- Prefer logical properties for RTL compatibility.
+- Use RGB CSS variables from `globals.css` so Tailwind opacity modifiers work.
+- Sort classes as layout → box-model → typography → visuals → misc.
+- Shared UI must stay reusable and composable.
+- For mission-critical layout components (header, footer, nav): use explicit CSS classes in `globals.css` with raw media queries, not only Tailwind responsive classes — avoids silent breakage from config drift.
+
+## 4) Comments
+
+- Comment **why**, not **what**. If the code is self-evident, no comment is needed.
+- Use `TODO: TASK-###` with a task number. Bare TODOs without a task reference are not allowed.
+- Comment non-obvious logic, security constraints, and rendering boundary decisions (e.g. `// 'use client' — needs useState for accordion`).
+- Do not add JSDoc that restates the component name or props type.
+
+## 5) Auth Middleware Pattern
+
+Auth middleware and token refresh: see `frontend-rendering-rules.md` § 4.1.
+
+## 6) Error Handling
+
+- Every async operation must handle loading, error, and empty states explicitly.
+- Use Error Boundaries at route level minimum (`error.tsx` per route group).
+- Map API `error_code` to i18n key: `errors.<domain>.<ERROR_CODE>` — never show raw server messages.
+- Provide retry action for recoverable errors (network, timeout).
+- Use toast for transient errors, inline display for form validation errors.
+- Network errors: show retry button, not just "error occurred".
+- Never let a failed API call result in a blank screen — always show fallback UI.
+
+## 7) Edge Case Testing
+
+- Test network failure scenarios (API returns 500, timeout, no response).
+- Test empty states (no data, empty arrays, null responses).
+- Test loading states (verify skeleton/spinner shows before data arrives).
+- Test form validation with invalid input, empty required fields, boundary values.
+- Test race conditions: rapid navigation, double-click submit, stale data after navigation.
+- Never write a test that asserts "renders without crashing" — assert visible content or behavior.
+
+## 8) E2E Testing (Playwright)
+
+E2E tests live in `src/frontend/e2e/` and are split into two layers:
+
+### Test Pyramid
+
+**UI Tests** (`e2e/ui/`) — no backend needed:
+
+- Page loads, form rendering, navigation, responsive layout
+- Run with: `make test-frontend`
+- Always pass regardless of backend state
+- Use `waitUntil: 'domcontentloaded'` for navigation
+
+**Integration Tests** (`e2e/integration/`) — backend REQUIRED:
+
+- Real API calls verified with `page.waitForResponse()`
+- HTTP status asserted (`expect(response.status()).toBeLessThan(400)`)
+- Use `requireBackend()` — tests FAIL (not skip) when backend is down
+- Run with: `make test-frontend-integration`
+
+### When to write which type
+
+- **UI test**: page loads correctly, form fields render, client-side validation, navigation links work
+- **Integration test**: form submit hits API and gets 200, data appears after action, redirect after auth
+
+### Patterns
+
+- Use `waitUntil: 'domcontentloaded'` for navigation — never `'load'` or `'networkidle'`.
+- Use `requireBackend()` in integration tests — never `skipIfNoBackend()` or `backendAvailable` branching.
+- Use `page.waitForResponse()` to intercept and verify API responses.
+- Use `generateTestEmail()` for unique test data per run.
+- Prefer `page.getByRole()` and `page.locator('#id')` over fragile CSS selectors.
+- Tests must pass without Stripe keys or Turnstile — these are env-var gated.
+- Use `attachPageDiagnostics()` to capture console errors, network failures, API calls.
+
+### Network Guard (MANDATORY for integration tests)
+
+**Every integration test MUST use `attachNetworkGuard()`** — a test that passes while the Network tab has errors is a lying test.
+
+```typescript
+import { attachNetworkGuard } from '../helpers';
+
+test('my integration test', async ({ page }) => {
+  const guard = attachNetworkGuard(page);
+
+  // ... test actions ...
+
+  // MUST be the last assertion — fails if unexpected network errors occurred
+  guard.assertNoUnexpectedErrors();
+});
+```
+
+**How it works:**
+
+- Monitors ALL network responses (4xx, 5xx) and request failures (CSP, timeouts, aborts)
+- Compares against a whitelist of expected errors (e.g., guest 401 on `/api/auth/user`)
+- Fails with a detailed report showing exactly which requests failed
+
+**To whitelist test-specific expected errors:**
+
+```typescript
+const guard = attachNetworkGuard(page, [
+  { urlPattern: /\/api\/v1\/some-endpoint/, status: 404 },
+]);
+```
+
+**Default whitelist** (always allowed):
+
+- `GET /api/auth/user` — guest users always get 401, this is expected
+- `lh3.googleusercontent.com` CSP — Google-hosted images blocked by CSP in dev
+- `/_next/image` 400 — missing local images in dev mode
+
+### Running
+
+- `make test-frontend` — UI tests only (no backend)
+- `make test-frontend-integration` — integration tests (backend required)
+- `make test-frontend-headed` — visible browser
+- `make ci-gate` — full pipeline: lint → backend → UI → integration → diagnose
+
+## Sub-File Routing
+
+- [frontend-rendering-rules.md](./frontend-rendering-rules.md)
+  Server-first rendering strategy, API client boundaries, performance, and testing guidance.
+
+## Quick Routing
+
+- Dependency choice or package fit → this file
+- Shared component style or Tailwind rule → this file
+- Server vs client rendering, SSR/ISR/SSG, caching, or tests → `frontend-rendering-rules.md`

templates/nextjs/scaffold/docs/engineering/i18n-policy.md

@@ -0,0 +1,99 @@
+<!-- domain:ALL | layer:policy | ssot:true | updated:2026-03-16 -->
+# Internationalization Policy
+
+Purpose: Locale support, message-key naming, ICU format rules, and src/frontend/backend i18n contracts.
+Read when: Adding translatable strings, setting up new locales, or reviewing i18n contracts.
+Skip when: Working within existing locale without adding new message keys.
+Read next: `architecture/10-blog-content-i18n.md` for content backend, `copywriting-standard.md` for tone.
+
+> Nav: [Docs Index](../00-index.md) | [Blog & i18n Architecture](../architecture/10-blog-content-i18n.md)
+
+---
+
+## Supported Locales
+
+- `en` → Active (default, fallback for all missing keys)
+- `es` → Planned (Americas + Spain)
+- `fa` → Planned (Iran + Farsi-speaking regions)
+- `de` → Planned (DACH region)
+- `fr` → Planned (France + Francophone)
+
+Format: BCP 47 lowercase, no region subtags unless required by regulation.
+
+---
+
+## Message Key Naming
+
+Format: `<page>.<section>.<key>` — all lowercase, dot-separated, no camelCase or underscores.
+
+- Page prefix matches content-spec filename slug: `home.*`, `checkout.*`, `shared.*` (header/footer), `errors.*`
+- Section groups by UI region: `home.hero.*`, `checkout.payment.*`
+- Key names the specific element: `checkout.payment.card-label`, `shared.nav.home`
+
+Examples: `home.hero.title` → "Welcome to ExampleApp" | `errors.not-found.heading` → "Page not found"
+
+---
+
+## Message Files
+
+Location: `src/frontend/messages/{locale}.json` — nested JSON matching dot-separated keys.
+
+Example: `{ "home": { "hero": { "title": "Welcome to ExampleApp", "cta": "Start browsing" } }, "checkout": { "summary": { "total": "Total", "item-count": "{count, plural, one {# item} other {# items}}" } } }`
+
+Required: `en.json` must have all keys. Other locales may be incomplete — `next-intl` falls back to English.
+
+---
+
+## ICU Message Format
+
+- **Variables** → `{count}` — wrap variable names in curly braces.
+- **Pluralization** → `"{count, plural, =0 {No items} one {# item} other {# items}}"` — use `=0`, `one`, `other`.
+- **Date/Time** → `"{date, date, long}"` — backend provides ISO 8601, frontend formats via next-intl.
+- **Currency** → `"{amount, number, currency}"` — use `Intl.NumberFormat` in components or ICU format.
+
+---
+
+## Frontend Setup
+
+- Library: `next-intl` (App Router) | Config: `src/frontend/next-intl.config.ts`
+- URL structure: `/[locale]/page` (e.g., `/en/home`, `/es/checkout`)
+- Locale detection: `Accept-Language` header → fallback `en`
+- Usage: `const t = useTranslations(); return <h1>{t('home.hero.title')}</h1>;`
+- With variables: `t('cart.item-count', { count: items.length })`
+
+---
+
+## Backend i18n
+
+- **Django Admin** → `gettext_lazy` for model labels, help text. Files in `locale/{locale}/LC_MESSAGES/`.
+- **DRF API** → English-only error messages with machine-readable error codes (e.g., `{ "error_code": "INVALID_CARD", "message": "Invalid card number" }`). Frontend maps `error_code` → localized message via `errors.<feature>.{error_code}` key.
+
+---
+
+## Hardcoded vs i18n Rule
+
+**ALL user-facing text must use message keys:** headings, labels, buttons, links, form messages, tooltips, email templates, meta descriptions.
+
+**Hardcoded English allowed only for:** console logs, code comments, variable names, migration descriptions, git commits.
+
+- All user-facing error messages must use i18n message keys (`errors.<domain>.<ERROR_CODE>`), never hardcoded English strings.
+- Backend error responses use `error_code` only — frontend maps to localized message via `messages/{locale}.json`.
+
+**Enforcement phasing:** Content-spec files marked `format:i18n-keys` must stay lint-clean. Frontend runtime surfaces are still migrating — `make docs-lint` inventories remaining hardcoded text without failing. Admin-only surfaces and editor/demo code stay out of docs-lint gating until a dedicated migration task promotes them.
+
+---
+
+## Adding a New Locale
+
+1. Copy `en.json` → `{new-locale}.json`
+2. Update `next-intl.config.ts` to register locale
+3. Add to this policy's supported locales list
+4. Translate all keys — no blank values in production
+5. Test language switcher and URL routing
+6. Update `changes.log`
+
+## Validation
+
+- Missing keys → compare key depth between `en.json` and target locale
+- Hardcoded text → `rg '">` in `src/frontend/components/`
+- Key format → `rg '\.[a-z]+\.[a-z]+\.' src/frontend/` to validate