@vegastack/vegafactory 0.19.0

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

@@ -0,0 +1,113 @@
+# Workflow conventions
+
+Artifact authority.
+
+Defaults resolve repo, group, then org; locks require explicit org delegation. Repository dispatch/commands never inherit; registers concatenate. Policy/migration uses dev-setup's `scripts/effective-policy.mjs` and vegafactory-setup's control-room reference.
+
+## Comment metadata markers
+
+Comments open:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan\|consolidated\|none>` and schema-v2 JSON | one per approval event |
+| `questions` | `rev` | one per ask round; earlier rounds stay as record (dev-setup's `references/ask-route.md`) |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and `(v<n>)` start at 1 only on brief, plan, questions and evidence; other types have neither. Locate by marker, never heading/legacy fallback.
+
+## Operator identity
+
+Use parenthesized GitHub usernames:
+
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
+
+Approval.mjs’s publisher/relay contract lets current-policy provider-envelope publishers attest listed operators’ session words. Other recorders may only relay independently read identical operator-published scoped grants within complete authority history, without lifecycle mutations. Relays inherit source authority/lifecycle; account attestation cannot authenticate off-platform speech.
+
+## Scoped approval records
+
+Use only dev-implement’s `scripts/lib/approval.mjs` and follow its contract. Refresh current policy and complete GitHub histories. `ArtifactRef={repo,issue,kind,artifactId,rev,digest}` binds brief issue-node or unique plan/protocol comment-node identity, revision and canonical SHA-256.
+
+Post exactly one approval comment: matching scope marker, then one fenced JSON `ApprovalRecord={schemaVersion:2,id,operator,scope,source:{kind,ref,quote},artifacts,supersedes,revokes}`. Exclude outer Markdown fences, future alternatives and unresolved source locators; validate the whole body with approval.mjs's `parseApproval`. Source kind is `session` or `github-comment`, with inspectable words. Reuse valid current grants/relays; avoid counterfactual plan-only or redundant approvals. Scope is `brief`, `plan` or `brief+plan`; planning requires brief, implementation both, research execution also its protocol. Empty-artifact revocations remove exact earlier IDs. Conflicts explicitly supersede; newest never wins.
+
+Preserve legacy comments. Without writes, inventory refusals/current digests and request reconfirmation. For duplicate canonical plans preserve both identities/bodies and request record-preserving reconciliation; never delete to clear ambiguity. Follow approval.mjs’s exact correction schema, operator-publisher and target checks. Only malformed or demonstrably invalid-source targets qualify, never valid authority or unavailable/inconsistent facts. Resolve source facts first; corrections grant no scope. Exact child checkpoint actions bind one selected code child's branch/ref/base/tasks/files; other actions never substitute.
+
+Consolidated parent events bind frozen manifests, canonical artifacts and exact task/action subsets. Use inline UTF-8 or immutable repository/commit/path plus blob hash, never local paths. Canonical `approvalBindings` authorize; requested `recordBinding` only audits. Follow approval.mjs’s preparation/research/recovery provenance, receipts, adapters, counted attempts and fresh admission; retain immutable history and unverified legacy records. Keep checkpoint/private/live/shipping gates separate.
+
+Canonicalization normalizes CRLF; its only exceptions are structural plan checkboxes and one validated JSON `{tasks:[{id,evidenceUrls}]}` block between `<!-- vsk:progress:start -->` / `<!-- vsk:progress:end -->`. IDs must exist; URLs are HTTP(S); unknown fields/duplicates refuse. Stable task IDs/order, interfaces, actions, revisions and all other bytes remain scope. Brief/protocol bodies have no mutable fields; fenced examples stay immutable and grant no authority.
+
+## Revision markers
+
+Scope edits increment marker/heading revisions and append `Revisions: v2 — DD-MM-YYYY: <change>, per (<username>) correction`; preserve earlier lines and obtain fresh approval. Validated progress changes need neither.
+
+## Scope classes
+
+Intake explains scope; operator overrides:
+
+- **`research`** — inquiry; throwaway code allowed, never merged. No branch/PR/changelog; evidence comment contains findings and recommendation.
+- **`quick-build`** — existing flow: draft brief+plan together, approve both, then `ready`.
+- **`full-plan`** — new ground: approve brief, `needs-plan`, separate grounded planning session, `needs-operator`, approve plan, `ready`. Split multiple deliverables into independently classified epic children.
+
+Scope ratchet: `dev-plan`.
+
+## Labels
+
+One state; flips set assignees (colors: dev-setup):
+
+| label | meaning | assignee |
+|---|---|---|
+| `needs-operator` | question, brief or plan approval, proposal | the operator |
+| `needs-plan` | brief approved; awaiting planning (full-plan only) | the operator |
+| `ready` | approved — an agent may start | nobody |
+| `working` | claimed; ledger shows live progress | the runner |
+| `for-operator` | done — evidence posted, awaiting operator review | the operator |
+
+Modifiers coexist with state: `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents without a native Epic type). Boards mirror states one-way.
+
+## Titles, types, hierarchy
+
+- **Title prefixes:** issues, branches and PRs use dev.md's `branch:` types plus `research:`; PR title = issue title.
+- **Native issue types/fields:** Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (else label); intake sets Priority/Effort. Scope classes stay labels.
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far · Not clear yet · Out of scope), with native child sub-issues. Issues are work units (brief, approvals, branch, PR, evidence); tasks are checkboxes **only in the plan comment**. Blockers use dependencies; phases use milestones. Only non-epic issues get `ready`.
+
+## The ledger
+
+One implementation ledger:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- <issue>-T<N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- <issue>-T<N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- <issue>-T<N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+
+**Resume protocol:** brief → plan comment → ledger → `git log`; then reconcile task IDs, canonical approval history, edited authority, source/evidence, ownership and delivery effects. Preserve completed work/provenance; stale heartbeat is not stop proof. Preparation never implies issue completion. Dev-implement's ledger reference owns recovery detail.
+
+## `.vegastack/` workspaces
+
+Drafts/reports: `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue: `intake-<slug>`), self-ignored by a `.gitignore` containing `*`. Branch checkouts: root-ignored `.vegastack/.worktrees/<issue-number>-<title-slug>/`; main stays on its default branch. Keep both outside `.git/`. Subagents save full reports and return short status. `<path-to-this-skill>` means SKILL.md’s directory.
+
+## Verification gate
+
+Prove claims with fresh command output and exit codes; report failures and skips. Delegate only substantial independent parallel work, never your own verification; keep spawn counts low. Guards block machine-verifiable failures (exit 2); heuristics warn. Guards contain no AI inference; unverifiable state fails closed.
+
+## Review bindings
+
+One fenced JSON each: `{"reviewBinding":{sha,baseSha,scopeDigest,verdict,findings:[{id,status}]}}` in review; `{"adjudication":{sha,reviewCommentId,operator,source:{kind,ref,quote},findings:[{id,disposition,reason}]}}` in evidence. Use full commit IDs and canonical-plan scopeDigest; status=open/resolved; disposition=accept-risk. Every open finding requires same-review operator acceptance. dev-ship’s README defines source checks. No prose exceptions.
+
+Communicate starts/findings/direction plainly; self-contained outcomes include paths and remaining checks. Avoid invented labels/arrows; visualize usefully. Challenge ambiguity with options; never guess silently.

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

@@ -0,0 +1,89 @@
+# Data — Postgres, tenancy, storage, caching
+
+## Database
+
+- PostgreSQL, always managed by us (a PlanetScale Postgres server or self-hosted
+  Hetzner-class) — never Neon. Behind Hyperdrive, target the highest Postgres major
+  Hyperdrive supports (pinned-facts — PG 18 is a known trap). Drizzle ORM with the single
+  `postgres-js` driver — never mix in `pg`. Stay on GA/stable majors of core DB deps;
+  verify vendor version-support claims per SKILL.md's verify protocol before locking a
+  decision.
+- From Workers: Hyperdrive binding + per-request client (`prepare: false, max: 1`,
+  request-scoped via the execution context) — a module-level pool in a Worker or Durable
+  Object is a bug, not a style choice (workerd forbids cross-request I/O). One Hyperdrive
+  per environment shared across services hitting the same database — never one per
+  service. On long-running Node services (Docker), pool normally.
+- Migrations run via CI only, never pushed from a dev machine — with one loud exception:
+  pre-launch databases with zero real users get clean resets instead of migration chains
+  (principles.md). Runners apply in journal order, idempotent on re-run. Iterate schema
+  with `db:push` during development; run `db:generate` exactly once right before shipping
+  — repeated generates mid-iteration create conflicting DDL.
+
+## Multi-tenancy
+
+- Shared schema with RLS, not database-per-tenant: every tenant-scoped table (and every
+  partition) gets `ENABLE` + `FORCE` ROW LEVEL SECURITY, driven by exactly one fail-closed
+  GUC accessor (`NULLIF(current_setting('app.current_org_id', true), '')::uuid`), defined
+  in one idempotent migration location.
+- RLS is one layer, never the only layer: every query also scopes explicitly by
+  `org_id`/`workspace_id` in the data-access layer. Two roles — the app role has no
+  `BYPASSRLS`; a separate system role does. `withOrgContext`/`withSystemContext` (or
+  equivalent) are the only query entry points; the raw client is never exported. **Why:**
+  RLS misses TimescaleDB chunks and misconfigurations fail open; two independent layers
+  fail closed.
+- Tenant identity comes from the authenticated principal, never client-supplied fields —
+  the IDOR precedent and rule live in security.md.
+- Better Auth's organization plugin owns the workspace/member/invitation schema
+  (security.md); its columns stay snake_case as generated, with native `uuid` columns —
+  Better Auth does not force text IDs.
+
+## Caching
+
+- No cache layer by default: rate limiting, dedupe, and most "cache" needs are
+  Postgres-native. Workers KV only with a named trigger; any Redis-class store is
+  optional and **never correctness-bearing**.
+- Never let auth, role, or permission data live in a cache long enough to serve stale
+  permissions — a revoked member seeing tenant data is a security bug, not a staleness
+  bug. Anything cached has a defined cache-outage story (fall back to DB, never
+  stale-forever).
+
+## Search, knowledge, files
+
+- Search and embeddings live in Postgres itself: `STORED` generated `tsvector` + GIN for
+  full-text; pgvector (`halfvec` + HNSW, `hnsw.iterative_scan = relaxed_order`) for
+  embeddings; hybrid fusion via RRF (k=60 starting constant). Embedding default: BGE-M3
+  self-hosted; bulk embedding calls skip the AI Gateway (the one carve-out from the
+  blanket gateway rule). No dedicated vector DB or SaaS search service.
+- Object storage: R2 by default, always behind an S3-compatible layer so AWS S3/Azure
+  Blob/MinIO work for licensed self-hosted deployments. Short-lived scoped access
+  (presigned), size/type validation on upload. Keys never expose raw user/workspace IDs —
+  documented prefix + nanoid (`wl_`, `ua_` style).
+- Blob GC deletes the storage object before the DB reference row — a crash mid-delete
+  must never leave a live dangling reference.
+- TimescaleDB is opportunistic, never required: feature-detect and fall back to native
+  `PARTITION BY RANGE` + BRIN in the same migration, so self-hosted installs work on
+  plain Postgres.
+
+## Schema discipline
+
+- Extend an existing table before creating a new one; when two tables serve the same job,
+  merge. Keep sync (`*_change_log`), audit (`audit_log`), and versioning (`*_revisions`)
+  as three separate, non-overlapping tables — never substitute one for another.
+- IDs: one global helper — UUIDs (v7 where ordering matters) internal, prefixed nanoids
+  public-facing. Timestamps `timestamptz` UTC, rendered in the user's timezone; money in
+  integer minor units; durations integer milliseconds. Prefer checked text over Postgres
+  enums for evolving vocabularies.
+- Secrets and PII never sit in plaintext columns (including inside JSONB) —
+  broker-wrapped envelope encryption only (security.md).
+- JSONB-on-row vs. dedicated table has no house default — MK has ruled both ways by
+  context. Present the tradeoff (volume, query needs, audit requirements) and ask.
+
+## Backups and recovery
+
+- Self-managed Postgres ships with WAL archiving + scheduled base backups from day one —
+  a database without a tested restore path is not production, whatever else is true.
+- A restore runbook (where backups live, how to restore, measured time) is a phase-0
+  deliverable for any live product; note RPO/RTO in dev.md's `## Architecture`. Test the
+  restore, don't assume it.
+- R2/object storage: no bucket versioning by default — deletion protection is the
+  object-before-row GC discipline plus lifecycle rules, planned explicitly.

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

