@vegastack/skills 0.9.0 → 0.10.0

package/skill/architect/references/mobile.md

@@ -1,78 +0,0 @@
-# Mobile — Flutter production doctrine
-
-**The Flutter app is a separate repo from the web/API repo** — it consumes the Next.js
-REST/OpenAPI contract as one more client, never a `mobile/` directory in the web monorepo
-(ADR-recorded, corroborated three ways; an expensive structural call to get wrong).
-
-Flutter is the production mobile framework when a product needs a mobile app (not all do —
-the profile records it). Baseline: Flutter 3.44.x stable; Impeller is the default renderer
-on iOS and Android API 29+ (falls back below 29 — test one API<29 device before shipping).
-Package versions here were verified 2026-08; re-verify on pub.dev before pinning.
-
-Evidence tiers in this file: rules drawn from the shipped VegaStack app are stated plainly;
-rules from official-docs research that MK has not yet ratified are tagged "(inferred)" —
-confirm those on first use, per SKILL.md.
-
-## Architecture (official-guidance derived — inferred where the shipped app is silent)
-
-- MVVM per official flutter.dev/app-architecture: View (widget, no logic) → ViewModel
-  (state + commands, 1:1 with its View) → Repository (source of truth, caching/retry,
-  never depends on another repository) → Service (thin stateless API/platform wrapper).
-  Skip the optional domain/use-case layer until logic is reused across ≥2 ViewModels.
-- Project structure is layer-first: `lib/{data, domain, ui, routing, config}`, feature
-  folders nested inside `ui/`, shared widgets in `ui/core/`. (Blog "feature-first is the
-  standard" claims don't survive verification — the official reference app, Compass, is
-  layer-first. Feature-first is a valid escalation once app/team size demands it.)
-- Class names mirror roles: `HomeViewModel`, `HomeScreen`, `UserRepository`,
-  `ClientApiService`.
-
-## State management — lean by default
-
-- Plain `ChangeNotifier`/`ValueNotifier` ViewModels with hand-wired constructor injection
-  in `main.dart`. Zero extra dependencies, zero codegen — this matches both official
-  guidance ("personal preference") and what VegaStack has actually shipped.
-- Escalate to Riverpod only when async state genuinely needs sharing across ≥3 widgets,
-  tests need provider-override mocking, or a second app shares a state-heavy module.
-  No get_it — official docs steer away from service locators; `provider` is the official
-  DI pick if constructor wiring ever gets unwieldy.
-
-## Networking & auth
-
-- One `dio` client centralized in a single `ApiClient` — never scattered HTTP calls.
-  The app consumes the same contract-first REST API as the web app (web.md).
-- Auth is the same Better Auth instance as web, via the bearer plugin: capture the token
-  from the `set-auth-token` response header on sign-in; store it in
-  `flutter_secure_storage` (never shared_preferences); attach `Authorization: Bearer` via
-  a dio interceptor; clear storage and route to sign-in on 401.
-- Do NOT depend on `better_auth_flutter` (0.1.0, negligible adoption as of 2026-08) —
-  hand-roll the interceptor; revisit at a real 1.0.
-- `shared_preferences` for non-secret local metadata only. `drift` only if genuine
-  offline/relational needs exist — never speculatively.
-
-## Design system on mobile
-
-- Material 3 (default since 3.16); semantic colors via a hand-authored `ColorScheme` plus
-  `ThemeExtension` for tokens outside Material's roles — mirroring the web design-system
-  token names 1:1 from one Dart source of truth.
-- House taste mapped: `CardTheme(elevation: 0)` with `outlineVariant` borders (flat,
-  borders-only); TextTheme capped at `FontWeight.w600`, never bold; subtle motion with
-  reduced-motion respected; Lucide-style iconography.
-
-## Navigation, models, testing, deploy
-
-- Navigation: the shipped app uses plain `Navigator`; `go_router` is the official Flutter
-  team pick for route-heavy apps (inferred) — adopt it when deep links/route state demand
-  it, not by reflex.
-- Models: the shipped app hand-writes all models — stay hand-written by default; freezed +
-  json_serializable only when codegen demonstrably earns its build cost (inferred
-  threshold, not MK-ratified).
-- Test where MVVM pays off: unit-test ViewModels and Repositories; widget-test critical
-  screens; integration tests only for can't-ship-broken flows (sign-in, payment). Golden
-  tests, if adopted: `alchemist` over the discontinued `golden_toolkit` (inferred — no
-  VegaStack golden-test precedent yet).
-- Deploy: GitHub Actions is the house CI; Fastlane for store signing/upload and real build
-  flavors (`--flavor` + per-env entry points) are the researched defaults (inferred — no
-  shipped store-deploy precedent yet; confirm before wiring).
-
-Undecided (ask MK rather than assume): push-notification provider preference, offline/sync
-expectations per product, store-release cadence.

