@vegastack/skills 0.9.0 → 0.10.0

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",

package/skill/dev-implement/SKILL.md

@@ -7,7 +7,7 @@ description: Implement an approved GitHub issue end to end without further user
 
 One issue, one session, end to end: preflight → claim → build dark → verify → review → evidence in the issue → stop. The user reads the result in the issue on their own time; nothing here creates a PR or merges — those are `dev-ship`, on the user's word.
 
-Nearest neighbor: `dev-intake` writes the brief this skill executes; if the issue turns out to need decisions, that's intake work — hand it back via `needs-operator`, don't guess. `.vegastack/dev.md` missing → run `dev-setup` first. Read dev.md before anything; its knobs (review, ui-evidence, tests, branch, stop-list) govern this whole skill.
+Nearest neighbor: `dev-intake` writes the brief this skill executes; if the issue turns out to need decisions, that's intake work — hand it back via `needs-operator`, don't guess. `.vegastack/dev.md` missing → run `dev-setup` first. Read dev.md before anything; its knobs (review, ui-evidence, tests, branch, stop-list) govern this whole skill, and when the issue touches stack surfaces (schema, auth, hosting, services, jobs) its `## Architecture` section governs those choices the way the knobs govern process.
 
 ## Direct requests
 
@@ -19,7 +19,7 @@ The gates exist to stop agent-invented authority, never to slow the user down. W
 - The issue is open, labeled `ready`, and carries the recorded approval comment (`Approved by … : "…"`). A label without the comment is not approval.
 - No open blockers (issue dependencies) and no other assignee — an assigned or `working` issue belongs to someone else. A claim from a dead session is released only by the user: take over a `working` issue only when they explicitly hand it to you.
 - Read the complete brief, plus parent issue and milestone for context. If the brief leaves a material decision open — including an unresolved Assumptions entry — do not start: label `needs-operator`, comment the smallest question that unblocks it, stop.
