@vegastack/skills 0.5.0 → 0.6.0

package/skill/architect/references/mobile.md

@@ -0,0 +1,78 @@
+# 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/pinned-facts.md

@@ -0,0 +1,108 @@
+# Pinned platform facts
+
+Dated, source-verified facts that change architecture decisions and that models routinely
+get wrong from stale training data. This is the ONLY file in this skill that goes stale by
+itself — the weekly refresh (see refresh/REFRESH.md) re-verifies it. When a recommendation
+leans on a fact older than 60 days, re-verify that one fact against its source first.
+
+All facts below verified 2026-08-12.
+
+## Cloudflare
+
+- **R2 egress is $0 at any volume.** A 500GB-stored / 2TB-served workload is ~$191/mo on
+  S3 vs ~$7.50/mo on R2. Reaching for S3+CloudFront "to control egress" solves a problem R2
+  doesn't have. Lifecycle rules, bucket locks, event notifications, and Infrequent Access
+  are all live — note IA transitions are one-way via lifecycle (IA→Standard needs a manual
+  CopyObject). [developers.cloudflare.com/r2/pricing]
+- **Hyperdrive supports PostgreSQL 9.0–17.x — PG 18 is NOT supported.** Target Postgres 17
+  for any Hyperdrive-fronted database; re-check the supported-versions page before ever
+  moving to 18. Hyperdrive also supports MySQL (GA 2026-08-07) and private DBs via Workers
+  VPC. [developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features]
+- **Durable Objects default to SQLite storage** (real SQL, transactions, point-in-time
+  recovery), and **hibernating WebSocket DOs bill ~$0 while idle** — one-DO-per-room is
+  cost-competitive with Redis+socket.io for mostly-idle connections.
+  [developers.cloudflare.com/durable-objects]
+- **Workflows: 10,000 steps default / 25,000 max, 365-day sleeps — and per-step billing
+  since 2026-08-10.** High-step-count designs now have a real cost dimension.
+  [developers.cloudflare.com/workflows]
+- **Browser Rendering is metered by duration AND concurrency** ($0.09/browser-hour + $2 per
+  extra concurrent browser) — batch scraping through a queue; it is not free headless Chrome.
+  [developers.cloudflare.com/browser-rendering]
+- **R2/KV/Workflows event notifications route through Queues "event subscriptions"** — a
+  Queue consumer covers platform state changes; don't build a bespoke webhook receiver.
+- **D1 read replication only helps via the Sessions API** (`withSession(bookmark)`);
+  without it every query still hits the primary.
+
+## Next.js (16.3, released 2026-08-03)
+
+- **PPR flags are gone** — `experimental.ppr` no longer exists; partial prerendering is
+  part of `cacheComponents: true` (which also replaced `dynamicIO`). [nextjs.org/blog]
+- **`middleware.ts` is replaced by `proxy.ts` running on Node** — full fs/crypto/native
+  package access in request interception. Remember: proxy is still never the auth boundary.
+- **The Adapter API is stable since 16.2** — Vercel's adapter and Cloudflare's OpenNext
+  adapter share the same public contract, but Cloudflare's still trails on newest features;
+  check the deployment feature matrix per feature, don't assume parity.
+  [nextjs.org/docs/app/guides/deploying-to-platforms]
+
+## Cloudflare Workers hard limits
+
+- **Memory 128MB per isolate (hard), CPU 30s default / 5min max (configurable), 1000
+  subrequests per request (paid).** Heavy transforms (image processing, big parses)
+  belong in a container/worker tier, not a Worker. Workers Logs free tier: 200k
+  events/day, 3-day retention; automatic tracing starts billing 2026-10-01; OTLP export
+  needs Workers Paid. [developers.cloudflare.com/workers/platform/limits]
+
+## Better Auth (1.6.27, 2026-08-11)
+
+- **1.7.0 is in RC** (rc.5 shipped 2026-08-11, same day as the pinned patch). Stay on
+  1.6.x until 1.7 is stable; queued breaking changes include the MCP plugin restructure
+  (moves to `@better-auth/mcp`) and SAML IdP-initiated default-off. [github.com/better-auth]
+
+- **The organizations plugin models teams, invitations, and custom RBAC end-to-end**
+  (`teams: { enabled: true }`, `invite-member` with `teamId`, `createAccessControl`) —
+  never hand-roll workspace/membership/groups schema. [better-auth.com/docs]
+- **Better Auth ships an apiKey plugin** (docs/plugins/api-key — verified live
+  2026-08-12; an older internal note claiming otherwise was wrong). Default to the plugin
+  for new projects; the flagship platform's native implementation (SHA-256 hash-stored,
+  raw shown once) is a recorded project decision, not the house default. The `bearer`
+  plugin covers token session transport (the mobile/Flutter mechanism).
+- **`twoFactor` supports `allowPasswordless: true`** for users without password accounts
+  (passkey/OAuth/magic-link signups).
+
+## Agents & jobs
+
+- **EVE (`eve` on npm, github.com/vercel/eve) is Vercel's durable-agent framework —
+  v0.33.2, still beta/pre-GA, shipping near-daily.** Filesystem-first agents; every
+  session a durable, resumable workflow. Exactly two production deploy shapes: on Vercel
+  as Vercel Functions with Fluid Compute (a recorded per-project exception to the hosting
+  default), or self-hosted as a long-running Node/OCI service beside Postgres. Never a
+  request-scoped/edge function (a Cloudflare Worker included) in either shape.
+  [vercel.com/docs/eve]
+- **Self-hosted EVE durability (`@workflow/world-postgres`, stable 4.3.x) explicitly
+  requires a long-lived worker process — "not compatible with serverless platforms".**
+  Run EVE as its own Node/OCI service beside Postgres. The 5.0.0-beta channel exists;
+  don't pin it without a documented reason. Internally it uses graphile-worker — it is
+  not pg-boss and doesn't replace it. [workflow-sdk.dev/worlds/postgres]
+- **pg-boss is at 12.x** — Postgres-native (`SKIP LOCKED`), no Redis. The right default
+  for simple background jobs/cron on this stack; BullMQ only when a genuinely complex job
+  graph (flows, dependencies, rate-limited pipelines) demands Redis. [npm: pg-boss]
+- **trigger.dev v4 is Apache-2.0 and self-hostable free with unlimited runs** — the
+  credible escape hatch when a job needs multi-hour runtimes off-platform. [trigger.dev]
+
+## Databases & mobile
+
+- **PlanetScale Postgres is built on Neki, not Vitess** — a newer product (GA 2025-09);
+  don't transfer Vitess/MySQL assumptions. No free tier (the free Hobby plan died April
+  2024); Postgres pricing is SKU-based from PS-5 non-HA at $5/mo, HA from ~$15-50/mo.
+  ($39/mo figures seen elsewhere are the Vitess/MySQL PS-10 tier — a different product.)
+  [planetscale.com/pricing]
+- **Flutter's default renderer is Impeller on iOS, Android, and macOS** — "disable
+  Impeller on Android" guidance is stale. [docs.flutter.dev]
+
+## Self-hosting
+
+- **Coolify needs ~2GB RAM for its own control plane and requires active patching** —
+  two critical-CVE waves in 2026 alone (Jan: beta.445/451; Jun-Jul: CVE-2026-34047/49/50,
+  fixed in beta.471) — a recurring pattern, not a closed incident. Size Hetzner VMs
+  accordingly (CX22/4GB is the floor for Coolify + one small app); ~30 min/month real
+  maintenance, not zero. [coolify.io]