package/skill/architect/references/principles.md

@@ -1,91 +0,0 @@
-# Principles — how VegaStack decides
-
-How MK actually makes architecture decisions, distilled from seven months of his sessions
-and repos. Each rule carries its why — apply the reasoning, not just the rule.
-
-## Build lean first
-
-One deployable until a concrete requirement forces a split. A single, properly structured
-Next.js app owns the UI, RSC, route handlers, auth, and the REST/OpenAPI control plane — no
-NestJS or Hono beside it, no speculative queue, cache, or worker. A notification sender is a
-cron handler inside the app, not its own deployable. **Why:** agents habitually propose
-services MK then has to strip out ("why do we still need workers like extra bloat or
-maintenance surface?"). On a 3-4 person team, every moving part is real maintenance, and the
-lean version is usually also the faster and more reliable one.
-
-Lean-first governs the *count of moving parts*, not the rigor inside each part.
-Correctness-critical logic — money, auth, tenancy, audit, secrets — always gets full rigor.
-
-## Every moving part names its trigger
-
-Propose infrastructure only together with the trigger that justifies it, stated in the
-recommendation: "a separate worker WHEN jobs exceed request timeouts", "a queue WHEN volume
-makes inline processing lossy", "OpenBao WHEN self-hosting customer-managed secrets".
-Provision only what the current build phase actually uses — infrastructure tracks real
-usage, never anticipated usage. **Why:** MK stated "OpenBao mandatory in production" and
-walked it back five days later ("some projects are just simple and straightforward").
-Blanket mandates rot; triggers stay true as projects differ.
-
-## Pre-launch means delete, not migrate
-
-Zero real users = no backward compatibility, no legacy shims, no deprecation windows, no
-feature flags hiding unfinished work. Delete outright; reset the dev database rather than
-writing migration chains. This is the DEFAULT — most VegaStack projects are pre-launch at
-any given time. Expand/migrate/contract discipline begins when real users exist, not before.
-**Why:** carrying compatibility for users who don't exist is pure bloat ("NO FEATURE FLAGS
-PLEASE... i dont want any backwards compatibility as this is an unreleased app").
-One exception: a versioned API contract consumed by a shipped mobile app counts as having
-real users even while the web side iterates freely — app-store install lag keeps old
-clients alive (mobile.md).
-
-## Reuse before you build new
-
-Extend the existing table, service, or spine (ACL, change-log, outbox, realtime channel)
-before creating a parallel one. When two components do the same job, merge them into one
-canonical source. Promote a util to `/lib` the moment a second feature uses it. **Why:**
-duplicated systems of record are the reference-architecture mistake MK explicitly engineers
-against; two sources of the same truth always drift.
-
-## Enforce boundaries mechanically
-
-Architectural boundaries that matter get a CI guard script that fails the build — monorepo
-import direction (apps → packages, never the reverse; workers never import UI/React),
-runtime gravity (below), server/client code separation. **Why:** convention alone was tried
-and failed; a guard script is cheaper than re-reviewing the same violation forever.
-
-## Runtime gravity: long-running work never lives in the request tier
-
-Anything that can run long, hold a connection, or outlive a request — agent execution, job
-processing, media pipelines — runs in a separate worker/runner tier, never inside a route
-handler or an OpenNext Worker. **Why:** request-scoped tiers have timeouts and body limits;
-the reference codebase MK studied executed workflows inside Next.js handlers and it is the
-single anti-pattern he cites most.
-
-## Effort scales with stakes, not habit
-
-Security, auth, tenancy, money, and architecture foundations get generous, thorough,
-adversarial treatment. Routine features on a small team get medium thoroughness — do a cheap
-reconnaissance pass before committing to full-cost work, and don't build governance ceremony
-a 3-4 person team will never exercise. **Why:** MK's own most recent self-correction — his
-previous architecture skill "got too complicated" by applying flagship-platform rigor
-everywhere.
-
-## Decisions are verified, recorded, and reversible for a reason
-
-- Resolve uncertainty with evidence, never with the safer-sounding guess: check the live
-  official docs (current year), verify the claimed constraint, then decide. MK refused to
-  accept an unverified "Better Auth forces text UUID columns" claim — it was false.
-- Present decisions as 2-3 options with a clear recommendation and the tradeoff that
-  matters, then record what was chosen and why (an ADR or one dated ledger line).
-- MK reverses when: a verified assumption proves false · added cleverness regresses UX ·
-  a heavyweight mandate meets a simple project · his own tooling over-complicates. He
-  reverses toward less machinery on low stakes and toward more rigor only when a concrete
-  bug or vulnerability is found. Anticipate this: don't defend machinery he'd delete.
-
-## Context gates rigor — ask, don't assume
-
-Rigor flexes on facts, not labels: pre-launch or live · internal, client, or OSS ·
-self-hosted or managed · handles money/PII or not · has real users or not. These live in
-`.vegastack/arch.md`. Client work gets the same approval gates and honesty as internal work
-— if anything, more documentation, never less. When two recorded decisions conflict or the
-profile can't answer, ask MK with a recommendation instead of assuming.

package/skill/architect/references/project-profile.md

@@ -1,37 +0,0 @@
-# Project profile — `.vegastack/arch.md`
-
-The per-project memory that stops every session from re-deriving the same facts. It is a
-head start, never the source of truth: the repository wins every disagreement.
-
-## First run in a project
-
-If `.vegastack/arch.md` does not exist and the task is architectural:
-
-1. First infer what you can from the repo — package.json/lockfile (runtime), wrangler
-   files (Cloudflare; a `d1_databases` binding with no Postgres driver = the D1-only
-   product class), Dockerfiles/compose (self-managed), drizzle config (database),
-   better-auth usage, `@aws-sdk/client-s3`/R2 bindings (storage), pg-boss dependency
-   (jobs), `eve`/`ai` packages (agents vs plain AI features), pubspec.yaml (mobile).
-2. Ask MK or the team member only what the repo can't answer, in one short message:
-   - Where does this deploy? (Cloudflare Workers via OpenNext · self-managed server ·
-     both · exception: Vercel)
-   - Stage and kind? (pre-launch or live · internal, client, or oss)
-   - Anything non-default? (mobile app, agents, separate workers, unusual services)
-3. Write `.vegastack/arch.md` from [the template](../assets/arch-template.md), show it,
-   and confirm before relying on it. Creating the file needs the same write authorization
-   as any other file.
-
-Never create the file during a purely read-only task or an explanation — suggest it instead.
-
-## Every later run
-
-- Read the file, then trust the repo over it. If the repo disagrees (the file says bun but
-  the lockfile is pnpm-lock.yaml; a wrangler.jsonc appeared; a mobile/ directory exists),
-  say so and propose the exact one-line file update. Never silently follow a stale profile,
-  and never silently rewrite it either.
-- Decisions and their dates belong in the `notes:` lines — one line per decision ("2026-08:
-  DO for realtime only, dropped for chat — SSE+Postgres instead"). This is the project's
-  decision ledger; keep entries short and dated.
-- If the file records something that contradicts this skill's defaults, the file wins for
-  that project — it is a recorded decision. Report it as accepted risk only if it crosses
-  a red line.

package/skill/architect/references/stack.md

@@ -1,38 +0,0 @@
-# Stack — locked decisions
-
-The VegaStack default stack. "Not" columns are real rejections MK has made — do not
-re-propose them without new facts. Current versions and platform caveats live in
-[pinned-facts](pinned-facts.md); check there before pinning a version.
-
-| Area | Use | Not | Why |
-|---|---|---|---|
-| Web framework | Next.js 16 App Router, one app | NestJS, Hono, a second backend | A properly structured Next app owns web + API + auth for web, Flutter, MCP, and public consumers; a second framework is pure maintenance surface |
-| Runtime / package manager | Bun (default for new projects); pnpm fully sanctioned where chosen | npm, yarn — never | One lockfile discipline per project; the profile records which. Commit text lockfiles (`bun.lock`, not `bun.lockb`) |
-| Auth | Better Auth: email/password + Google sign-in by default; organizations plugin (teams enabled) for orgs/workspaces/teams; bearer plugin for mobile; apiKey plugin for API keys | Hand-rolled auth, custom user-groups schema, Auth0/Clerk | Owner-stated standing rule. Organization maps to workspace (`modelName: "workspace"` pattern); teams = Better Auth teams; prefer the shipped plugins over native builds unless a project records why |
-| Database | PostgreSQL, always self-managed by us: PlanetScale Postgres server or self-hosted (Hetzner or similar). PG 17 behind Hyperdrive; 17/18 otherwise. D1-only is a recorded exception for the minimal Cloudflare-native product class (vegastack-pages/vegafactory precedent, locked 2026-05-20) — check `.vegastack/arch.md` before assuming Postgres | Neon (never), D1 as a secondary store beside Postgres, MySQL | "We don't use neon at all." One datastore per product; Hyperdrive caps at PG 17.x (see pinned-facts). D1's sanctioned sidecar case: a Worker-scoped idempotency table for Stripe webhooks — Postgres still owns the ledger |
-| ORM | Drizzle + drizzle-kit, single `postgres-js` driver | Prisma | House standard across every repo since Feb 2026 |
-| DB from Workers | Hyperdrive binding, per-request client (`prepare: false, max: 1`, request-scoped) | Global pools, TCP clients (ioredis) in Workers | workerd forbids I/O across requests; a module-level pool is a bug, not a style choice |
-| Storage | Cloudflare R2 (S3-compatible API), presigned URLs, short-lived scoped access | S3 + CloudFront by reflex | R2 egress is $0 at any scale — the cost problem S3+CDN solves doesn't exist here. For licensed self-hosted deployments, keep the S3 protocol boundary so any S3 provider or MinIO works |
-| Cache / Redis | None by default. Rate limiting and caching Postgres-native; Workers KV only with a named trigger (e.g. read-mostly config/session cache at request volumes where a Postgres round-trip measurably hurts — as in the recorded auth-cache migration); a Redis-class store never correctness-bearing | Upstash Redis (migrated off), Redis "because caching" | "No Redis in P1" — a cache layer is a moving part; Postgres already exists. Never cache authorization/role data aggressively |
-| Jobs / cron | pg-boss on the existing Postgres, dispatcher-only — lease/heartbeat/retry state of authority lives in our own tables. Cron parsing/description: `croner` (DST/IANA-aware) + `cronstrue` (human-readable) | BullMQ+Redis, Temporal, CF Queues by default; `node-cron`, `cron-parser` | Jobs are simple; Postgres is already there. Owning durability state keeps the queue library swappable; croner/cronstrue are the battle-tested cron pair (a cron-parser swap was made and corrected once already) |
-| Agent execution | EVE (Vercel's `eve`, beta): on Vercel as Functions with Fluid Compute (recorded per-project exception), or self-hosted as its own long-running Node/OCI service with `@workflow/world-postgres` | EVE inside an OpenNext Worker or any request-scoped/edge function | EVE's Postgres world explicitly requires a long-lived worker process — "not compatible with serverless platforms". EVE owns agent sessions; pg-boss owns generic jobs — complementary, never conflated |
-| AI calls | AI SDK v7 (`ai@^7`) behind a thin adapter; Anthropic default provider; Cloudflare AI Gateway for routing/telemetry when on Cloudflare | Hardcoded model IDs scattered in code, per-provider SDKs everywhere | Adapter keeps providers swappable; the gateway centralizes cost/telemetry without building it |
-| Design system | Consume `@vegastack/design` + `@vegastack/ui` (Base UI primitives, semantic tokens) | Creating/modifying components upstream, raw shadcn edits, Radix for new work | Consume, don't extend — upstream changes are MK's deliberate decision. Base UI locked over Radix 2026-07 |
-| Frontend state | Server state via RSC + TanStack Query; URL state via nuqs; ephemeral UI state via Zustand | Persisting remote/tenant data client-side (IndexedDB/local-first) for multi-tenant SaaS | Governance: tenant data never rests on the client. Local-first only for a confirmed single-tenant/offline product — ask first |
-| Realtime | SSE tailing an event log first; Durable Objects (SQLite, WebSocket hibernation) when on Cloudflare and bidirectional state is real. One DO per collaboration scope (a `WorkspaceHub` for presence/signals, a per-document `PageSync` for edit traffic) — never one monolithic DO | socket.io + Redis pub/sub, Ably, Pusher | SSE covers most "live" needs with zero new services; hibernating DOs bill ~nothing while idle. Third-party realtime vendors were migrated off |
-| Collaborative editing | Tiptap editor (markdown as source of truth), Yjs CRDT sync via `y-partyserver` inside the document DO; server-side sanitization/versioning still applies to every CRDT write | CodeMirror (abandoned 2026-05-21), ElectricSQL (removed), RxDB (reversed to plain Dexie where local cache is needed) | Locked through real reversals; CRDT must never become an XSS/version/audit bypass |
-| Analytics | Self-hosted Plausible (`pb.vegastack.com`), proxied via `next-plausible` where applicable | Google Analytics, Vercel Analytics, PostHog by default | Self-hosted, privacy-clean, already running — recurs across 5 projects |
-| Hosting | Cloudflare Workers via OpenNext, or self-managed servers (Docker; Coolify for push-to-deploy). Both recorded in the profile | Vercel as a default (allowed only by explicit per-project exception, recorded); a parallel Vercel path once committed to Cloudflare | Cost and egress economics favor Cloudflare/self-host; split deploy paths drift. EVE-hosted workloads are a legitimate Vercel exception |
-| Email | AWS SES (behind an adapter); handle bounces/complaints via the SNS-webhook pattern into a suppression list | Per-vendor SDK sprawl, sending to suppressed addresses | Cheap, boring, already proven in-house; unhandled bounces poison sender reputation |
-| Payments | Stripe; webhook intake isolated (own worker or route) with idempotent event handling | Building billing logic inside request handlers | Money paths get the full rigor tier: idempotency keys, event dedupe, DLQ |
-| Monorepo | Turborepo + workspaces (Bun or pnpm) when there is more than one package; apps → packages only, enforced by a boundary check | Deep relative cross-package imports, packages importing apps | Import direction is a guard script, not a convention |
-| i18n | next-intl, `localePrefix: 'as-needed'`; no hardcoded user-facing strings | Ad-hoc string tables | Already the proven pattern; English-only today but scaffolded |
-| APIs | Contract-first: zod schemas → OpenAPI 3.1; auth before parse; cursor pagination on every list; RFC 9457 problem-details errors | Route-local validation, raw `request.json()`, unbounded lists | One contract feeds web, Flutter, MCP, and public consumers; sanitize responses (never return secrets/credential refs) |
-
-## Choosing between the two hosting targets
-
-Cloudflare (OpenNext) when: public web product, global latency matters, R2/DO/Queues fit,
-cost-per-request dominates. Self-managed (Docker/Hetzner) when: self-hosting is a product
-requirement (licensed/enterprise), the workload needs long-lived processes (EVE, heavy
-workers), or platform independence is worth ~30 min/month of ops. Many products use both:
-OpenNext app on Cloudflare + a long-running worker container beside the database.

package/skill/architect/references/web.md

@@ -1,152 +0,0 @@
-# Web — frontend, design system, backend/API taste
-
-## Project layout
-
-- Top-level `server/` (or `packages/*` server code) holds DB, services, integrations — it
-  is sacred: never imported from client code, enforced with `server-only` + a boundary
-  check. The app router lives in `src/app/`; features are self-contained modules under
-  `src/features/<domain>/` (components/hooks per feature); shared pieces in
-  `src/{components,hooks,lib,store,messages}/`. Pages stay thin — they compose features.
-- The house convention scopes agent instructions per directory (a short CLAUDE.md/AGENTS.md
-  at each boundary-bearing directory) — follow it where a project already does this.
-
-## Frontend architecture
-
-- Server state → RSC + TanStack Query; URL state → nuqs; ephemeral UI state → Zustand.
-  Remote/tenant data is never persisted client-side (IndexedDB/local-first was evaluated and
-  rejected for multi-tenant SaaS on governance grounds — a confirmed single-tenant/offline
-  product is the only exception, and that's a decision to ask for, not assume).
-- Next config: `output: 'standalone'`, `cacheComponents: true` (PPR flags no longer exist).
-  Query key factories live in non-`'use client'` `.keys.ts` modules so RSC pages can prefetch.
-- Server Components by default; `'use client'` only at the lowest leaf that needs it.
-  `/server` (or `packages/*` server code) is never imported from client code — `server-only`
-  plus a boundary check, not convention.
-- Request interception: on OpenNext/Cloudflare, `proxy.ts`/Node middleware does NOT work
-  as of 2026-08 (open adapter issues — see infra.md); use what the adapter actually
-  supports and re-check its docs per feature. Either way interception is never the auth
-  boundary (see security.md).
-- Internal navigation uses `next/link`; bare `<a>` only for true external links/downloads.
-- Never TypeScript `any` — `unknown` and narrow.
-- Dependencies: prefer the native/browser API when it covers the need
-  (`Intl.RelativeTimeFormat` over date-fns); self-implement simple behavior (a tween, a diff
-  view) by composing design-system primitives before adding a library; any non-trivial new
-  dependency needs a stated justification and approval. **Why:** self-contained code has no
-  supply-chain, licensing, or upgrade surface, and MK rejects "library because library".
-
-## Design system (consuming `@vegastack/design` / `@vegastack/ui`)
-
-- First-time setup in a fresh project (npm install, Tailwind wiring, provider, registry
-  auth) is a separate, already-built skill — `vegastack-consume` — use it; don't
-  re-derive the wiring here.
-- Consume through the package barrel, never deep imports; never edit shipped component files.
-  A missing component or variant is an upstream request MK decides — the recommended
-  interim pattern is a local presentational composition in the app (inferred — confirm on
-  first use); don't fork the system.
-- Semantic tokens only: no inline `style={}`, no arbitrary values (`bg-[#123]`, `h-[13px]`),
-  no raw palette classes (`bg-neutral-900`), not even for opacity. Dynamic values go through
-  CSS custom properties.
-- Visual language: borders-only cards, flat surfaces (shadows only for true overlays); accent
-  color rationed to the primary action and real selected/active state — never hover, roughly
-  ≤10 accent elements a page. Focus stays visible always (WCAG 2.2 AA floor) — the house
-  mechanism is a darker border or native outline, never a `ring-*` utility. Control heights
-  on the 28/32/40 scale = `h-7`/`h-8`/`h-10` (no off-scale `h-9`); radius: `rounded-md`
-  controls, `rounded-sm` menu items, `rounded-lg` containers, `rounded-full` pills — never
-  `rounded-xl` on cards/dialogs. Touch-target minimum is genuinely unresolved (24px WCAG AA
-  vs 44px mobile-HIG both appear in the record) — ask MK when it matters.
-- Typography: product code caps at `font-semibold` and uses it sparingly (inside the design
-  system package itself the cap is `font-medium`); headings `font-lora`; numbers, versions,
-  costs, and card digits always `font-mono`; uppercase only in mono at ≤14px. Fonts are
-  self-hosted via `next/font` — never a Google Fonts CDN request.
-- Icons: Lucide only. Toasts: sonner, never native/OS prompts. 4px spacing scale.
-- Motion: subtle and minimal — no button hover/press animations, no `transition-all`; motion
-  is for state feedback (success/error) and structural changes. `prefers-reduced-motion`
-  disables animation entirely (instant, not softened).
-- No decorative filler: no gratuitous badges, eyebrow text, or "3 of 3" counters — MK cuts
-  these on sight as AI-generated design tells.
-- Light AND dark theme on every shipped surface (internal-only tools may opt out, stated
-  up front).
-
-## UI completeness bar (every real surface, before it's "done")
-
-- Full state matrix: loading skeleton shaped like the real content · empty state with
-  guidance · error routed to the specific failure (401/403, 404, 410, 429, generic — never
-  swallowed into `{}`) · success feedback. Optimistic updates where a mutation changes
-  visible state; the UI reflects backend mutations without a manual refresh.
-- Forms: Enter submits; spinner replaces the button icon (not beside it); first field
-  auto-focused; all fields disabled while the primary action runs; state resets on error or
-  navigation.
-- Responsive: no horizontal scroll at any width; computed layout math, never hardcoded pixel
-  offsets; truncation driven by available space, not character counts; iOS inputs must not
-  zoom on focus; the mobile keyboard must never occlude the active input.
-- Systemic fixes: a defect found in one component (scroll leaking through an overlay, missing
-  cursor, wrong token) is fixed across the whole family in one sweep, with evidence.
-- Perceived speed is the named pattern "instant shell": the layout shell renders
-  immediately (RSC + `cacheComponents`), every data region streams in behind a skeleton
-  shaped like its content — never a blank page or a full-page spinner.
-- Long lists (>~50 rows) virtualize with `@tanstack/react-virtual` (the approved package —
-  still state the justification when adding it).
-- Cloning/rebranding a reference site: strip every trace of the source tool's provenance
-  (class names, external asset domains, meta) so the result is fully self-contained, and
-  verify parity by clicking through as a real user — screenshot diffing alone doesn't count.
-
-## SEO and metadata (every public-facing app)
-
-- Every route exports `metadata`/`generateMetadata` — not just the root layout. Public
-  apps ship `sitemap.ts` and `robots.ts`; `llms.txt` is generated at build time, never
-  hand-maintained. OG images follow the house convention (generated, mono for
-  names/numbers). i18n uses next-intl `localePrefix: 'as-needed'` (stack.md) so default-
-  locale URLs stay clean. **Why:** MK has demanded "100% SEO" coverage on shipped sites
-  twice — treat it as a completeness bar, not an enhancement.
-
-## Testing (web/backend — test where it pays off)
-
-- Unit-test services and pure logic (Vitest); component/a11y tests run in Vitest browser
-  mode with the Playwright provider (real Chromium — jsdom's ARIA/layout gaps produce
-  false a11y results and are not trusted).
-- E2E is a walking skeleton: one real happy path (boot → auth → core mutation → verify)
-  plus targeted adversarial invariants — not a blanket suite. DB-gated tests are authored
-  even when execution is blocked, and gated behind an env flag (`RUN_DB_TESTS=1` pattern);
-  E2E doubles implement real ports, never a parallel mock pathway.
-- Every confirmed bug gets a regression test; no coverage-percentage targets — "100%"
-  means audit completeness, never a coverage metric. VRT/demo content is deterministic
-  (no `Date.now()`/`Math.random()`).
-
-## Backend / API design
-
-- Contract-first: zod schemas are the single source → OpenAPI 3.1 under `/api/v1`, camelCase,
-  cursor pagination on every list, RFC 9457 problem-details errors with a stable error-code
-  catalog. One contract serves web, Flutter, MCP, and public consumers.
-- Every route: auth before parse, through the shared route-handler wrapper — no route-local
-  zod, no raw `request.json()`. Sanitize responses: secrets and credential references never
-  leave the server. Enforce with a CI ratchet (unwrapped routes fail the build), not review.
-- Return what the view renders, not everything — no mega-responses. Select columns explicitly.
-- Body limits stream: count bytes as they arrive and abort at the limit; never buffer the
-  whole body first.
-- Webhooks over polling; the database is the source of truth. Once provider state lands in
-  Postgres via webhook, don't re-poll the provider — and don't build intermediary "waiting"
-  pages; redirect on success and let the rest arrive in the background.
-- Money paths (Stripe): isolated intake (own worker or route), idempotency keys on every
-  mutation, event dedupe, append-only ledgers as the single cost source of truth, audit
-  events written in the same transaction as the business change. Pricing/quoting math is
-  deterministic code with server-enforced invariants — AI drafts and judges; deterministic
-  code calculates and enforces (a proven client-project pattern; treat as the strong
-  default for money paths).
-- Centralize the boring: one ID helper (never raw `crypto.randomUUID` scattered), one logger
-  (never `console.log`; request/org context auto-injected; never log secrets or PII beyond
-  user IDs), one typed fail-hard zod env parser validated at startup — no
-  `DISABLE_AUTH`-style escape hatches, no plaintext fallbacks.
-- Dead endpoints get deleted, not deprecated-and-kept. (Exception: a versioned `/api/v1`
-  contract consumed by a shipped mobile app outlives web deploy cycles — app-store install
-  lag means mobile clients keep the old contract alive; see mobile.md.)
-- Outbound webhooks to customers (when a product offers them): a defined event catalog,
-  Standard Webhooks-style signing with rotatable secrets, delivery via the transactional
-  outbox → queue with retries/backoff, auto-disable an endpoint after N consecutive
-  failures, and a replay surface. Never fire webhooks inline from request handlers.
-- Platform-native mentions over plain text: when the data allows it, resolve and mention
-  the real entity (Slack user @mentions, Notion Person fields) instead of rendering names
-  as text — the recurring "don't just fix, improve" integration principle.
-- Wizard/checkout flow-state persistence (Zustand + sessionStorage vs server-side draft)
-  is not yet a settled house rule — ask MK when building one.
-- Rate-limited responses return 429 with a `Retry-After` header.
-- Timestamps stored UTC (`timestamptz`), rendered in the user's timezone; durations as
-  integer milliseconds; money in integer minor units.