@@ -0,0 +1,99 @@
+# Infra — hosting, CI cost, observability
+
+## Hosting targets
+
+Two sanctioned targets, recorded in dev.md's `## Architecture`:
+
+- **Cloudflare Workers via OpenNext** — the default for public web products. Once
+  committed to Cloudflare, never stand up a parallel Vercel deploy path (deploy paths
+  drift); shared packages must still *work* on Vercel for downstream consumers —
+  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 needing 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
+  trigger-gated — DO when live collaboration actually ships, 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 first.
+- Multi-env via the Workers environments feature (`env.*`) — never separate top-level
+  Workers per environment; environments are `dev` / `preview` / `production`, and the
+  `staging` git branch deploys to `preview`. One Hyperdrive per environment, shared by
+  every service hitting the same database. Naming: hyphen-only; purge inconsistent legacy
+  names.
+- Domains: production on `vegastack.com`; non-prod under `*.vegastack.dev`. Every Worker
+  sets `workers_dev: false` + `custom_domain: true` — the default `*.workers.dev` origin
+  bypasses Cloudflare Access, exposing a gated Worker unauthenticated (security, not
+  cosmetics). Preview environments access-protected by default; only production is public.
+- Secrets per environment (`wrangler secret put X --env production`). Local env files:
+  `.env` feeds `next dev`, `.dev.vars` feeds `wrangler dev` — 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
+  (current adapter caveats: pinned-facts).
+- 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). 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 why.
+- 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, within the budget the architecture
+  owner states for that server (ask if none stated — don't guess); Coolify's own footprint:
+  pinned-facts. Cloud infra beyond Cloudflare goes through Terraform, IAM scoped narrowly per
+  purpose.
+- Any infra cleanup (disks, stale resources, runners) needs explicit authorization first,
+  scoped to verified-stale items — never blanket cleanup.
+
+## CI cost and verification (workflow gates and ship mechanics live in dev.md)
+
+- CI is cost-managed, not maximal: path-condition expensive jobs so docs-only changes skip
+  them; push heavy verification into local hooks and self-hosted runners; hosted Actions
+  minutes are a tracked budget. Verification is local-first — CI verifies it happened via
+  a committed receipt 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.
+
+## 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; the full OTel SDK/collector only
+  when cross-service trace correlation becomes a real pain.
+- 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 and the analytics
+  dashboard (current limits and billing dates: pinned-facts).
+- Alerting honest to team size: an uptime monitor (Uptime Kuma-class) + a cron checking
+  error-rate thresholds in the event table posting to Slack, plus a dead-man's-switch ping
+  for silent job failures. No paging/SLO/on-call ceremony — 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 rule applies under pressure too. Rolling back a deploy IS a deploy: it needs the
+  operator's go-ahead — bring them the evidence and the recommended rollback; mitigation
+  that doesn't deploy (feature-level disable, traffic block) can proceed and be reported.
+- Every real incident gets a short postmortem in the project's `docs/postmortems/`: what
+  happened, root cause, the guard that now prevents it. An incident that doesn't change a
+  rule or a check will repeat.

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 the architecture owner 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 the architecture owner rather than assume): push-notification provider,
+offline/sync expectations per product, store-release cadence.