-- Re-verify the brief against reality before coding: its cited touch points against the current code (things drift between approval and execution), and volatile dependency claims when stale or version-sensitive. Reality contradicting the brief is a stop — label `needs-operator` with the discrepancy; an approved brief is never a license to improvise past what's actually there.
+- Re-verify the brief against reality before coding: its cited touch points against the current code (things drift between approval and execution), and volatile dependency claims when stale or version-sensitive (per `dev-architect`'s verify protocol). Reality contradicting the brief is a stop — label `needs-operator` with the discrepancy; an approved brief is never a license to improvise past what's actually there.
 
 ## Claim and branch
 
@@ -27,7 +27,7 @@ Assign yourself, swap `ready` → `working`. Branch from the default branch per
 
 ## Build — dark
 
-No progress updates, no questions. A spike the brief flagged runs first — its result opens the evidence comment and shapes the rest of the build. Decide routine things yourself: file layout, helpers, fixtures, and root-cause fixes inside the issue's change areas. The brief's out-of-scope section and the dev.md stop-list bound you; hitting a stop condition (scope change, new dependency, spending, destructive/production action, unresolvable blocker) ends dark mode — post one `needs-operator` comment stating the smallest decision needed with your recommendation, and stop.
+No progress updates, no questions. A spike the brief flagged runs first — its result opens the evidence comment and shapes the rest of the build. Decide routine things yourself: file layout, helpers, fixtures, and root-cause fixes inside the issue's change areas. A structural choice mid-build — a new dependency, table, or service — checks `dev-architect`'s trigger discipline first; a moving part with no named trigger is a stop condition, not a judgment call. The brief's out-of-scope section and the dev.md stop-list bound you; hitting a stop condition (scope change, new dependency, spending, destructive/production action, unresolvable blocker) ends dark mode — post one `needs-operator` comment stating the smallest decision needed with your recommendation, and stop.
 
 Honesty over green: a failing test gets fixed at the root or reported as failing. Weakening a test, an assertion, or acceptance to pass is a cover-up, and cover-ups surface at review with interest.
 

package/skill/dev-intake/SKILL.md

@@ -14,7 +14,7 @@ Nearest neighbor: `dev-implement` consumes what this produces — intake writes
 Finding facts is your job, never the user's — and a brief built on unverified facts is a confident mistake waiting for dark mode. The source can be one sentence in chat; thinner material just means the grounding and interview carry more weight. Before the first question:
 
 - **Read the touched code.** Open the actual paths the feature would change: current behavior, existing patterns to reuse, where the new work plugs in. The brief cites these real paths later — a brief naming no files is a sign this step was skipped.
-- **Verify dependencies.** Any library, service, or API capability the approach leans on gets checked against current official docs (docs tools or web search), noted with the date. Consult `architect`'s pinned facts for stack questions before re-researching; re-verify a pinned fact older than 60 days; skip lookups for long-stable basics — judgment, not ritual.
+- **Verify dependencies.** Any library, service, or API capability the approach leans on gets checked against current official docs (docs tools or web search), noted with the date. Stack, schema, auth, and infra approach choices route through `dev-architect` — its verify-before-you-recommend protocol governs the check (pinned facts first, live docs on a miss or a fact older than 60 days); skip lookups for long-stable basics — judgment, not ritual.
 - **Cross-check the request** against product docs and current behavior. A contradiction is pushback, never a silent resolution: "you asked for X; the code/docs currently do Y — which wins?" Push back on cost the same way: when a simpler version covers most of the need, name it.
 - **Triage every unknown** into exactly three bins: *findable* → find it now, yourself; *only-the-user-knows* → ask, with a recommendation; *only-running-code-can-tell* → flag it as a spike that becomes the issue's first step. Guessing is not a bin.
 
@@ -32,7 +32,7 @@ Work the design the way a joint product-and-tech review would; each round's answ
 
 1. **Product** — who this is for, the observable outcome, what's in and out of scope now, how it splits into slices or phases, priority.
 2. **Behavior** — primary and alternate flows, rules, permissions, validations, edge and failure cases; for UI, the states, components, and copy.
-3. **Technical** — only the choices that are genuinely the user's: approach trade-offs, data and interface implications, integrations, migration; recommend one and say why. When the project versions releases (dev.md `changelog:` knob), settle the intended version impact (patch/minor/major) here — the brief records it and dev-implement's changelog entry starts from it. Routine implementation stays the implementer's.
+3. **Technical** — only the choices that are genuinely the user's: approach trade-offs, data and interface implications, integrations, migration; recommend one and say why — checking `dev-architect` first so a brief never proposes a recorded rejection or a moving part without its trigger. When the project versions releases (dev.md `changelog:` knob), settle the intended version impact (patch/minor/major) here — the brief records it and dev-implement's changelog entry starts from it. Routine implementation stays the implementer's.
 4. **Quality and risk** — what proves it works (test cases, acceptance), what earns the `risky` label, what should stop a dark run beyond the standing stop-list.
 
 These are the brief template's sections in interview form — a question exists only where reading the material, the codebase, and sensible defaults cannot fill a section.

package/skill/dev-setup/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: dev-setup
-description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", or invoked as dev-setup; also run automatically when dev-intake, dev-implement, or dev-ship find no .vegastack/dev.md in the project. Detects the stack and drafts its native release, changelog, and guard conventions; creates the project profile, the AGENTS.md dev section plus CLAUDE.md import, the workflow labels, and the decision register; offers release-guard workflows and the decision-capture hook on the user's yes. Not for architecture profiles or advice (that is architect and .vegastack/arch.md), not for authoring skills, not for general CI or app scaffolding.
+description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", or invoked as dev-setup; also run automatically when dev-intake, dev-implement, or dev-ship find no .vegastack/dev.md in the project. Detects the stack and drafts its native release, changelog, and guard conventions; creates the project profile, the AGENTS.md dev section plus CLAUDE.md import, the workflow labels, and the decision register; offers release-guard workflows and the decision-capture hook on the user's yes. Not for architecture advice (that is dev-architect reading the dev.md Architecture section this skill writes), not for authoring skills, not for general CI or app scaffolding.
 ---
 
 # dev-setup
 
 Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs and runbooks, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request.
 
-Nearest neighbor: `architect` owns `.vegastack/arch.md` (architecture facts and advice); dev-setup owns `.vegastack/dev.md` (workflow facts and knobs). When arch.md exists, point dev.md at it for stack facts instead of duplicating them.
+Nearest neighbor: `dev-architect` consumes dev.md's `## Architecture` section and gives architecture advice; dev-setup detects the facts and writes the section. There is no separate architecture profile — dev.md is the one file.
 
 ## Step 1 — Detect before asking
 
@@ -21,7 +21,8 @@ Facts are your job; decisions are the user's. Gather these silently and present
 | web app (UI evidence relevant) | framework dependencies (next, react, vue, …) |
 | release/changelog machinery | match signals against [stack-playbooks](references/stack-playbooks.md) — the matched playbook drafts the `## Ship` runbook, the `changelog:` knob, and the guards to offer |
 | environments and run commands | CI/deploy configs, env examples (names only), dev/start scripts — these draft `## Environments` and `## Verify` |
-| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, `.vegastack/arch.md`, the decision register |
+| architecture (app repos) | wrangler files (a `d1_databases` binding with no Postgres driver = the D1-only class), drizzle config, better-auth usage, `@aws-sdk/client-s3`/R2 bindings, pg-boss dependency, `eve`/`ai` packages, Dockerfiles/compose, pubspec.yaml — these draft `## Architecture` |
+| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, a legacy `.vegastack/arch.md`, the decision register |
 | existing labels | `gh label list` |
 
 Not a git repo, or no origin remote → this is a **greenfield run, not an error**: follow the greenfield playbook in [stack-playbooks](references/stack-playbooks.md) — interview for the intended stack, offer `git init` and `gh repo create` each on its own yes, and render dev.md from the chosen playbook's conventions with TODO lines where machinery doesn't exist yet. A declined remote skips labels and records the TODO plainly.
@@ -30,7 +31,7 @@ Not a git repo, or no origin remote → this is a **greenfield run, not an error
 
 Ask with your harness's question tool — AskUserQuestion in Claude Code, `request_user_input` in Codex where the mode allows it (availability details: [harness-facts](references/harness-facts.md)). When no question tool is available (headless run, gated mode), write the defaults, mark every unconfirmed knob `# TODO confirm`, and say so in your reply — a wrong invented preference costs more than a TODO.
 
-**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not, matched playbook). Ask only about what detection could not fill.
+**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not, matched playbook, detected architecture facts). Ask only about what detection could not fill.
 
 **Round B — the workflow knobs**, recommended default first:
 
