@horka/app-forge 0.1.0

package/templates/packs/nuxt-web/docs-architecture/ARCHITECTURE.md

@@ -0,0 +1,169 @@
+# ARCHITECTURE — Layered Nuxt Web App
+
+Maps the universal L0–L5 contract (`ARCHITECTURE_PRINCIPLES.md` — read it first) onto
+Nuxt 4 / Vue 3 / TypeScript. One repo, one `app/` source dir. Nuxt has no module-system
+walls, so **the import graph IS the architecture** — every rule below must stay
+grep-visible (Physical mapping rule 2).
+
+## 1. Layer model — Nuxt instantiation
+
+```
+L5  COMPLETE FEATURES   app/pages/        file-based routes — THIN assemblies only
+                        app/layouts/      shells (default, app, …)
+                        app/stores/       shared app state (Pinia) — explicit barrel imports
+                        app/middleware/   route policy (auth from route meta — SEO_AND_ROUTING.md)
+                        app/plugins/sdk.ts  composition root: wires the SDK with runtime config
+                        app.vue · error.vue · server/ (health endpoint, BFF routes)
+L4  SHARED FEATURES     app/features/<Feature>/   domain-AWARE bricks reused by ≥2 pages
+                        (components/ + composables/ + types/ + index.ts barrel)
+L3  CORE LOGIC          app/domain/       pure TS: models, engines, validation —
+                                          no Vue, no Nuxt, no IO, no auto-imports
+    CORE UI             app/designSystem/<DSModule>/   domain-BLIND components
+                        (components/ + types/ + composables/ + index.ts barrel)
+L2  DATA                the typed SDK (external package — SDK_CONTRACT.md)
+                        app/composables/api/   repository composables: call SDK,
+                                               map wire types → domain models
+L1  OPS                 app/plugins/  analytics.client.ts · logger.{client,server}.ts · flags
+                        app/constants/analytics.ts   the typed event catalog (OPS_WEB.md)
+L0  FOUNDATION          app/assets/css/tokens.css   design tokens (CSS custom properties)
+                        app/utils/    pure helpers/formatters — no Vue imports
+```
+
+> **Target shape vs. what ships.** The map above is where each kind of file *goes* — not an
+> inventory of the skeleton. The scaffold ships the always-needed floor only:
+> `app/assets/css/{tokens,main}.css`, `app/utils/`, `app/domain/`, `app/designSystem/DSButton`,
+> `app/features/`, `app/pages/index.vue`, `app/app.vue`, and `server/api/health.get.ts`.
+> Everything else named here — `app/plugins/` (analytics/logger/flags), `app/constants/analytics.ts`,
+> `app/composables/api/`, `app/stores/` (Pinia — add `@pinia/nuxt` the day a store lands),
+> `app/middleware/auth.global.ts`, `app/layouts/`, `error.vue` — is created **the slice it earns
+> its first real file**. Don't pre-scaffold empty directories or add Pinia before a store exists;
+> the rules below say where things belong when they arrive, and the greps in §5 assume the target
+> layout (they no-op on directories that don't exist yet).
+
+## 2. Dependency direction rules
+
+| Layer | May use | Must NEVER use | Why |
+|---|---|---|---|
+| L0 tokens + utils | nothing | Vue, Nuxt, the DOM | testable in node, reusable anywhere |
+| L1 ops | L0, runtime config | domain types, SDK | plumbing is product-blind |
+| L2 api composables | SDK public surface, L3 domain models, L1, L0 | components, stores | they implement L3 needs (the sanctioned upward arrow: models/contracts only) |
+| L3 `domain/` | L0 utils only | Vue, Nuxt, SDK, fetch | pure — vitest runs it in milliseconds |
+| L3 `designSystem/` | L0 tokens, Vue | domain types, SDK, stores, i18n keys of features | a DS button doesn't know what an "Order" is |
+| L4 `features/` | L3, L2, L1, L0 | sibling features, pages, stores in props | bricks take values + emit events |
+| L5 pages/layouts/stores | everything below | sibling pages | final assembly, throwaway by design |
+
+- **L4/L5 communicate by props down / events up** (`@save`, `@delete`) — a brick never reaches
+  into a store on its own; the page wires store ↔ brick.
+- **Auto-imports hide the import graph.** A composable used without an import line is still a
+  dependency. Compensate with placement + naming discipline (CONVENTIONS.md) and the greps in §5.
+
+> ⚠️ **Gotcha:** Symptom — refactoring the API SDK breaks the *design system*. Cause — a
+> production team kept domain row components (`ProjectRow`, `ReleaseRow`…) inside the DS folder,
+> their props typed against deep SDK internals (`sdk/src/types/*`). Fix — `designSystem/` is
+> domain-blind by contract: primitives and UI types in props only. Domain-aware composites are
+> **features (L4)**; SDK types enter through L2 mapping, never through component props' imports.
+
+> ⚠️ **Gotcha:** Symptom — a "component" added under `app/pages/` becomes a navigable route.
+> Cause — Nuxt routes every `.vue` file under `pages/`. Fix — components never live in `pages/`;
+> page-specific pieces go to the matching `features/<Feature>/components/`.
+
+## 3. Module anatomy + registration
+
+DS modules (L3) and feature modules (L4) share one anatomy:
+
+```
+app/designSystem/DSButton/          app/features/Checkout/
+  components/DSButton.vue             components/CheckoutSummary.vue
+  types/dsButton.ts                   composables/useCheckout.ts
+  index.ts          ← barrel          types/checkout.ts
+                                      index.ts
+```
+
+`nuxt.config.ts` registers them once, by glob — adding a module requires zero config:
+
+```ts
+components: [
+  { path: '~/designSystem', pattern: '**/components/**', pathPrefix: false },
+  { path: '~/features',     pattern: '**/components/**', pathPrefix: false },
+],
+imports: { dirs: ['~/designSystem/**/composables', '~/features/**/composables'] },
+```
+
+> ⚠️ **Gotcha:** Symptom — every DS component renders as an empty comment node, no error
+> anywhere. Cause — the glob was put in `path` (`path: '~/designSystem/**/components'`);
+> the scanner ignores glob-in-path **silently** and registers nothing. Fix — directory in
+> `path`, glob in `pattern` (as above). Verify after config changes:
+> `grep DSButton .nuxt/components.d.ts`.
+
+- Components auto-register by file name (`<DSButton />` in any template).
+- **Everything else crosses module boundaries through the barrel**:
+  `import { DS_BUTTON_VARIANTS } from '~/designSystem/DSButton'` — never a deep file path.
+  The barrel is the module's public surface; internals are refactorable.
+
+## 4. Layer contracts
+
+### L3 `domain/` — the pure heart
+Plain TS modules: entities, engines (pure functions, injected `now`/randomness), validation,
+repository *contracts* (interfaces) when the app owns orchestration. Zero imports from Vue/Nuxt.
+This is where DELIVERY.md's "domain heart" slice lives; every rule ships with a vitest test that
+runs without booting Nuxt.
+
+### L2 — the SDK and its composables
+The SDK is wired ONCE in `app/plugins/sdk.ts` (runtime config → client instance → `provide`).
+Repository composables (`app/composables/api/useProjectsApi.ts`) are the only callers; they map
+wire DTOs to `domain/` models. **No component or store calls `$fetch` to the backend directly**
+(MULTI_REPO_CONTRACT.md: never bypass the SDK).
+
+### L1 — ops plugins
+Analytics catalog + `trackEvent`, logger plugins (client/server variants), feature-flag reader
+(fail closed). All specified in OPS_WEB.md. Nothing here knows the domain.
+
+### L5 — pages, layouts, stores, middleware
+Pages assemble bricks, declare their own route policy (`definePageMeta({ auth: false })`), own
+SEO meta, and fetch via `useAsyncData` in setup (CONVENTIONS.md §4). Stores hold cross-page
+state only; module-local state belongs in the module's composable.
+
+## 5. Enforcement greps — run before claiming a slice done
+
+```bash
+grep -rn "from '~/designSystem" app/domain app/utils            # L3-pure importing UI → bug
+grep -rn "sdk/src\|/dist/" app --include='*.ts' --include='*.vue'  # deep SDK imports → bug
+grep -rnE "#[0-9a-fA-F]{3,8}\b" app --include='*.vue'           # hex color outside tokens → bug
+grep -rn "\$fetch(" app/pages app/features app/stores            # raw API calls bypassing L2
+grep -rn "onMounted" app/pages                                   # each hit needs a CLIENT-ONLY rationale
+awk 'END{ if (NR>300) exit 1 }' <component>.vue                  # size cap (CONVENTIONS.md §3)
+```
+
+## 6. Where does a new file go?
+
+| You are adding… | It lives in… |
+|---|---|
+| A color/spacing/font/radius value | `app/assets/css/tokens.css` (L0) |
+| A pure formatter/helper | `app/utils/` (L0) |
+| An analytics event, logger, feature flag | `app/constants/` + `app/plugins/` (L1) |
+| An API call / DTO mapping | `app/composables/api/` (L2) |
+| A business rule, entity, engine | `app/domain/` (L3) — with its test |
+| A domain-blind component (button, card, modal) | `app/designSystem/<DSModule>/` (L3) |
+| A domain-aware brick used by ≥2 pages | `app/features/<Feature>/` (L4) |
+| A route, layout, cross-page state, route policy | `app/pages/`, `app/layouts/`, `app/stores/`, `app/middleware/` (L5) |
+| A server-only endpoint (health, BFF) | `server/api/` (L5) |
+| A user-facing string | `i18n/<locale>/<feature>.json` (I18N.md) |
+
+When in doubt between L4 and L5: start in the page, promote to `features/` on second use.
+
+## 7. Why this works with AI agents
+
+- **Fast ground truth without the browser**: `npm run test` exercises `domain/`, `utils/`,
+  DS components and composables in seconds — agents iterate there before paying for
+  `nuxt build` or a browser session.
+- **Grep-visible violations** (§5): every architectural rule is one search away.
+- **Deterministic components**: DS modules mount standalone in vitest (no Nuxt context),
+  so UI bricks are provable without e2e.
+- **Predictable placement** (§6): an agent knows the 3–5 files a feature needs; diffs stay small.
+
+Build matrix before claiming "done":
+```bash
+npm run test          # unit layer — seconds
+npm run build         # full SSR build
+npm run dev           # then eyes-on: open the page, check empty/error states
+```

package/templates/packs/nuxt-web/docs-architecture/CONVENTIONS.md

@@ -0,0 +1,140 @@
+# CONVENTIONS — Vue 3 / Nuxt 4 / TypeScript
+
+Prescriptive — follow as written. Layer placement is ARCHITECTURE.md; this file is how the
+code inside each brick looks.
+
+## 1. DS modules (L3 Core UI)
+
+One folder per component family, fixed anatomy, one barrel:
+
+```
+app/designSystem/DSButton/
+  components/DSButton.vue      # auto-registered globally (glob in nuxt.config)
+  types/dsButton.ts            # variant consts + prop types — plain .ts, NEVER .d.ts
+  composables/                 # optional: UI-only logic (focus trap, dismiss…)
+  tests/DSButton.spec.ts       # vitest, mounts standalone — colocated with the module
+  index.ts                     # barrel = the module's ONLY public surface
+```
+
+Rules:
+- Name = `DS<Thing>` (folder, component, file). The prefix prevents collisions with feature
+  components and makes DS usage grep-able.
+- **Domain-blind**: props are primitives, UI enums, slots, callbacks. A domain model in a DS
+  prop means the component belongs in `features/` (L4) — move it.
+- Variants are a `const` array + derived union type (`DS_BUTTON_VARIANTS` →
+  `DSButtonVariant`), exported from `types/`, so tests can iterate every variant.
+- Cross-module imports go through the barrel: `import { DSButton } from '~/designSystem/DSButton'`.
+
+> ⚠️ **Gotcha:** Symptom — `import { MY_CONST } from './types/foo'` is `undefined` at runtime.
+> Cause — consts were authored in a `.d.ts` file; declaration files emit no JavaScript and most
+> pipelines silently skip them. Fix — module types live in **plain `.ts`** files; reserve `.d.ts`
+> for ambient declarations only (e.g. `window.yourProvider` — OPS_WEB.md §1).
+
+## 2. Naming
+
+| Thing | Convention | Example |
+|---|---|---|
+| DS component | `DS<Thing>.vue` | `DSButton.vue`, `DSModal.vue` |
+| Feature component | `<Feature><Role>.vue` | `CheckoutSummary.vue` |
+| Composable | `use<Thing>.ts`, one main export | `useApiErrorHandler.ts` |
+| Domain module | noun, intent not tech | `order.ts`, `pricingEngine.ts` |
+| Store | `use<Thing>Store` in `app/stores/` | `useSessionStore` |
+| Types file | camelCase, plain `.ts` | `dsButton.ts` |
+| Events emitted | past/imperative verb | `@save`, `@dismiss`, `@page-change` |
+| Booleans | assertions | `isLoading`, `hasErrors`, `canSubmit` |
+
+Comments explain **why** (decision, trap, side effect) — never what the code already says.
+
+## 3. Component size cap — 200 target, 300 hard
+
+A `.vue` file (template + script + style) over **300 lines is a review blocker**; over 200,
+plan the split. Splitting recipe, in order:
+1. **Pure logic out** → `app/domain/` (testable rules) or a module composable (UI orchestration).
+2. **Repeated/markable template chunks out** → child components in the same module's
+   `components/`, or a DS module if domain-blind.
+3. **Types and consts out** → the module's `types/` file.
+
+> 📖 **War story:** a production homepage hero grew to 1,353 lines — animation logic, three
+> sub-layouts, inline SVG and tracking calls in one SFC. Every change risked every behavior, and
+> no part was testable alone. The cap exists so the split happens at 250 lines, not at 1,353.
+
+## 4. Data fetching — the SSR stance (read before any fetch)
+
+This app runs `ssr: true`. **Default: fetch in setup** with `useAsyncData`/`useFetch` —
+runs on the server, renders real content, hydrates without refetch:
+
+```ts
+const { data: projects, error, pending } = await useAsyncData(
+  'projects',                                  // explicit, stable key
+  () => useProjectsApi().list(),               // L2 repository composable — never raw $fetch
+)
+```
+
+**Client-only fetching is the exception** and requires a written rationale at the call site:
+
+```ts
+// CLIENT-ONLY: depends on viewport size measured after mount; below the fold,
+// not SEO-relevant, gated behind user interaction.
+onMounted(async () => { … })
+```
+
+`grep -rn onMounted app/pages` with no adjacent `CLIENT-ONLY:` comment = violation.
+
+> 📖 **War story:** a production app ran `ssr: true` while ~45 pages fetched everything in
+> `onMounted`. The server rendered empty shells, crawlers indexed spinners, users got a content
+> flash on every navigation — all of SSR's cost, none of its value. The stance above is the fix.
+
+SSR safety rules:
+- No `window`/`document` at setup top level — guard with `import.meta.client` or move to
+  lifecycle hooks. `if (import.meta.server) return` is the idiom for client-only ops code.
+- State shared between server render and client must use `useState`, not module-level `ref`s
+  (module state leaks **between requests** on the server).
+- Never patch globals (`window.fetch`, `console`) — see OPS_WEB.md §Logging.
+
+## 5. Props / emits / boundaries
+
+- `defineProps<{…}>()` + `withDefaults`, `defineEmits<{ save: [item: Item] }>()` — always typed.
+- Bricks receive **values**, emit **events**. They never import a store, never navigate, never
+  call the SDK. The page (L5) wires store ↔ brick and owns navigation.
+- Optional callbacks/slots change the UI (e.g. no `@delete` listener → hide the delete button):
+  use `defineSlots`/optional emits deliberately, document on the brick.
+
+## 6. SDK consumption (L2)
+
+- Wired ONCE in `app/plugins/sdk.ts` from `runtimeConfig` — components never instantiate it.
+- All calls go through repository composables in `app/composables/api/`, which map wire DTOs to
+  `domain/` models. Pages and stores call composables, never the SDK directly.
+- **Import the SDK from its package root (or `…/types` subpath) only.** Deep `…/src/…` imports
+  bypass the public contract and break on any internal refactor (ANTI_PATTERNS.md #3 — found in
+  22 files of one consumer). Enforce with `no-restricted-imports` once ESLint lands.
+- Every `catch` around an SDK call delegates to `useApiErrorHandler` (OPS_WEB.md §2).
+
+## 7. Stores (L5)
+
+- Pinia, only for state shared across pages (session, cart…). Module-local state lives in the
+  module's composable instead.
+- Stores are imported **explicitly from the `~/stores` barrel** — no directory auto-scan magic;
+  the import graph must stay visible.
+- Stores call L2 composables and `domain/` engines; they never touch components or routes.
+
+## 8. Strings, styles, sizes
+
+- **Every user-facing string goes through i18n** — including `aria-label`, `placeholder`,
+  `title`. Hardcoded copy in a template is a violation (I18N.md has the detector script spec).
+- **Visual values come from tokens**: `var(--ds-color-*)`, `var(--ds-space-*)`,
+  `var(--ds-radius-*)`, `var(--ds-font-*)`. A hex color or magic px in a component is a bug;
+  add a token instead.
+- Scoped styles per component; global styles only in `app/assets/css/` base files.
+
+## 9. Testing — real or absent
+
+- **Unit (vitest)**: `domain/` engines (exhaustive, table-driven), DS components (mounted with
+  `@vue/test-utils`, standalone — no Nuxt context), composables with logic. Colocated in each
+  module's `tests/`. Must pass from a clean checkout: `npm install && npm run test`.
+- **E2E (playwright)**: user journeys only, in `tests/e2e/`. `@playwright/test` is a real
+  devDependency with a real config; specs boot the dev server themselves.
+- A `package.json` script that cannot run from a clean checkout **is testing theater**
+  (ANTI_PATTERNS.md #10): either install the dependency and keep the test green, or delete the
+  script. Generated reports (`playwright-report/`, `coverage/`) are gitignored — a committed
+  report is a claim, a green run is proof (DELIVERY.md).
+- Every new domain rule ships with its test in the same change. No test, no rule.

package/templates/packs/nuxt-web/docs-architecture/I18N.md

@@ -0,0 +1,102 @@
+# I18N — module-per-feature translations, enforced parity
+
+Discipline for `@nuxtjs/i18n` (add the module the day the first user-facing string appears —
+which is usually day one). The unit of organization is the **feature module**, mirroring the
+code layout: a feature ships its strings the way it ships its components.
+
+## 1. Layout
+
+```
+i18n/
+  i18n.config.ts        # the ONE registration point: LOCALES + MODULES + static imports
+  GLOSSARY.md           # canonical translation of domain terms per locale
+  en/
+    common.json         # genuinely shared strings ONLY (generic buttons, generic errors)
+    errors.json         # API error names → messages (OPS_WEB.md §2 reads these)
+    <feature>.json      # one file per feature/page module (checkout.json, settings.json…)
+  fr/
+    …same files, same keys
+```
+
+Rules:
+- **One JSON module per feature, created WITH the feature.** A new L4/L5 module's definition of
+  done includes its `<feature>.json` in every locale.
+- A key used by exactly one feature lives in that feature's file. `common.json` is for strings
+  shared by ≥2 features — moving a key there is a deliberate promotion, like L5→L4 for code.
+- Keys are namespaced inside the module: `checkout.summary.title`, max 3 nesting levels.
+  Never reuse another feature's keys — duplication across features is correct here (copy
+  diverges per context; shared keys create accidental coupling).
+- Components consume strings only via `t('feature.…')` — including `aria-label`, `placeholder`,
+  `title` attributes and toast messages.
+
+## 2. Registration — static imports, one config
+
+Lazy per-file loading does not compose with module-per-feature splitting in a reliable way;
+register statically and let the bundler tree-shake:
+
+```ts
+// i18n/i18n.config.ts
+const LOCALES = ['en', 'fr'] as const
+const MODULES = ['common', 'errors', 'checkout'] as const   // ← add new modules HERE
+
+import en_common from './en/common.json'
+import en_errors from './en/errors.json'
+// … one import per (locale × module); the analyzer (§3) fails CI if one is missing
+
+export default defineI18nConfig(() => ({
+  legacy: false,
+  fallbackLocale: 'en',
+  messages: { en: { …merge en_* }, fr: { …merge fr_* } },
+}))
+```
+
+Adding a feature module = 1 file per locale + 1 entry in `MODULES` + 1 import line per locale.
+Adding a locale = 1 folder + 1 entry in `LOCALES` (copy `en/` as the starting point so the
+parity check drives the translation work).
+
+## 3. Parity enforcement — tooling, not vigilance
+
+Translations drift silently; humans don't notice a missing key until a user does. A small
+analyzer script (`scripts/check-i18n.*`, any language) runs locally and in CI with three checks:
+
+1. **Key parity (CI gate — fails the build):** every key present in one locale exists in all
+   locales, per module file. Missing file = every key missing.
+2. **Suspected untranslated (report):** keys whose values are byte-identical across locales.
+   Usually a pasted-but-never-translated copy.
+3. **Hardcoded strings (report → gate once clean):** scan `.vue` templates for literal
+   user-facing text outside `t()` calls (text nodes, `aria-label`, `placeholder`, `alt`).
+
+Wire it as `npm run i18n:check` and run it in the same CI job as the unit tests — translation
+breakage is a build failure, not a backlog ticket.
+
+> ⚠️ **Gotcha:** Symptom — the identical-values check drowns in false positives. Cause — brand
+> names, locale-invariant terms ("Premium", "API", product name) are *legitimately* identical.
+> Fix — the script maintains an explicit ignore list of keys/values; every addition to the list
+> is reviewed, so the report stays actionable instead of muted.
+
+> ⚠️ **Gotcha:** Symptom — a locale renders raw `{name}` braces to the user. Cause —
+> interpolation parameters present in one locale's string but missing/renamed in another;
+> key parity can't see it. Fix — the analyzer also compares the **set of `{param}` placeholders**
+> per key across locales and fails on mismatch.
+
+> ⚠️ **Gotcha:** Symptom — translated rich text renders as escaped HTML or, worse, injects
+> markup. Cause — HTML inside translation strings rendered with `v-html`. Fix — prefer
+> component interpolation (`<i18n-t>`); if HTML in translations is unavoidable, sanitize at
+> render time and say so next to the call site.
+
+## 4. GLOSSARY.md — domain terms decided once
+
+Every domain term gets one canonical translation per locale, recorded in `i18n/GLOSSARY.md`
+(term, per-locale translation, one-line definition, terms that must NOT be translated).
+Translators — human or agent — consult it before inventing a synonym. Inconsistent domain
+vocabulary across pages reads as three different products.
+
+## 5. Locale strategy
+
+- Detection: cookie-persisted choice + browser-language first visit. Expose a visible switcher.
+- URL strategy is an SEO decision, not an i18n one: `no_prefix` (locale invisible in URLs) is
+  fine for an app behind auth, but **indexable multilingual marketing pages need per-locale
+  URLs** (`prefix_except_default`) + `hreflang` — see SEO_AND_ROUTING.md. Decide deliberately
+  and record it in DECISIONS.md.
+- Dates, numbers and currencies go through `Intl` formatters in `app/utils/` (L0) — never
+  hand-formatted strings in templates.

package/templates/packs/nuxt-web/docs-architecture/OPS_WEB.md

@@ -0,0 +1,176 @@
+# OPS_WEB — analytics, errors, logging, flags, deploy
+
+The L1 ops layer plus the ship pipeline. Everything here is product-blind plumbing; if a
+snippet needs a domain type, it's in the wrong file.
+
+## 1. Analytics as code — the typed event catalog
+
+Event names scattered as inline strings make the tracking plan unauditable and typo-prone.
+The catalog **is** the tracking plan:
+
+```ts
+// app/constants/analytics.ts (L1)
+export const ANALYTICS_EVENTS = {
+  // Naming: [Context] [Action] [Element] — document expected props inline
+  SCROLL_DEPTH:     'Scroll Depth',        // props: { percent: 25|50|75|100, page }
+  CTA_HERO_PRIMARY: 'CTA Hero Primary',    // props: { page }
+  SIGNUP_COMPLETED: 'Signup Completed',
+} as const
+
+export type AnalyticsEvent = (typeof ANALYTICS_EVENTS)[keyof typeof ANALYTICS_EVENTS]
+
+export function trackEvent(
+  name: AnalyticsEvent,
+  props?: Record<string, string | number | boolean>,
+): void {
+  if (import.meta.server) return                       // SSR-safe by construction
+  window.yourProvider?.(name, props ? { props } : undefined)
+}
+```
+
+Rules:
+- **If an event name isn't in the catalog, the event doesn't exist.** A provider call with an
+  inline string anywhere else is a violation — grep for the provider symbol outside this file.
+- Props are documented next to each event; changing an event's name or props is reviewed like
+  an API change (dashboards are consumers).
+- Renamed events keep the old entry in a `// LEGACY` section until dashboards migrate, then die.
+- Behavioral tracking (scroll depth, section visibility) lives in dedicated composables that
+  import the catalog — components call `useScrollDepthTracking('pricing')`, never the provider.
+- Use a privacy-respecting, cookieless provider when possible; anything cookie-based goes
+  behind the consent manager.
+
+## 2. API errors — one handler, statusCode → severity
+
+UI code never inspects response bodies or invents error copy. The SDK normalizes every non-2xx
+into a typed `ApiError` (SDK_CONTRACT.md §2); the app maps it to UX exactly once:
+
+```ts
+// app/composables/useApiErrorHandler.ts
+const SEVERITY: Record<number, 'warning' | 'error'> = {
+  409: 'warning',   // conflict: "already exists" — recoverable, don't alarm
+  423: 'warning',   // locked / temporarily unavailable
+}
+
+export function useApiErrorHandler() {
+  const { t, te } = useI18n()
+  const toast = useToast()
+
+  function handleError(error: unknown, overrides?: Record<number, string>): void {
+    if (isApiError(error)) {                        // type guard exported by the SDK
+      const key = `errors.api.${error.errorName}`   // wire contract → i18n/errors.json
+      const message = overrides?.[error.statusCode] ?? (te(key) ? t(key) : t('errors.generic'))
+      toast[SEVERITY[error.statusCode] ?? 'error'](message)
+      return
+    }
+    toast.error(t('errors.generic'))                // never leak raw Error.message to users
+  }
+  return { handleError }
+}
+```
+
+Usage — per-call overrides for context-specific copy:
+
+```ts
+try { await useTeamsApi().create(input) }
+catch (e) { handleError(e, { 409: t('teams.alreadyExists') }) }
+```
+
+Rules: every `catch` around an L2 call delegates here · 401 is NOT handled here (the SDK's
+session layer owns refresh/logout — SDK_CONTRACT.md §3) · raw `error.message` never reaches
+a toast (it's developer text, often English-only, sometimes sensitive).
+
+## 3. Logging — injected, never monkey-patched
+
+One logger module in `app/utils/logger.ts` (level from runtime config, structured meta), exposed
+to app code via plugins (`logger.client.ts`, `logger.server.ts`). Production builds drop stray
+`console.*` (esbuild `drop`), so the logger is the only voice that survives.
+
+> ⚠️ **Gotcha:** Symptom — every HTTP request in the app gets logged twice, aborts and streamed
+> responses behave oddly, and nobody can find *where* the logging comes from. Cause — a plugin
+> reassigned `window.fetch` to a logging wrapper. Patched globals are invisible at call sites,
+> stack with every other patcher, double-instrument SDK traffic that already has its own logging
+> port, and subtly break fetch semantics. Fix — instrument the boundaries you own: the SDK's
+> injected logger (SDK_CONTRACT.md §5) and, for app-local calls, a created client —
+> `$fetch.create({ onRequest, onResponse, onResponseError })` — that callers import knowingly.
+
+## 4. Feature flags — fail closed
+
+```ts
+// app/utils/flags.ts (L0 pure) — read via useRuntimeConfig in a composable (L1)
+const TRUTHY = new Set(['true', '1'])
+export function flagEnabled(value: string | boolean | undefined | null): boolean {
+  if (typeof value === 'boolean') return value
+  if (value == null) return false                       // missing means OFF
+  return TRUTHY.has(String(value).trim().toLowerCase()) // unknown means OFF
+}
+```
+
+Misconfiguration must disable the feature, never enable it. Parsers like `value !== 'false'`
+turn every typo into a silent activation (ANTI_PATTERNS.md #8 — found in production). When a
+flag evaluates to off because the value was unrecognized, log a warning naming the variable.
+
+## 5. Runtime config — one shape, runtime overrides
+
+- Declare every key in `runtimeConfig` (server) / `runtimeConfig.public` (client-visible) with
+  a safe default. Override at **runtime** via `NUXT_<KEY>` / `NUXT_PUBLIC_<KEY>` env vars.
+- Secrets live server-side only. A secret in `public` ships to every browser.
+- Because public values are runtime-overridable, **one image serves all environments** — don't
+  bake per-environment URLs at build time (see §6).
+
+## 6. Docker — multi-stage, BuildKit secrets, tiny runtime
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+# Private registry/git auth: BuildKit secret — NEVER a build ARG.
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
+COPY . .
+RUN npm run build                                  # → .output/ (self-contained Nitro server)
+
+FROM node:22-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/.output ./.output
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD wget -qO- http://127.0.0.1:3000/api/health || exit 1
+CMD ["node", ".output/server/index.mjs"]
+```
+
+Build: `docker build --secret id=npmrc,src=$HOME/.npmrc -t app .`
+Ship a `.dockerignore` (node_modules, .nuxt, .output, .env*, test artifacts) or the builder
+context uploads your laptop.
+
+> ⚠️ **Gotcha:** Symptom — a repo access token readable by anyone who can pull the image.
+> Cause — the token entered the build as an `ARG` and was written into git config in a `RUN`
+> layer; `docker history` and layer caches preserve both. Fix — BuildKit secret mounts: the
+> secret exists only during the single `RUN` it's mounted into and never lands in a layer.
+
+> ⚠️ **Gotcha:** Symptom — every new config variable must be edited in four places (workflow
+> secrets, Dockerfile ARGs, Dockerfile ENVs, compose file) and someone always misses one.
+> Cause — public config baked at build time forces the whole env through build args. Fix — §5:
+> runtime `NUXT_*` overrides; build args only for values that genuinely change the build output.
+
+## 7. Health & deploy gate — one endpoint, every consumer
+
+```ts
+// server/api/health.get.ts — already in the skeleton
+export default defineEventHandler(() => ({ status: 'ok', service: '…', time: … }))
+```
+
+- **Exactly one health endpoint.** The Docker HEALTHCHECK, the orchestrator/reverse-proxy
+  check, the deploy gate and uptime monitoring all hit `/api/health`. Two "health" URLs WILL
+  diverge, and the one your alerting watches will be the stale one.
+- The deploy pipeline's last step curls it on the live host and fails the deploy on non-200 —
+  proof over claims (DELIVERY.md), applied to infrastructure.
+- Keep it dependency-free (no DB call) unless a dependency genuinely gates "alive"; if you add
+  readiness checks later, extend the same endpoint's payload, don't add a second URL.
+
+## 8. Error monitoring
+
+Add a crash/error reporter (client + server) before the first real user, not after the first
+real incident. Requirements: source maps uploaded at build (hidden from the public bundle),
+environment tag from runtime config, and the `useApiErrorHandler` path reports unexpected
+(5xx/unknown) errors — expected 4xx noise stays out of the alert channel.