@vegastack/skills 0.9.1 → 0.11.0

package/skill/dev-architect/references/mobile.md

@@ -0,0 +1,75 @@
+# 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
+(register-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 —
+dev.md's Architecture `mobile:` line 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. Rules from the shipped VegaStack app are stated plainly; rules
+from official-docs research MK has not ratified are tagged "(inferred)" — confirm 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.
+- Layer-first structure: `lib/{data, domain, ui, routing, config}`, feature folders inside
+  `ui/`, shared widgets in `ui/core/`. (Blog "feature-first is the standard" claims don't
+  survive verification — the official reference app is layer-first; feature-first is a
+  valid escalation at scale.) Class names mirror roles: `HomeViewModel`, `UserRepository`.
+
+## State management — lean by default
+
+- Plain `ChangeNotifier`/`ValueNotifier` ViewModels with hand-wired constructor injection
+  in `main.dart` — zero extra dependencies, zero codegen; matches official guidance and
+  what VegaStack has 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 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). That versioned
+  `/api/v1` contract outlives web deploy cycles: app-store install lag keeps old clients
+  alive, so a shipped mobile app counts as real users even while the web side iterates
+  freely — the one exception to pre-launch delete-not-migrate and to dead-endpoint
+  deletion.
+- 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 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 for genuine offline/relational needs — never
+  speculatively.
+
+## Design system on mobile
+
+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`; adopt `go_router` when deep
+  links/route state demand it, not by reflex (inferred).
+- Models: hand-written by default (what the shipped app does); freezed +
+  json_serializable only when codegen demonstrably earns its build cost (inferred).
+- 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).
+- 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; confirm before wiring).
+
+Undecided (ask MK rather than assume): push-notification provider, offline/sync
+expectations per product, store-release cadence.

package/skill/{architect → dev-architect}/references/pinned-facts.md

@@ -1,7 +1,8 @@
 # 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
+get wrong from stale training data. This file is the verified cache behind SKILL.md's
+verify-before-you-recommend protocol, and 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.
 
@@ -38,7 +39,12 @@ All facts below verified 2026-08-12.
 - **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.
+  package access in request interception.
+- **`proxy.ts`/Node middleware does NOT work on OpenNext Cloudflare as of 2026-08** (open
+  issues opennextjs-cloudflare#962/#1277, workers-sdk#13755/#13937) — don't design a
+  Cloudflare-hosted feature around `proxy.ts`; re-check the trackers before assuming it
+  shipped. Turbopack is supported since adapter v1.15.0 (the old breakage is fixed;
+  re-verify only on older pins).
 - **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.
@@ -57,15 +63,14 @@ All facts below verified 2026-08-12.
 - **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]
+  (`teams: { enabled: true }`, `invite-member` with `teamId`, `createAccessControl`).
+  [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).
+  for new projects; the flagship platform's native implementation 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).
 
@@ -73,16 +78,12 @@ All facts below verified 2026-08-12.
 
 - **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]
+  session a durable, resumable workflow. [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]
+  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]

package/skill/dev-architect/references/principles.md

@@ -0,0 +1,117 @@
+# Principles — how VegaStack decides, reviews, and talks
+
+Distilled from seven months of MK's 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 strips out; on a 3-4 person team every moving part is real maintenance,
+and the lean version is usually also the faster, more reliable one. Lean-first governs the
+*count of moving parts*, not the rigor inside each — money, auth, tenancy, audit, and
+secrets always get 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". 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. 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. **Why:**
+carrying compatibility for users who don't exist is pure bloat. One exception: a versioned
+API contract consumed by a shipped mobile app counts as 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. Promote a
+util to `/lib` the moment a second feature uses it. **Why:** two sources of the same truth
+always drift — the reference-architecture mistake MK explicitly engineers against.
+
+## 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, server/client 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;
+executing workflows inside Next.js handlers is the anti-pattern MK cites most.
+
+## Effort scales with stakes, not habit
+
+Security, auth, tenancy, money, and foundations get generous, adversarial treatment.
+Routine features on a small team get medium thoroughness — a cheap reconnaissance pass
+before full-cost work, and no governance ceremony a 3-4 person team won't exercise.
+**Why:** MK's own latest 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 the safer-sounding guess (SKILL.md's verify
+  protocol). MK refused an unverified "Better Auth forces text UUID columns" claim — false.
+- Present decisions as 2-3 options with a clear recommendation and the tradeoff that
+  matters; record the choice as one dated register line — the reader learns the reasoning.
+- MK reverses when: a verified assumption proves false · cleverness regresses UX · a
+  heavyweight mandate meets a simple project · his own tooling over-complicates. He
+  reverses toward less machinery on low stakes, toward more rigor only on a concrete bug
+  or vulnerability. 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 · money/PII or not. These live in dev.md's `## Architecture`
+section. When two recorded decisions conflict or the facts can't answer, ask MK with a
+recommendation instead of assuming.
+
+## Review discipline (design reviews, audits)
+
+- Adversarial by default: assume the work is wrong until disproven — findings or verified
+  absence of findings, never praise. Evidence or it doesn't exist: every finding cites
+  file:line actually read, quoted verbatim; detection is never a claim of absence.
+- Verify every candidate finding before reporting: verdict true-positive / false-positive
+  / duplicate / lower-severity, with disproving evidence for the false positives.
+- Severity, three tiers with required actions: **critical** — exploitable or data-losing;
+  blocks ship, MK signs off on the fix. **production-gate** — fixed before the surface
+  serves real users; fine behind pre-launch. **consider** — advisory; log and move on.
+  Never round up; judge severity against the project's Architecture facts — never surface
+  platform-scale concerns as defects on a simple project.
+- Cheap deterministic checks belong in every review: dead exports, unpaginated lists,
+  `SELECT *` at API boundaries, missing tenant/FK indexes, fresh-clone buildability.
+- Coverage without bias: evaluate the review's scope, not just what changed or what you
+  built. End honestly: open questions, not-verified items, accepted risks named as such.
+
+## Advise, never gate
+
+You recommend; MK and the team decide. A departure from a recommendation becomes one dated
+accepted-risk line proposed for the register, reported honestly in later reviews — never
+silenced, never blocked on, never re-litigated.
+
+## Voice — a team briefing, not a compliance report
+
+Plain language, short sentences, terms defined on first use. Recommendation first, then
+the one risk that matters, then detail in bullets and tables. Plain markdown, no JSON
+blocks. No em dashes, emojis, or hashtags in copy MK will publish.
+
+## Client engagements (`kind: client`)
+
+Same stack defaults, gates, and honesty — a client never gets a looser standard. Scope
+inversion is named the moment it's seen (SOW drift surfaces with options, never silently
+absorbed); client-driven stack overrides are dated register lines with MK's sign-off; the
+register plus the issue briefs are the handover record.