@@ -45,6 +46,8 @@ Ask with your harness's question tool — AskUserQuestion in Claude Code, `reque
 - Guards drafted → offer to write their CI backstop steps into the project's workflow files (the local `guard:` lines run without CI); each file on the user's yes — release guards only, never general CI
 - Environments or run commands detected → confirm the drafted `## Environments` and `## Verify` bullets
 - Evidence repo (`ui-evidence: playwright`) → default is the owner's **shared** `<owner>/dev-review-evidence`; if it doesn't exist, offer `gh repo create <owner>/dev-review-evidence --private --add-readme` + the layout/retention README — created once, every project points at it. An org naming policy that rejects the name → pick the closest compliant name with the user and record it in the knob (the name is a knob value, not a contract)
+- App architecture detected → confirm the drafted `## Architecture` (hosting, stage, and kind are what detection usually can't fill — ask those); nothing detected → delete the section, the `stack:` line is enough
+- A legacy `.vegastack/arch.md` exists → fold its knob lines into `## Architecture`, offer each dated `notes:` line to the decision register on the user's yes, then offer to delete arch.md
 - Decision-capture hook → offer the Stop-hook from [harness-facts](references/harness-facts.md) for the harnesses in use; hook files and settings wiring are written only on the user's explicit yes, merging into existing hook config, never overwriting
 - AGENTS.md already has content → append the marked section (default) or show a merge proposal first
 - CLAUDE.md already has content → add the `@AGENTS.md` import as its first line (default) or move its content into AGENTS.md and leave only the import
@@ -56,7 +59,7 @@ Everything else — merge style, branch naming, the stop-and-ask list — takes
 
 | Target | Action |
 |---|---|
-| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — the project's single canonical process doc (short directional bullets; Ship/Verify/Environments/Design drafted from the playbook, Decisions test included, placeholders deleted, TODO lines where machinery is absent) |
+| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — the project's single canonical process doc (short directional bullets; Ship/Verify/Environments/Design drafted from the playbook, Architecture drafted from detection, Decisions test included, placeholders deleted, TODO lines where machinery is absent) |
 | `AGENTS.md` | create it, or insert/replace only the block between `<!-- vsk-dev:start -->` and `<!-- vsk-dev:end -->` using the [agents-section template](assets/agents-section.md.template); content outside the markers is the user's and stays untouched |
 | `CLAUDE.md` | ensure its first line is `@AGENTS.md` — Claude Code does not read AGENTS.md natively and needs this import ([harness-facts](references/harness-facts.md)); create the file when absent |
 | labels | `gh label create <name> --color <hex> --description "<text>"` for the names the `labels:` knob records, skipping ones that exist; default names and creation colors: `needs-operator` FBCA04 (waiting on the user) · `ready` 0E8A16 (approved, agent may start) · `working` 1D76DB (claimed by an agent) · `for-operator` 5319E7 (result awaiting user review) · `risky` B60205 (security, money, data, or production) |