@vegastack/vegafactory 0.19.0

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

@@ -0,0 +1,90 @@
+# Security & auth
+
+Auth, tenancy-isolation, and secrets work is the highest-rigor tier: extra precision on
+every change, and a focused security audit after any auth-adjacent change before it's done.
+
+## Authentication (Better Auth, always)
+
+- Email/password + Google sign-in is the default configuration; magic link and email OTP
+  as flows demand; 2FA TOTP when the product warrants (`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. 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: Better Auth's apiKey plugin by default. Whatever implements them, the
+  invariants hold: hash-stored with a recognizable prefix, raw value shown exactly once
+  and never cached or logged again, constant-time compare on verify.
+
+## Authorization
+
+- Middleware/proxy is never the boundary (CVE-2025-29927 class). The boundary is a
+  server-only data-access layer — `requireSession()`/`requireOrgRole()`-style helpers,
+  re-checked per resource, on every route, auth before body parse.
+- Every check fails closed: a policy-engine error, throw, or unmatched rule resolves to
+  deny, and the deny is still audited. No `DISABLE_AUTH`-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 at
+  platform scale; today only the flagship platform has earned it. Anyone else proposing
+  one: present the trigger and ask the architecture owner.
+- 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; 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". 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, wrangler.jsonc, generated output,
+  logs, audit records (redact to a short prefix), agent state, or JSONB columns.
+  Cloudflare Worker secrets and GitHub secrets are the storage; a credential broker
+  (envelope AES-256-GCM, AAD bound to org+credential+key-version, fresh per-secret DEK)
+  when the product stores third-party credentials.
+- OAuth: authorize/token URLs resolved server-side from a fixed allowlist (never
+  caller-supplied); state single-use and session-bound; refresh tokens broker-wrapped.
+- OpenBao/vault infrastructure only on named triggers — self-hosting customer-managed
+  secrets, multi-service identity, dynamic DB credentials — never "because production".
+- The operator enters OTP/2FA/credentials themselves, always. Agents never type or
+  automate through credential prompts.
+
+## Requests out and untrusted content
+
+- 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), 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. 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
+  the predecessor row (`SELECT ... FOR UPDATE`) before computing the next hash — unlocked
+  concurrent writers silently fork the chain.
+
+## Verifying security findings
+
+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 the architecture owner'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 the architecture owner 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 the architecture owner when building one.

package/skill/dev-architect/refresh/REFRESH.md

@@ -0,0 +1,31 @@
+# Freshness contract — dev-architect
+
+Most of this skill is durable taste and recorded decisions; it does not go stale on its
+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
+
+1. **Weekly scheduled agent (primary).** A scheduled Claude Code/Codex job re-verifies
+   each pinned fact against its stated source URL and opens ONE pull request quoting
+   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).** 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.
+
+## Rules
+
+- Critical sources (Hyperdrive supported versions, Better Auth docs, eve/Workflow SDK
+  deploy constraints) get `critical: true` — drift there warrants a prompt PR, not a
+  batch.
+- Every edited fact keeps the pattern: fact → why it changes a decision → source URL →
+  verified date. The file carries one blanket verified-date for facts checked together;
+  a fact re-verified alone gets its own inline date, superseding the blanket one.
+- A fact that stops being decision-changing is deleted, not kept for completeness.

package/skill/dev-architect/refresh/sources.json

@@ -0,0 +1,239 @@
+{
+  "schemaVersion": 1,
+  "policy": {
+    "criticalTopics": [
+      "hyperdrive-postgres",
+      "better-auth",
+      "eve-deploy"
+    ],
+    "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 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"
+  },
+  "sources": [
+    {
+      "id": "CF-HYPERDRIVE-VERSIONS",
+      "service": "Cloudflare Hyperdrive supported databases",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "hyperdrive-postgres"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/data.md"
+      ],
+      "checksum": "fda2870b95deffce48dca7f3df3707325b1bc4a2d58a17708ee9220bfba5eba1",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "CF-R2-PRICING",
+      "service": "Cloudflare R2 pricing",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://developers.cloudflare.com/r2/pricing/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "r2-economics"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/stack.md"
+      ],
+      "checksum": "bd5e8d26f7bbf2f92182ad4ac1a59ae9b1d90695120062adaf54c281bd88e81f",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "CF-WORKFLOWS-PRICING",
+      "service": "Cloudflare Workflows limits and pricing",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://developers.cloudflare.com/workflows/reference/limits/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "workflows"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md"
+      ],
+      "checksum": "64e10ca4ced4edc042d12a9a24f2e165ea71cb9481c30ac5f067f2f6c9218cda",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "BETTER-AUTH-DOCS",
+      "service": "Better Auth documentation",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://better-auth.com/docs/plugins/organization"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "better-auth"
+      },
+      "topics": [
+        "better-auth"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/security.md"
+      ],
+      "currentVersion": "1.7.2",
+      "versionCheckedAt": "2026-08-29T05:56:59.737Z",
+      "checksum": "905fef0ef5b216abae2fcb14c7c7ea9b74c4788acc7fd65e8ad72600b13d670f",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "EVE-DOCS",
+      "service": "Vercel eve agent framework",
+      "kind": "official-docs",
+      "stability": "beta",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://vercel.com/docs/eve"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "eve"
+      },
+      "topics": [
+        "eve-deploy"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md"
+      ],
+      "currentVersion": "0.47.3",
+      "versionCheckedAt": "2026-08-29T05:56:59.737Z",
+      "checksum": "84a499a2bc49274d6736703b0d82b774822c7d5e9d69954a73262eff4af72614",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "WORKFLOW-SDK-POSTGRES",
+      "service": "Workflow SDK Postgres world deployment constraints",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://workflow-sdk.dev/worlds/postgres"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "@workflow/world-postgres"
+      },
+      "topics": [
+        "eve-deploy"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md"
+      ],
+      "currentVersion": "4.3.5",
+      "versionCheckedAt": "2026-08-29T05:56:59.737Z",
+      "checksum": "d99e33159e2259f8f71d22f2bd19ffbc284ff55e1d8e9916d4930725fb55461a",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "NEXTJS-BLOG",
+      "service": "Next.js release blog",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://nextjs.org/blog"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "next"
+      },
+      "topics": [
+        "nextjs"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/web.md"
+      ],
+      "currentVersion": "16.3.3",
+      "versionCheckedAt": "2026-08-29T05:56:59.737Z",
+      "checksum": "5485cefce17dd80d1062364c597dbef4ebe39b7a59e869458b53d618c4f6f57d",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "PG-BOSS-NPM",
+      "service": "pg-boss job queue",
+      "kind": "package-registry",
+      "stability": "stable",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://registry.npmjs.org/pg-boss/latest"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "pg-boss"
+      },
+      "topics": [
+        "jobs"
+      ],
+      "affected": [
+        "references/pinned-facts.md"
+      ],
+      "currentVersion": "12.28.1",
+      "versionCheckedAt": "2026-08-29T05:56:59.737Z",
+      "checksumScope": "http-body",
+      "checksum": "6d1863268232526ae87582d9cba6f7ba148d91888409456a033c1f6b7e2f00f4",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    },
+    {
+      "id": "FLUTTER-RELEASES",
+      "service": "Flutter release notes",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://docs.flutter.dev/release/release-notes"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "flutter"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/mobile.md"
+      ],
+      "checksum": "833a60e3142d8944af96eb33a6266fb27cdbfedb3f72db9765098f81bdabfa9d",
+      "retrievedAt": "2026-08-29T05:56:59.737Z"
+    }
+  ]
+}

package/skill/dev-chronicle/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: dev-chronicle
+description: The project's narrative record — what got built, why, and how it went, in plain language for the operator's future recall. Use when asked to "catch me up on this project", "what did we build here", "what happened in this repo", "tell me the story so far", "what's the project story", when a chronicle entry needs writing for finished work, or when dev-implement's hand-back cites the chronicle format. Not for the consumer-facing changelog (dev-implement writes those per the changelog knob), release notes (dev-ship), or current board state ("what needs me" is dev-status).
+---
+
+# dev-chronicle
+
+Act: write the project's story for the operator who returns months later — exact terms, plain language, one honest line on how it went.
+
+`.vegastack/chronicle.md` is the project's story, newest first — the answer to "what did I build here and what happened?" months later, when the operator remembers nothing. Entries are **story language for a human**, because the changelog already tells consumers what changed and the chronicle is for the operator who wants to know what happened.
+
+Nearest neighbors: `dev-implement` writes the entries at hand-back (the write rule lives there; the format lives here); `dev-status` answers "what needs me now" — this skill answers "how did we get here". `dev-ship`'s ship-gate checks entry presence when dev.md says `chronicle: on`.
+
+## The entry — one per behavior-changing branch
+
+```markdown
+## DD-MM-YYYY — <title: the change as a human outcome — not a mechanism, not a commit subject> ([#<issue>](<issue url>))
+
+- **What:** <2–4 plain sentences: what exists now that didn't, from the operator's point of view>
+- **Why:** <the need that prompted it>
+- **How it went:** <the honest one-liner: smooth / what fought back / what was cut>
+- **Changed:** <the user-visible changes, simple words — sub-bullets or one ·-separated line>
+- **Decisions:** <register lines it produced, or "none">
+
+— approved by (<username>) · built by <agent> · branch <name>
+```
+
+- Titles name the outcome ("Invoice reminders now chase late payers"), because the mechanism ("add reminderAt column") is the commit subject's job. Issue references are full markdown links to `…/issues/<n>` (correct for PRs too — GitHub redirects), because file views don't auto-link a bare `#N`.
+- The fields are list items and the footer sits after a blank line — single newlines soft-wrap into one paragraph in rendered markdown; bullets are what guarantee a line per field.
+- Prepend — newest first. File missing → create it with a two-line header naming this skill as the format home.
+- **How it went** is where honesty lives: what fought back, what was cut, what surprised. "Smooth" is a fine answer; silence is not.
+- Research issues get an entry only when the findings changed direction; docs/test-only merges get none (ship-gate's excuse flag covers both records at once).
+- A notable ship event — rollback, failed release — becomes its own short entry on the next branch. Entries are append-only like the register — a typo is the one edit — because a rewritten chapter is a story nobody can trust.
+- An entry runs 80–200 words; the digest scales with the ask.
+
+## Style — tone, not length
+
+dev.md's `chronicle-style:` knob (`plain` default · `story` · `witty`) sets the voice and `emoji:` (`none` default · `sparing`) the emoji budget; the rule every style follows, the boundary of `witty`, and one worked example per style live in [styles](references/styles.md). In every style, domain keywords stay exact and every factual field says what it means, because the operator searches the chronicle for the terms they remember.
+
+## The digest — "catch me up"
+
+On "catch me up on this project" (or any story-so-far ask), read only the chronicle and the decision register, because the digest is the story as told, not reconstructed, and render three parts, plain language throughout:
+
+1. **The story so far** — 3–5 sentences: what this project is, the arc of what's been built, where it stands.
+2. **Recent chapters** — the last 3–7 entries, one line each: date, the outcome title, and the one thing worth remembering from How-it-went.
+3. **Open threads** — pending decisions the register hasn't recorded, entries whose How-it-went named unfinished business, and (when `dev-status` is installed) a one-line pointer to run it for the live board.
+
+Length scales with the ask: "catch me up quickly" is one paragraph; a returning-after-months operator gets all three parts. A young project with three entries gets three honest lines, because padding is the mannered prose the style rule excludes.
+
+## Setup
+
+The `chronicle:` knob in dev.md (`on` default | `off`) governs whether dev-implement writes entries and ship-gate checks them; `chronicle-style:` and `emoji:` govern how they read; `dev-setup` writes all three. A project that turns it on mid-life starts from now — no retroactive backfill unless the operator asks, and then it's marked as reconstructed.

package/skill/dev-chronicle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-chronicle"
+  short_description: "The project's story — entries and the catch-me-up digest"
+  default_prompt: "Use $dev-chronicle to catch me up on this project."