package/skill/{architect → dev-architect}/references/security.md

@@ -6,22 +6,22 @@ every change, and a focused security audit after any auth-adjacent change before
 ## 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.
+  as flows demand; 2FA TOTP when the product warrants (`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 (teams enabled) owns orgs/workspaces/teams/invitations —
+  organization maps to workspace (`modelName: "workspace"` pattern); "user groups" of any
+  kind are Better Auth teams; never a hand-rolled workspace/membership/groups schema. The
+  SSO plugin covers 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.
+- Sessions: rolling expiry, Postgres-authoritative. Don't enable cookie-cache-style
+  shortcuts without checking Better Auth's current issues — a cookieCache bug once caused
+  silent 5-minute logouts in production. Revocation ("sign out everywhere",
+  admin-initiated) goes through Better Auth's session-list/revoke APIs server-side.
 - 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
+- API keys: 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.
 
@@ -31,25 +31,27 @@ every change, and a focused security audit after any auth-adjacent change before
   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.
+  deny, and the deny is still audited. No `DISABLE_AUTH`-style escape hatches, ever;
+  dev-only conveniences 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.
+  (Cedar-class ABAC) needs a named trigger — fine-grained multi-principal authorization at
+  platform scale; today only the flagship platform has earned it. Anyone else 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.
+  cross-tenant IDOR; reject on mismatch). 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.
+  "intentionally public". Guest/anonymous write paths get the same rigor as authenticated
+  ones — never looser.
+- Tenancy at the data layer: RLS ENABLE+FORCE plus explicit scoping — 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.
+- No plaintext secrets anywhere: not in code, config, 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.
@@ -60,29 +62,22 @@ every change, and a focused security audit after any auth-adjacent change before
 - MK enters OTP/2FA/credentials himself, always. Agents never type or automate through
   credential prompts.
 
-## Requests in and out
+## Requests out and untrusted content
 
-- 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).
+  host allowlist (no suffix matching), re-validate every redirect hop.
+- Body-size limits stream: count bytes as they arrive and abort at the limit — never
+  buffer the whole body first.
+- Third-party/webhook/agent content is untrusted input — sanitize before rendering or
+  acting on it. The instruction/data separation agent products must keep: 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.
+- Erasure by crypto-shredding: per-subject keys; erase = destroy the key. 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 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
@@ -91,7 +86,5 @@ every change, and a focused security audit after any auth-adjacent change before
 
 ## 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.
+Scanner/reviewer output follows the review discipline in principles.md — verdict per
+finding, no rounding up. Additionally: every confirmed finding gets a regression test.

package/skill/dev-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 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; dev.md records which. Commit text lockfiles (`bun.lock`, not `bun.lockb`) |
+| Auth | Better Auth, always — default flows, plugins, and the org→workspace mapping: security.md | Hand-rolled auth, custom user-groups schema, Auth0/Clerk | Owner-stated standing rule; 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), behind Hyperdrive on Workers. D1-only is a recorded exception for the minimal Cloudflare-native product class (locked 2026-05-20) — check dev.md's `## Architecture` before assuming Postgres | Neon (never), D1 as a secondary store beside Postgres, MySQL | "We don't use neon at all." One datastore per product. 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 — discipline in data.md | 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. Keep the S3 protocol boundary so any S3 provider or MinIO works for licensed self-hosted deployments |
+| Cache / Redis | None by default. Rate limiting and caching Postgres-native; Workers KV only with a named trigger (e.g. read-mostly config cache at volumes where a Postgres round-trip measurably hurts — 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 (data.md) |
+| Jobs / cron | pg-boss on the existing Postgres, dispatcher-only — lease/heartbeat/retry state of authority in our own tables. Cron parsing/description: `croner` (DST/IANA-aware) + `cronstrue` | 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; a cron-parser swap was made and corrected once already |
+| Agent execution | EVE (Vercel's `eve`) — deploy shapes and constraints: ai-agents.md | EVE inside an OpenNext Worker or any request-scoped/edge function | EVE's Postgres world requires a long-lived worker process; EVE owns agent sessions, pg-boss owns generic jobs — never conflated |
+| AI calls | AI SDK 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, a per-document `PageSync` for edits) — 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 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) — recorded in dev.md's Architecture | Vercel as a default (per-project recorded exception only); 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); bounces/complaints via the SNS-webhook pattern into a suppression list | Per-vendor SDK sprawl, sending to suppressed addresses | Cheap, boring, proven in-house; unhandled bounces poison sender reputation |
+| Payments | Stripe — money-path mechanics: web.md | Building billing logic inside request handlers | Money paths get the full rigor tier |
+| 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 — detail: web.md | Route-local validation, raw `request.json()`, unbounded lists | One contract feeds web, Flutter, MCP, and public consumers |
+
+## 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/dev-architect/references/web.md

@@ -0,0 +1,102 @@
+# Web — frontend, backend/API taste
+
+## Project layout
+
+- Top-level `server/` (or `packages/*` server code) holds DB, services, integrations —
+  never imported from client code, enforced with `server-only` + a boundary check, not
+  convention. App router in `src/app/`; features as self-contained modules under
+  `src/features/<domain>/`; 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 (rejected for multi-tenant SaaS on
+  governance grounds; a confirmed single-tenant/offline product is the only exception —
+  ask, don't assume).
+- Next config: `output: 'standalone'`, `cacheComponents: true` (PPR flags no longer
+  exist — pinned-facts). Query key factories 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. Internal navigation uses `next/link`.
+- Request interception on OpenNext/Cloudflare: check pinned-facts before designing around
+  `proxy.ts` — and interception is never the auth boundary (security.md).
+- Dependencies: prefer the native/browser API when it covers the need
+  (`Intl.RelativeTimeFormat` over date-fns); self-implement simple behavior 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 — MK rejects "library because library".
+
+## Design system
+
+`vegastack-design-system` owns component choice, tokens, and the do/don't rules;
+first-time wiring is `vegastack-consume`. Consume-don't-extend is a red line (SKILL.md).
+One unresolved item recorded here: touch-target minimum (24px WCAG AA vs 44px mobile-HIG
+both appear in the record) — ask MK when it matters.
+
+## UI completeness bar (every real surface, before it's "done")
+
+- Full state matrix: loading skeleton shaped like the real content, empty state with
+  guidance, errors routed to the specific failure (never swallowed into `{}`), success
+  feedback, optimistic updates where a mutation changes visible state.
+- Perceived speed is the named "instant shell" pattern: the layout shell renders
+  immediately (RSC + `cacheComponents`), every data region streams in behind a
+  content-shaped skeleton — never a blank page or full-page spinner.
+- Systemic fixes: a defect found in one component (scroll leaking through an overlay,
+  wrong token) is fixed across the whole family in one sweep, with evidence.
+- Long lists (>~50 rows) virtualize with `@tanstack/react-virtual` (approved — still state
+  the justification when adding it).
+- Cloning/rebranding a reference site: strip every trace of the source's provenance (class
+  names, asset domains, meta) 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).
+**Why:** MK has demanded "100% SEO" on shipped sites twice — a completeness bar, not an
+enhancement.
+
+## Testing — stack-specific taste (whether tests are required: dev.md's `tests:` knob)
+
+- Component/a11y tests run in Vitest browser mode with the Playwright provider — 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, behind an env flag (`RUN_DB_TESTS=1`); E2E doubles
+  implement real ports, never a parallel mock pathway.
+- VRT/demo content is deterministic (no `Date.now()`/`Math.random()`). "100%" means audit
+  completeness, never a coverage metric.
+
+## 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()`; responses sanitized (secrets and credential
+  references never leave the server). Enforced with a CI ratchet, not review.
+- Return what the view renders — no mega-responses; select columns explicitly.
+- Webhooks over polling; the database is the source of truth. Once provider state lands in
+  Postgres via webhook, don't re-poll — and no 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 in the same transaction as the business change. Pricing math is deterministic
+  code with server-enforced invariants — AI drafts and judges; deterministic code
+  calculates and enforces.
+- Centralize the boring: one ID helper, 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.
+- Dead endpoints get deleted, not deprecated-and-kept (exception: a versioned `/api/v1`
+  contract consumed by a shipped mobile app — mobile.md).
+- Outbound webhooks to customers: defined event catalog, Standard Webhooks-style signing
+  with rotatable secrets, delivery via transactional outbox → queue with retries/backoff,
+  auto-disable after N consecutive failures, a replay surface — never fired inline from
+  request handlers.
+- Platform-native mentions over plain text: resolve and mention the real entity (Slack
+  @mentions, Notion Person fields) instead of rendering names as text.
+- Wizard/checkout flow-state persistence (client store vs server-side draft) is not a
+  settled house rule — ask MK when building one.

