@vegastack/skills 0.4.0 → 0.6.0

package/skill/architect/references/infra.md

@@ -0,0 +1,128 @@
+# Infra — hosting, CI/CD, observability
+
+## Hosting targets
+
+Two sanctioned targets, recorded per project in `.vegastack/arch.md`:
+
+- **Cloudflare Workers via OpenNext** — the default for public web products. Once a project
+  commits to Cloudflare, never stand up a parallel Vercel deploy path (deploy paths drift).
+  Shared packages must still *work* on Vercel for downstream consumers — that's portability,
+  not a deploy target.
+- **Self-managed servers** (Hetzner-class, Docker; Coolify for push-to-deploy) — when
+  self-hosting is a product requirement, the workload needs long-lived processes (EVE, heavy
+  workers), or platform independence justifies ~30 min/month of real ops.
+- Vercel only by explicit, recorded per-project exception (e.g. EVE-hosted workloads).
+  Internal/admin apps that need no edge features may run plain `next start` in Docker —
+  OpenNext is the default, not a ritual.
+
+## Cloudflare discipline
+
+- Provision only what the current phase uses. Queues, KV, Durable Objects, Workflows are
+  all trigger-gated: DO when live collaboration/presence actually ships (hibernating
+  WebSockets make it cheap then — see pinned-facts); Queues when webhook/event volume is
+  real; never scaffolded ahead of need. Delete stale Workers, Hyperdrive configs, and
+  buckets — with an explicit create/delete accounting before touching anything, and
+  `wrangler` used carefully.
+- Multi-env via the Workers environments feature (`env.*`) — never separate top-level
+  Workers per environment. One Hyperdrive per environment, shared by every service hitting
+  the same database.
+- Naming: hyphen-only across all Cloudflare resources; purge inconsistent legacy names.
+- Domains: production on the `vegastack.com` apex/subdomains; non-prod environments under
+  `*.vegastack.dev`. Every Worker sets `workers_dev: false` + `custom_domain: true` — the
+  default `*.workers.dev` origin bypasses Cloudflare Access, so leaving it on exposes a
+  gated Worker unauthenticated (this is security, not cosmetics). Preview environments are
+  access-protected by default; only production is public.
+- Environments are `dev` / `preview` / `production` via the Workers `env.*` feature; the
+  `staging` git branch deploys to the `preview` environment — there is no fourth Worker
+  environment unless a project records one. Secrets are set per environment
+  (`wrangler secret put X --env production`). Local env files: `.env` feeds `next dev`,
+  `.dev.vars` feeds `wrangler dev`/Miniflare — both gitignored, both with committed
+  `.example` companions.
+- No Cloudflare Images — optimize with `sharp` at build/upload time and serve from R2 (the
+  paid add-on solves a problem `sharp` + free egress already solve).
+- Runtime constraints are architectural facts: no TCP clients, per-request DB connections
+  (data.md), and OpenNext trails vanilla Next.js — check OpenNext docs per feature instead
+  of assuming. Two dated specifics: Turbopack is supported since adapter v1.15.0 (the old
+  breakage is fixed; re-verify only on older pins); `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.
+- Edge/CDN caching never bypasses live authorization — revoked, expired, or
+  password-protected content is re-checked even when the artifact is cached.
+- Cloudflare Tunnel is the default for exposing self-hosted services and remote dev
+  previews (already paid for via the Workers plan). Cloudflare Access gates paths by data
+  sensitivity with email allowlists — not one site-wide gate.
+
+## Self-managed discipline
+
+- Containers hardened: non-root user, `cap_drop: [ALL]`, `read_only: true` where runtime
+  paths allow; healthchecks on every service. Migrations and storage provisioning run in
+  the app container's own entrypoint under a Postgres advisory lock (safe when replicas
+  race on boot) — not a separate bootstrap deployable, unless a project records a concrete
+  reason for one (the shipped self-host pattern deliberately avoids an extra init
+  container).
+- Ship `docker compose up` as the self-host story: bundle only Postgres + MinIO-class
+  essentials; everything else (vector store, gateway, vault) is connect-your-own.
+- Server sizing: SSD, compute, and RAM over disk capacity, optimized for ROI within the
+  budget MK states for that server (ask if none was stated — don't guess one); Coolify
+  itself needs ~2GB RAM and real patching (pinned-facts). Cloud infra beyond Cloudflare
+  goes through Terraform, IAM scoped narrowly per purpose and region.
+- Any infra cleanup (disks, stale resources, runners) needs explicit authorization first,
+  scoped to verified-stale items — never blanket cleanup.
+
+## CI/CD
+
+- Never commit, tag, push, merge, publish, deploy, or create paid/cloud resources without
+  MK's explicit go-ahead for that step — this holds even in fully autonomous runs (it is
+  the red line, stated identically in SKILL.md).
+- Build passes before any commit. When committing: review the complete uncommitted diff
+  (not just this session's), draft a conventional-commit message covering all of it, wait
+  for approval.
+- Package manager is locked per project — read it from the repo, pin the exact version
+  (corepack/bun), never silently substitute.
+- Branch protection on main/staging/develop (no force-push), branch-naming enforced
+  server-side and in a pre-push hook. DB migrations apply via CI only (data.md).
+- CI is cost-managed, not maximal: path-condition expensive jobs (VRT, contract tests) so
+  docs/skills-only changes skip them; push heavy verification into local pre-commit/pre-push
+  hooks and self-hosted runners; hosted Actions minutes are a tracked budget. Verification
+  is local-first — CI verifies that it happened, via a committed receipt (a signed
+  `.gates/receipt.json` bound to the git tree hash) rather than re-executing browser
+  suites. A receipt is attestation, not proof — skipping a gate becomes visible, not
+  impossible.
+- Wire every architectural guard script (import boundaries, runtime gravity, route-wrapper
+  ratchet) into the one composed check command — a separate script someone forgets to run
+  doesn't exist.
+- Green CI is necessary, never sufficient: a unit is done after a real
+  boot → auth → reach → mutate → verify pass against live infra. On CI failure:
+  diagnose and report the root cause first; fix second.
+- Releases via Changesets + GitHub Actions. MK enters npm OTP/2FA and other credentials
+  himself — never the agent. Node 24 standard; deprecated Actions versions are routine
+  housekeeping, fixed proactively.
+
+## Observability (small-team baseline)
+
+- Structured JSON logs (pino) to stdout with OTel-shaped fields (trace/request/org context
+  auto-injected) — OTel-compatible by convention now, full OTel SDK/collector only when
+  cross-service trace correlation becomes a real pain, not before.
+- The append-only Postgres event log is the authoritative telemetry source; metrics/log
+  tables are derived and disposable (30-day raw, 13-month rollups, compress after ~7 days;
+  TimescaleDB opportunistic with partition+BRIN fallback).
+- On Cloudflare, use the built-in free tier first: Workers Logs (200k/day, 3-day
+  retention) and the analytics dashboard cost nothing; note Workers tracing starts billing
+  2026-10-01, and OTLP export needs Workers Paid.
+- Alerting honest to team size: an uptime monitor (Uptime Kuma-class) + a cron that checks
+  error-rate thresholds in the event table and posts to Slack, plus a dead-man's-switch
+  ping for silent job failures. No paging/SLO/on-call ceremony — that practice is
+  deliberately undefined until the team needs it; propose per project, don't invent doctrine.
+
+## Incidents
+
+- Active production incident: diagnose first (root cause with evidence), fix second — the
+  standing diagnose-before-fix rule applies under pressure too. Rolling back a deploy IS a
+  deploy: it still needs MK's go-ahead — reach him with the evidence and the recommended
+  rollback rather than acting; mitigation that doesn't deploy (feature-level disable via
+  config, traffic block) can proceed and be reported.
+- Every real incident gets a short postmortem in the project's `docs/postmortems/`
+  (established precedent): what happened, root cause, the guard that now prevents it.
+  Codify the recurring correction (advisory.md) — an incident that doesn't change a rule
+  or a check will repeat.

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.