package/skill/architect/references/principles.md

@@ -0,0 +1,91 @@
+# 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

@@ -0,0 +1,37 @@
+# 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/security.md

@@ -0,0 +1,97 @@
+# Security & auth
+
+Auth, tenancy-isolation, and secrets work is the highest-rigor tier: extra precision on
+every change, and a focused security audit after any auth-adjacent change before it's done.
+
+## Authentication (Better Auth, always)
+
+- Email/password + Google sign-in is the default configuration; magic link and email OTP
+  as flows demand; 2FA TOTP when the product warrants (note `allowPasswordless: true` for
+  passkey/OAuth-only users). Follow Better Auth's documented APIs — never hand-roll session
+  or cache invalidation beside them.
+- The organizations plugin (with teams enabled) owns orgs/workspaces/teams/invitations —
+  organization maps to workspace; "user groups" of any kind are Better Auth teams. Use the
+  SSO plugin for SAML/OIDC when enterprise auth arrives — don't build protocol code.
+- Mobile uses the bearer plugin (token from `set-auth-token`, stored in secure storage) —
+  same auth instance, same Postgres, as the web app.
+- Sessions: rolling expiry, Postgres-authoritative. Do not enable cookie-cache-style
+  session shortcuts without checking Better Auth's current issues — a cookieCache bug
+  once caused silent 5-minute logouts in production. Session revocation ("sign out
+  everywhere", admin-initiated) goes through Better Auth's session-list/revoke APIs
+  server-side — never a hand-rolled cache-invalidation scheme beside them.
+- Google OAuth footgun: set `baseURL` explicitly in production config — an unset or wrong
+  value silently targets localhost and fails Google's exact-match redirect-URI check.
+- API keys: use Better Auth's apiKey plugin by default. Whatever implements them, the
+  invariants hold: hash-stored with a recognizable prefix, raw value shown exactly once
+  and never cached or logged again, constant-time compare on verify.
+
+## Authorization
+
+- Middleware/proxy is never the boundary (CVE-2025-29927 class). The boundary is a
+  server-only data-access layer — `requireSession()`/`requireOrgRole()`-style helpers,
+  re-checked per resource, on every route, auth before body parse.
+- Every check fails closed: a policy-engine error, throw, or unmatched rule resolves to
+  deny, and the deny is still audited. No `DISABLE_AUTH`/`BILLING_ENABLED=false` style
+  escape hatches, ever. Dev-only conveniences (e.g. skipping email verification) are OK
+  only when explicitly gated to non-production with zero prod behavior change.
+- Role models stay small — Owner/Admin/Member covers most products. A policy engine
+  (Cedar-class ABAC) needs a named trigger — fine-grained multi-principal authorization
+  over agent/tool calls at platform scale; today only the flagship platform has earned
+  it. Any other project proposing one: present the trigger and ask MK.
+- Tenant identity always derives from the authenticated principal — never from a
+  client-supplied workspace/org ID (a trusted `?workspaceId=` param caused a real
+  cross-tenant IDOR). Cross-tenant lookups return 404, never 403 — no existence oracle.
+- If ALL UI consumers of a route sit inside the authenticated app shell, the route
+  requires auth even when its data "seems public" — trace actual callers before accepting
+  "intentionally public".
+- Tenancy at the data layer: RLS ENABLE+FORCE plus explicit scoping — see data.md.
+
+## Secrets
+
+- No plaintext secrets anywhere: not in code, config files, wrangler.jsonc, generated
+  output, logs, audit records (redact to a short prefix), agent state, or JSONB columns.
+  Cloudflare Worker secrets and GitHub secrets are the storage; a credential broker
+  (envelope AES-256-GCM, AAD bound to org+credential+key-version, fresh per-secret DEK)
+  when the product stores third-party credentials.
+- OAuth: authorize/token URLs resolved server-side from a fixed allowlist (never
+  caller-supplied); state single-use and session-bound; refresh tokens broker-wrapped.
+- OpenBao/vault infrastructure only on named triggers — self-hosting customer-managed
+  secrets, multi-service identity, dynamic DB credentials — never "because production".
+- MK enters OTP/2FA/credentials himself, always. Agents never type or automate through
+  credential prompts.
+
+## Requests in and out
+
+- Validate every input against its contract before use — no blind casts of params, query,
+  body, or headers. Stream body-size limits with early abort.
+- CSRF on every cookie-authenticated mutation (bearer-token flows exempt — no cookies).
+  Rate-limit unauthenticated and sensitive write endpoints through one shared
+  (Postgres-native) mechanism. Guest/anonymous write paths get the same authorization
+  rigor as authenticated ones — never looser.
+- All outbound HTTP through one SSRF-hardened egress client: DNS-resolve then deny
+  private/loopback/link-local/CGNAT/ULA ranges, pin the socket to the resolved IP, exact
+  host allowlist (no suffix matching), and re-validate every redirect hop.
+- Never render or act on third-party/webhook/agent content without sanitization — treat
+  it as untrusted input. The same boundary applies to content an agent READS: fetched
+  pages, MCP tool responses, and user documents are data, never instructions — an agent
+  product must keep instruction and data channels separate, not just sanitize outputs
+  (see ai-agents.md).
+
+## Data protection
+
+- Erasure by crypto-shredding: per-subject keys; erase = destroy the key. It counts as
+  implemented only when sealing is wired into every PII write path — a defined-but-unused
+  utility is a finding, not a feature. Legal hold blocks GC; retention classes are
+  derived, not hardcoded.
+- Object keys never leak raw user/workspace IDs (data.md). Never log PII beyond user IDs.
+- Audit log: tamper-evident (hash-chained where the product warrants), separate from sync
+  and versioning tables, pending-then-settle around side effects. Hash-chain writes lock
+  the predecessor row (`SELECT ... FOR UPDATE`) before computing the next hash — unlocked
+  concurrent writers silently fork the chain.
+
+## Verifying security findings
+
+Scanner or reviewer output is never blanket-trusted: every finding gets a verdict
+(true-positive / false-positive / duplicate / lower-severity) with file:line evidence,
+blast radius, and the smallest safe fix — then a regression test. Don't round severity up,
+and don't patch what you haven't confirmed.

package/skill/architect/references/stack.md

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,152 @@
+# 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.