package/skill/{architect → dev-architect}/refresh/REFRESH.md

@@ -1,8 +1,9 @@
-# Freshness contract — architect
+# Freshness contract — dev-architect
 
 Most of this skill is durable taste and recorded decisions; it does not go stale on its
-own. Exactly one file decays with the platform landscape: `references/pinned-facts.md`
-(plus the version claims embedded in `references/stack.md` and `references/mobile.md`).
+own. The decaying surface is `references/pinned-facts.md` — the verified cache behind
+SKILL.md's verify-before-you-recommend protocol — plus the version claims embedded in
+`references/mobile.md` and the fact-adjacent lines the registry's `affected` lists name.
 
 ## Mechanism
 
@@ -11,9 +12,10 @@ own. Exactly one file decays with the platform landscape: `references/pinned-fac
    evidence for anything that changed (fact text, version, date, source). The diffing
    judgment lives in the agent run, not in maintained scripts. The PR is human-reviewed —
    never auto-merged.
-2. **Refresh-on-use (safety net, written into SKILL.md).** When a recommendation leans on
-   a pinned fact older than 60 days, the consuming agent re-verifies that one fact first
-   and says so. Never bulk-refresh in-session.
+2. **Refresh-on-use (safety net, written into SKILL.md).** The verify protocol: a
+   recommendation leaning on a pinned fact older than 60 days re-verifies that one fact
+   first and says so; an uncached decision-bearing claim is verified against live docs
+   before it is recommended. Never bulk-refresh in-session.
 3. **Registry baseline (`sources.json`).** The repo-shared refresh runner
    (`tooling/refresh/refresh-evidence.mjs`) keeps checksum baselines for the critical
    source pages so CI can detect upstream drift deterministically between weekly runs.

package/skill/{architect → dev-architect}/refresh/sources.json

@@ -8,7 +8,7 @@
     ],
     "defaultChecksumScope": "html-text-v1",
     "offline": "Use cached metadata only; fail closed when a critical entry is missing or older than thresholdDays.",
-    "drift": "Any drift requires reading the changed page and a human-reviewed PR updating references/pinned-facts.md (and version claims in references/stack.md / references/mobile.md); never auto-apply.",
+    "drift": "Any drift requires reading the changed page and a human-reviewed PR updating references/pinned-facts.md plus every other file the source's affected list names; never auto-apply.",
     "copyright": "Store claim metadata, URLs, hashes, and concise excerpts only; never archive third-party documentation corpora.",
     "cadence": "weekly scheduled-agent refresh; thresholdDays must be >= 14 (2x cadence) so a single missed run never breaches a threshold"
   },
@@ -31,7 +31,6 @@
       ],
       "affected": [
         "references/pinned-facts.md",
-        "references/stack.md",
         "references/data.md"
       ],
       "checksum": "fda2870b95deffce48dca7f3df3707325b1bc4a2d58a17708ee9220bfba5eba1",
@@ -102,8 +101,7 @@
       ],
       "affected": [
         "references/pinned-facts.md",
-        "references/security.md",
-        "references/stack.md"
+        "references/security.md"
       ],
       "currentVersion": "1.6.27",
       "versionCheckedAt": "2026-08-12T14:33:11.062Z",
@@ -129,8 +127,7 @@
       ],
       "affected": [
         "references/pinned-facts.md",
-        "references/ai-agents.md",
-        "references/stack.md"
+        "references/ai-agents.md"
       ],
       "currentVersion": "0.33.2",
       "versionCheckedAt": "2026-08-12T14:33:11.062Z",
@@ -182,8 +179,7 @@
       ],
       "affected": [
         "references/pinned-facts.md",
-        "references/web.md",
-        "references/stack.md"
+        "references/web.md"
       ],
       "currentVersion": "16.3.0",
       "versionCheckedAt": "2026-08-12T14:33:11.062Z",
@@ -208,8 +204,7 @@
         "jobs"
       ],
       "affected": [
-        "references/pinned-facts.md",
-        "references/ai-agents.md"
+        "references/pinned-facts.md"
       ],
       "currentVersion": "12.27.0",
       "versionCheckedAt": "2026-08-12T14:33:11.062Z",