voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-server/skills/void-background-job-pattern/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: void-background-job-pattern
+description: "Run async work outside the request lifecycle: when to use a queue (Inngest, Trigger, Cloudflare Queues) vs a cron route. Idempotency, retry, dead-letter. Self-contained, no harness wrappers."
+---
+
+# background-job-pattern
+
+Use when work needs to happen **outside the user's request lifecycle** — too slow for the 10s HTTP timeout, or scheduled, or needing retry. Default in void-machine: a managed queue (Inngest, Trigger.dev, Cloudflare Queues) for event-driven jobs; route handlers + cron config for time-based.
+
+If the work completes in < 200ms AND happens during the request anyway, do it inline. Background jobs add latency to the UX (work happens later) and infrastructure cost. Not the default.
+
+## When to use a background job
+
+- Sending an email after signup (don't block the signup response on SMTP)
+- Generating a PDF/export (multi-second work)
+- Recomputing a cache after data change
+- Polling an external API on schedule
+- Cleanup tasks (delete soft-deleted rows after 30 days)
+- Webhook retries when initial handler fails recoverably
+
+## When NOT to use a background job
+
+- Work that the user is actively waiting for (use Server Actions, await inline)
+- Work that depends on per-request context (cookies, headers) the queue won't have
+- Sub-100ms operations (queue overhead > work cost)
+- One-off scripts (use a runbook, not a job)
+
+## Three job types
+
+| Type | Trigger | Tool example |
+|---|---|---|
+| **Event-driven** | Code event ("user.signed_up") | Inngest, Trigger.dev, Cloudflare Queues |
+| **Scheduled** | Cron expression | Vercel Cron, Inngest schedule, Upstash QStash |
+| **One-shot** | Manual or webhook | Same as event-driven |
+
+Pick the type by **the trigger**, not by the work.
+
+## The 5 layers every job must implement
+
+```
+1. Validate input        — Zod schema on the event payload
+2. Idempotency           — same event delivered twice = one effect
+3. Trace context         — log job name + event ID
+4. Service call          — the business work in src/services/
+5. Retry classification  — throw retryable errors, classify permanent ones
+```
+
+These hold whether you use a queue's native helpers or write the job by hand. The pattern is the substance.
+
+## Event-driven jobs (Inngest example)
+
+```ts
+// apps/web/src/jobs/send-welcome-email.ts
+import { inngest } from '@/adapters/inngest';
+import { z } from 'zod';
+import { logger } from '@repo/core';
+import { emailService } from '@/services/email';
+
+// 1. Validate event payload at the boundary (defense in depth)
+const EventData = z.object({
+  userId: z.string().uuid(),
+  email: z.string().email(),
+});
+
+export const sendWelcomeEmail = inngest.createFunction(
+  // 5. Retry classification: Inngest auto-retries thrown errors.
+  //    Non-retryable: throw NonRetriableError (Inngest's marker class).
+  { id: 'send-welcome-email', retries: 3 },
+  { event: 'user.signed_up' },
+  async ({ event, step }) => {
+    // 1. Zod validate at the job boundary
+    const data = EventData.parse(event.data);
+
+    // 3. Trace context (event.id is Inngest's correlation key)
+    logger.info({
+      event: 'job.start',
+      name: 'send-welcome-email',
+      userId: data.userId,
+      eventId: event.id,
+    });
+
+    // 4. Do the work in a step (Inngest's retry checkpoint — only re-runs
+    //    failed steps on retry, not the whole function)
+    await step.run('send-email', async () => {
+      await emailService.sendWelcome({ to: data.email });
+    });
+
+    // 2. Idempotency: Inngest dedupes by event.id automatically for the
+    //    same function. For non-Inngest queues, do `INSERT ON CONFLICT
+    //    DO NOTHING` in an inbox table with event.id as key.
+
+    return { ok: true };
+  },
+);
+```
+
+Trigger from a Server Action:
+
+```ts
+await inngest.send({ name: 'user.signed_up', data: { userId, email } });
+```
+
+Inngest's `step.run` IS the retry checkpoint. Trigger.dev and Cloudflare Queues have similar primitives (`task`, `step`). Use what your queue gives you natively. No wrapper from this pack required.
+
+## Scheduled jobs (Vercel Cron example)
+
+```ts
+// apps/web/src/app/api/cron/cleanup/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { env, logger } from '@repo/core';
+import { cleanupSoftDeleted } from '@/services/admin';
+import * as Sentry from '@sentry/nextjs';
+
+export async function GET(req: NextRequest) {
+  // 1. Auth via cron secret (Vercel injects the Authorization header
+  //    based on the CRON_SECRET env var)
+  const auth = req.headers.get('authorization');
+  if (auth !== `Bearer ${env.CRON_SECRET}`) {
+    return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
+  }
+
+  // 2. Concurrency lock — skip if a previous run is still in-flight.
+  //    Implement with Redis SETNX, Postgres advisory lock, or your
+  //    queue's native job-deduplication.
+  const lock = await tryAcquireLock('cron:cleanup', { ttlMs: 10 * 60 * 1000 });
+  if (!lock) {
+    logger.warn({ event: 'cron.skip', reason: 'previous-run-active', name: 'cleanup' });
+    return NextResponse.json({ ok: true, skipped: true });
+  }
+
+  try {
+    // 3. Trace context
+    logger.info({ event: 'cron.start', name: 'cleanup' });
+
+    // 4. Do the work
+    const result = await cleanupSoftDeleted({ olderThanDays: 30 });
+
+    logger.info({ event: 'cron.done', name: 'cleanup', deleted: result.count });
+    return NextResponse.json({ ok: true, deleted: result.count });
+  } catch (err) {
+    // 5. Always log + notify on cron failure; silent 500 means next run
+    //    might also fail without anyone noticing
+    Sentry.captureException(err, { tags: { cron: 'cleanup' } });
+    return NextResponse.json({ ok: false }, { status: 500 });
+  } finally {
+    await releaseLock(lock);
+  }
+}
+```
+
+`vercel.json`:
+
+```json
+{
+  "crons": [
+    { "path": "/api/cron/cleanup", "schedule": "0 3 * * *" }
+  ]
+}
+```
+
+The 5 layers (auth, concurrency lock, observability, work, error handling) are explicit. No wrappers required. `tryAcquireLock` / `releaseLock` are project-side primitives (Redis-backed, advisory lock, whatever fits) — typically 30 lines of code owned by the consumer.
+
+## Idempotency strategies
+
+Pick the one that matches your storage layer:
+
+- **Queue-native dedupe** (Inngest, Trigger): they dedupe on the event ID for the same function — free.
+- **Inbox table**: `INSERT ON CONFLICT DO NOTHING` on a key column; if no row inserted, you've seen this event.
+- **Service-level idempotence**: design the work so re-running is safe (`UPDATE WHERE status = 'pending'`).
+- **Cron with concurrency lock**: not strictly idempotent but prevents pile-up; combine with service-level idempotence for true safety.
+
+If none of these fit, you have a job that's unsafe to retry — flag it, write an ADR (`void-decide`).
+
+## Retry classification
+
+Most queues retry on throwing handlers. Distinguish:
+
+- **Retryable**: network errors, 5xx from external API, transient DB unavailability → throw normally
+- **Non-retryable**: validation failures (Zod), 4xx from external API, "user doesn't exist" → throw a marked error class your queue recognizes (Inngest: `NonRetriableError`; Trigger: `AbortTaskRunError`; Cloudflare Queues: custom field)
+
+If you can't tell, default to retryable. Worst case you waste retries; best case you survive a transient.
+
+## Dead-letter
+
+After retry budget exhausted:
+
+- Inngest, Trigger.dev, Cloudflare Queues have native DLQs — configure them
+- Or write your own `job_dead_letter` table the team reviews
+- Surface in `Settings → Background jobs → Dead letter` UI
+- Never silently drop a failed job
+
+## Anti-patterns
+
+- ✗ **`Promise.resolve().then(work)`** after a Server Action — serverless instance shuts down with the request; the work never runs
+- ✗ **One mega-job that does 10 things** — split per concern; one job per event type
+- ✗ **Cron without concurrency lock** — slow runs pile up, take down the worker
+- ✗ **Cron without secret check** — anyone hitting the URL triggers your cron
+- ✗ **Reading per-request context** — jobs don't have the user's cookies; pass identity in the event payload
+- ✗ **Logging without job name + event ID** — can't correlate failures back to triggers
+- ✗ **Sharing Zod schemas via copy-paste between sender and handler** — they drift; share via a `schemas/events.ts` module
+
+## Local development
+
+- **Inngest CLI**: `npx inngest-cli dev` runs a local worker + UI for piping events
+- **Trigger.dev**: `npx trigger.dev dev`
+- **Vercel Cron**: no local equivalent; call the route handler directly with the cron secret to simulate
+
+## Composition (informational — each skill stands alone)
+
+- `void-async-safety` — generic retry/idempotency/dead-letter doctrine.
+- `void-webhook-handler-pattern` — webhooks often emit events that trigger jobs.
+- `void-server-action` — actions emit events for async follow-up.
+- `void-env-validation` — `CRON_SECRET`, queue API keys validated.
+- `void-observability` — trace context links action → event → job.

package/core-assets/packs/pack-server/skills/void-background-job-pattern/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-server/skills/void-drizzle-migration-safe/.source

@@ -0,0 +1,6 @@
+Sources for `void-drizzle-migration-safe` skill (see `docs/plans/skill-audits/void-drizzle-migration-safe.md` for the full audit):
+
+- No external source audited — native Drizzle concretization of the `void-migrations` doctrine.
+- Tooling referenced (not vendored): Drizzle Kit (drizzle-kit generate/push), Postgres CONCURRENTLY / NOT VALID semantics.
+
+Strategy: native. Same principles as migrations, rewritten as concrete Drizzle SQL and code samples; no upstream skill was copied.

package/core-assets/packs/pack-server/skills/void-drizzle-migration-safe/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: void-drizzle-migration-safe
+description: "Write Drizzle migrations safe under concurrent traffic: zero-downtime add/rename of columns, indexes, FKs, enums. Composes with migrations for the generic discipline."
+---
+
+# drizzle-migration-safe
+
+Use when adding, modifying, or removing anything in a Drizzle schema that will be deployed to a production database with concurrent traffic. Composes with `void-migrations` (the generic doctrine); this skill ships the concrete Drizzle patterns.
+
+If you are working on a fresh schema before any prod deployment, this skill does not apply — use raw `drizzle-kit generate` and `drizzle-kit push`. The discipline starts at the first paid user.
+
+## When this skill triggers
+
+- "Add a column to the users table"
+- "Rename `created_at` to `inserted_at`"
+- "Make `email` not null"
+- "Add an index on (org_id, status)"
+- Any `pnpm db:generate` / `bun db:generate` followed by a manual review
+
+## Iron rules
+
+1. **Never combine schema change + backfill in one migration.** Each migration does one thing.
+2. **Never `ALTER COLUMN ... NOT NULL` without a backfill migration in between.** Two deploys minimum.
+3. **Always use `CREATE INDEX CONCURRENTLY` on Postgres** in production migrations — drizzle-kit doesn't add this by default, you must edit the generated SQL.
+4. **Never `DROP COLUMN` in the same release as the deploy that stops writing to it.** The old running pods will still write. Wait one deploy cycle.
+5. **Renames are deletes + adds.** Same as rule 4: ship the new column, dual-write for one cycle, then drop.
+
+## Pattern: adding a NOT NULL column
+
+```ts
+// Step 1 — migration 0042_add_users_locale.sql (deploy A)
+ALTER TABLE users ADD COLUMN locale text;        -- nullable, no default
+```
+
+```ts
+// Step 2 — backfill (deploy A.5, runs once)
+UPDATE users SET locale = 'fr' WHERE locale IS NULL;
+```
+
+```ts
+// Step 3 — migration 0043_users_locale_not_null.sql (deploy B)
+ALTER TABLE users ALTER COLUMN locale SET NOT NULL;
+```
+
+Three migrations, two deploys minimum. The drizzle schema file:
+
+```ts
+// schema.ts (eventually consistent — reflects the END state)
+export const users = pgTable('users', {
+  id: uuid().primaryKey(),
+  email: text().notNull(),
+  locale: text().notNull(),                       // safe to declare here after step 3
+});
+```
+
+## Pattern: adding an index on a large table
+
+```sql
+-- Generated by drizzle-kit (DO NOT use as-is in prod):
+CREATE INDEX users_org_status_idx ON users (org_id, status);
+
+-- Edit before deploying:
+CREATE INDEX CONCURRENTLY users_org_status_idx ON users (org_id, status);
+```
+
+`CONCURRENTLY` doesn't lock writes. The cost: it can fail mid-creation and leave an INVALID index. Always verify:
+
+```sql
+SELECT indexrelid::regclass AS idx, indisvalid
+FROM pg_index WHERE indexrelid = 'users_org_status_idx'::regclass;
+```
+
+If `indisvalid = false`, drop and recreate.
+
+## Pattern: renaming a column
+
+The naive way (`ALTER TABLE users RENAME COLUMN old TO new`) is one statement but takes an exclusive lock and breaks every running pod still reading `old`.
+
+Safe way (three deploys):
+
+1. **Deploy A**: add `new`, dual-write app code (write both `old` and `new`, read from `old`)
+2. **Backfill**: `UPDATE users SET new = old WHERE new IS NULL`
+3. **Deploy B**: app reads from `new` (still writes both)
+4. **Deploy C**: app stops writing `old`, migration drops `old`
+
+Painful for a rename. That's the cost of zero downtime — most renames are not worth it. Bias toward "keep the old name forever" unless the column is user-facing in an API.
+
+## Pattern: dropping a column
+
+```ts
+// Deploy A: stop reading + writing the column in app code (PR is type-safe — TS removes it from inserts/selects)
+// Deploy B: migration `ALTER TABLE users DROP COLUMN obsolete;`
+```
+
+Two deploys. Never the same release.
+
+## Pattern: adding a foreign key
+
+```sql
+-- Direct ADD CONSTRAINT takes an ACCESS EXCLUSIVE lock to validate every row:
+ALTER TABLE orders ADD CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users(id);
+
+-- Two-step (no exclusive lock):
+ALTER TABLE orders ADD CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users(id) NOT VALID;
+ALTER TABLE orders VALIDATE CONSTRAINT fk_orders_user;
+```
+
+`NOT VALID` adds the constraint for new rows immediately, then `VALIDATE` scans the table without blocking writes.
+
+## Pattern: changing an enum
+
+Postgres enums are awkward to change. Use this checklist:
+
+- **Add a value**: `ALTER TYPE my_enum ADD VALUE 'new_one';` — safe, takes a row-level lock per row touched. On Postgres 12+ you can also `ALTER TYPE my_enum ADD VALUE 'new_one' IF NOT EXISTS` for idempotency.
+- **Rename a value**: `ALTER TYPE my_enum RENAME VALUE 'old' TO 'new';` — Postgres 12+ only. App code must already accept both.
+- **Remove a value**: not supported by Postgres. You must create a new enum, alter the column, drop the old enum. 4+ migrations. Almost never worth it; consider a text column with a CHECK constraint instead.
+
+## Drizzle-specific gotchas
+
+- **`drizzle-kit generate` won't add `CONCURRENTLY` or `NOT VALID`** — always edit the generated SQL.
+- **Schema declarations should match the END state**, not intermediate states. Drizzle infers types from the schema; if you declare `notNull()` before step 3 above, TS thinks the field is always defined while step-1 prod rows still have NULL.
+- **Migration ordering**: `drizzle-kit generate` names migrations by timestamp. Never rename or reorder a migration that has been deployed to staging or prod.
+- **`pgEnum` migrations**: Drizzle generates `CREATE TYPE` once. Re-running `generate` after an enum change can produce broken SQL — verify the diff before commit.
+
+## Workflow
+
+1. **Plan the change** before opening Drizzle Kit. Sketch on paper: this is X migrations, Y deploys.
+2. **Generate**: `pnpm db:generate` (or `bun db:generate`).
+3. **Inspect the SQL** in `drizzle/0042_*.sql`. Edit by hand if needed (CONCURRENTLY, NOT VALID, splitting one migration in two).
+4. **Run staging**: `pnpm db:migrate` against staging DB. Verify schema diff, run perf-sensitive queries, watch lock activity.
+5. **Open PR** with a "Deploy plan" section listing the migration's effect and required app code changes.
+6. **Deploy**: monitor `pg_stat_activity` for blocked queries; abort and rollback if writes back up.
+
+## Applying the migration: who runs `migrate`, and where
+
+Two environments, two owners. Never blur them.
+
+**Dev / local (the agent applies).** When a ticket ships a schema change, the migration must land in the dev/local DB *before* the test passes run — Drizzle infers types from the schema and the integration/E2E suite queries the real tables, so a stale DB either fails spuriously or (worse) passes against the wrong shape.
+
+```bash
+# after `pnpm db:generate` + hand-review of the SQL:
+pnpm db:migrate                                   # local Postgres / pglite
+# or against an ephemeral Neon dev branch (isolated, throwaway):
+neonctl branches create --name dev/$TICKET --parent main
+DATABASE_URL="$(neonctl connection-string dev/$TICKET)" pnpm db:migrate
+# then run the suite against that same DATABASE_URL
+```
+
+A Neon dev branch is the right target when the migration is lock-sensitive or needs realistic row counts (see `void-migrations` lock-impact dry run); pglite/local is enough for small tables. Delete the branch when the ticket lands.
+
+**Production (CI applies, never the agent).** The worker/session stops at a green branch. `drizzle-kit migrate` against prod runs in a gated CI job on merge — a human-approved GitHub Actions step, never a local command and never on push to a feature branch:
+
+```yaml
+# .github/workflows/deploy.yml (excerpt) — runs after review + merge to main
+- name: Apply migrations
+  run: pnpm db:migrate
+  env:
+    DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
+```
+
+This mirrors the `void-migrations` anti-rule "MUST NOT auto-apply migrations on push to main": prod DDL is a deploy decision, not a coding-cycle side effect.
+
+## Composition
+
+- `void-migrations` — generic doctrine (this skill is the Drizzle concretization).
+- `void-server-action` — service code calling the schema must handle nullable-then-not-null gracefully during the intermediate deploy.
+- `void-observability` — log migration start/end with row counts; surface long-running ones in Sentry.
+- `void-async-safety` — backfills that touch >100k rows should batch (LIMIT + LOOP), not one statement.

package/core-assets/packs/pack-server/skills/void-drizzle-migration-safe/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-server/skills/void-env-validation/.source

@@ -0,0 +1,6 @@
+Sources for `void-env-validation` skill (see `docs/plans/skill-audits/void-env-validation.md` for the full audit):
+
+- No external source audited — native distillation of the @repo/core/env pattern (Zod-validated, fail-at-boot).
+- Tooling referenced (not vendored): Zod, the per-runtime split (Node / Edge / browser) and NEXT_PUBLIC_* convention.
+
+Strategy: native. Authored for void-machine from the @repo/core/env pattern; no upstream skill was copied.

package/core-assets/packs/pack-server/skills/void-env-validation/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: void-env-validation
+description: Validate environment variables at boot via Zod in @repo/core/env. Separate PUBLIC (NEXT_PUBLIC_*) from server-only. Fail fast at startup; never raw process.env in business code.
+---
+
+# env-validation
+
+Use when adding any new environment variable, or when working in a project that doesn't yet have `@repo/core/env`. Env vars are an invisible trust boundary — they're inputs from outside the process, and "the database URL is undefined" should explode at boot, not at the first query.
+
+This skill is the void-machine operational form. Composes with `void-security-guidance` (env doctrine) and enforced by the `no-process-env-in-app` hook.
+
+## The principle
+
+```
+process.env.X        →   used ONLY inside @repo/core/env
+import { env } from '@repo/core'  →   used everywhere else
+```
+
+`@repo/core/env` parses + validates `process.env` ONCE, exposes a typed object. Any business code reading `process.env` directly is forbidden (enforced by the `no-process-env-in-app` hook).
+
+## The schema
+
+```ts
+// packages/core/src/env.ts
+import { z } from 'zod';
+
+const ServerSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  DATABASE_URL: z.string().url(),
+  STRIPE_SECRET_KEY: z.string().regex(/^sk_(test|live)_/),
+  STRIPE_WEBHOOK_SECRET: z.string().min(10),
+  SENTRY_DSN: z.string().url().optional(),
+  OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
+});
+
+const ClientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_SENTRY_DSN: z.string().url().optional(),
+});
+
+function parseEnv() {
+  const isServer = typeof window === 'undefined';
+  const server = isServer ? ServerSchema.parse(process.env) : ({} as z.infer<typeof ServerSchema>);
+  const client = ClientSchema.parse({
+    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+    NEXT_PUBLIC_SENTRY_DSN: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  });
+  return { ...client, ...server };
+}
+
+export const env = parseEnv();
+export type Env = typeof env;
+```
+
+Three rules in this file:
+
+1. **Server schema parsed only on server** (`typeof window === 'undefined'`). Otherwise the client bundle would include the server schema, leak field names + (worse) attempt to parse missing values.
+2. **Client schema parsed both sides**, but Client schema only reads `NEXT_PUBLIC_*`. Anything else is a leak.
+3. **Throws at module-load if missing/invalid.** This is intentional. App fails to boot rather than crash mid-request.
+
+## Per-runtime sanity
+
+| Runtime | What's available | What env reads |
+|---|---|---|
+| Node server | Full `process.env` | Server + Client schemas |
+| Edge runtime | Subset (only NEXT_PUBLIC_*  + a few injected) | Server schema may fail — exclude server-only vars from edge routes |
+| Browser | Only NEXT_PUBLIC_* + Next-injected | Client schema only |
+
+If a server-only variable is read in an Edge route, the import chain pulls in the server schema, which fails on Edge (no `process.env.DATABASE_URL`). Solution: import `env` granularly:
+
+```ts
+// Edge-safe — explicit imports
+import { env } from '@repo/core/env-client';
+// Server-only
+import { env } from '@repo/core/env-server';
+```
+
+Or split into `env-client.ts` and `env-server.ts` exports if your stack needs Edge support.
+
+## Naming convention
+
+- `NEXT_PUBLIC_*` for browser-visible (Next.js convention; baked into the bundle at build time)
+- `<DOMAIN>_<NAME>` for server-only (e.g., `STRIPE_SECRET_KEY`, not `SECRET_KEY`)
+- Never use single-word ambiguous names (`API_KEY` — for what?)
+
+## The `.env.example` discipline
+
+Every env added to the schema MUST be added to `.env.example` (committed):
+
+```bash
+# .env.example
+DATABASE_URL=postgresql://user:pass@localhost:5432/dev
+STRIPE_SECRET_KEY=sk_test_REPLACE_ME
+STRIPE_WEBHOOK_SECRET=whsec_REPLACE_ME
+SENTRY_DSN=                         # optional
+```
+
+New developer clones → `cp .env.example .env` → fill values → boot. If `.env.example` is incomplete, onboarding breaks for 30 minutes per dev.
+
+## What goes in `.env` vs secrets manager
+
+- `.env.local` (gitignored): local dev secrets, test keys, dev DB
+- Vercel/Doppler/etc. env settings: staging + production secrets
+- Never commit `.env` (only `.env.example`)
+
+## Anti-patterns
+
+- ✗ **`process.env.STRIPE_KEY ?? 'default'`** — silent fallback hides config errors; the schema's `.parse` would throw correctly
+- ✗ **`process.env.STRIPE_KEY!` (non-null assertion)** — bypasses TS type system; if missing at runtime, you get a useless undefined error mid-request instead of a clear schema error at boot
+- ✗ **NEXT_PUBLIC for secrets** — anything `NEXT_PUBLIC_*` is in the bundle and visible to anyone
+- ✗ **Server-only env imported in a Client Component** — caught at build time, but the import chain matters: keep `env-server` imports out of `'use client'` files
+- ✗ **Optional everywhere** — if it's optional, the code must handle absence. If the code crashes when absent, it was actually required → mark as required in the schema
+
+## Verification
+
+In dev, simulate missing env:
+
+```bash
+DATABASE_URL= bun run dev
+# Expected: app fails to start with Zod's error showing which field
+```
+
+If app starts and crashes later, your schema isn't comprehensive — find the missed import or non-null assertion.
+
+## Composition
+
+- `void-security-guidance` — env-as-trust-boundary doctrine.
+- `void-server-action` — actions import `env`, never `process.env`.
+- `void-webhook-handler-pattern` — webhook secrets pulled from `env`.
+- `void-instrumentation-setup` — Sentry/OTel DSN from `env`.
+- `no-process-env-in-app` hook (harness-server) — blocks `process.env.X` in `apps/*/src/` files outside the env module itself.

package/core-assets/packs/pack-server/skills/void-env-validation/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-server/skills/void-rate-limit-strategy/.source

@@ -0,0 +1,6 @@
+Sources for `void-rate-limit-strategy` skill (see `docs/plans/skill-audits/void-rate-limit-strategy.md` for the full audit):
+
+- No external source audited — native distillation of the void-machine rate-limit presets per action class.
+- Doctrine referenced (not vendored): `void-security-guidance` ("rate limit at every boundary"); this skill supplies the HOW (window / max / key).
+
+Strategy: native. Presets and key strategies authored for void-machine; no upstream skill was copied.