package/skill/dev-architect/references/pinned-facts.md

@@ -0,0 +1,133 @@
+# Pinned platform facts
+
+Dated, source-verified facts that change architecture decisions and that models routinely
+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.
+
+Facts carry their own verification dates — sections verified 2026-08-12 unless a
+bullet says otherwise; Better Auth and EVE re-verified 2026-08-29.
+
+## 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.
+- **`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.
+  [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.7.2, 2026-08-29)
+
+- **1.7 is stable** — 1.7.0 shipped 2026-08-18, current 1.7.2 (2026-08-26, npm latest).
+  The former 1.6.x hold is retired; adopt 1.7.x via the official migration steps. Notable
+  1.7.0 breaks beyond the bullets below: accounts rekeyed on `(issuer, accountId)` with a
+  migration backfill; `validAudiences` → `resources` + `oauthClientResource`;
+  `experimental.joins` → `advanced.database.joins`; generic OAuth rewritten on OAuth 2.1
+  defaults. [github.com/better-auth releases, verified 2026-08-29]
+- **The MCP plugin lives in `@better-auth/mcp` since 1.7.0** — requires
+  `@better-auth/cimd` and the `jwt()` plugin; `withMcpAuth` → `requireMcpAuth`,
+  `mcpHandler` → `createMcpProtectedRequestHandler`; options are flat, no `oidcConfig`
+  nesting. [releases/tag/v1.7.0]
+- **SAML IdP-initiated sign-in is default-off since 1.7.0** (`saml.allowIdpInitiated`
+  defaults to false); opt back in explicitly only where the IdP flow is required.
+  [releases/tag/v1.7.0, verified 2026-08-29]
+- **The organizations plugin models teams, invitations, and custom RBAC end-to-end**
+  (`teams: { enabled: true }`, `inviteMember` with `teamId`, `createAccessControl`) —
+  unchanged in 1.7 (SCIM was decoupled from it; irrelevant unless SCIM is used).
+  [better-auth.com/docs, verified 2026-08-29]
+- **The apiKey plugin is the standalone `@better-auth/api-key` package** (lockstep
+  1.7.2) — import from `@better-auth/api-key`, not `better-auth/plugins` (core's exports
+  no longer carry it). Default to the plugin for new projects; the flagship platform's
+  native implementation is a recorded project decision, not the house default. The
+  `bearer` plugin stays in core and covers token session transport (the mobile/Flutter
+  mechanism). [better-auth.com/docs/plugins/api-key, verified 2026-08-29]
+- **`twoFactor` supports `allowPasswordless: true`** for users without password accounts
+  (passkey/OAuth/magic-link signups). Since 1.7.0, `enableTwoFactor` takes and returns a
+  discriminated `method: "otp" | "totp"` (default totp) — pass `method: "otp"` for OTP
+  enrollment.
+
+## Claude API (verified 03-09-2026)
+
+- **Thinking blocks bind to their conversation prefix on Claude Fable 5.1**: replaying one after
+  the system prompt, tools, or an earlier message changed returns a 400 for accounts created on
+  or after 31-08-2026 (future models: everyone); keep product agent loops append-only.
+  **Assistant prefill on the last turn is a 400 from Claude 4.6 onward** — use structured outputs.
+  [platform.claude.com/docs/en/build-with-claude/prompt-engineering]
+
+## Agents & jobs
+
+- **EVE (`eve` on npm, github.com/vercel/eve) is Vercel's durable-agent framework — v0.47.3
+  (2026-08-28), still beta/pre-GA, shipping multiple releases per day; pin behavior, not
+  minor versions.** Filesystem-first agents; every 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".**
+  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/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 the
+architecture owner 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, the architecture owner 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; the architecture owner 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 the architecture owner 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 the architecture
+owner's sign-off; the register plus the issue briefs are the handover record.