thevoidforge 21.0.11 → 21.0.12

package/dist/docs/methods/TREASURY.md

@@ -0,0 +1,184 @@
+# THE TREASURY — Dockson's Financial Operations
+## Lead Agent: **Dockson** (The Bookkeeper, Mistborn) · Sub-agents: Cosmere Universe
+
+> *"Every coin has a story. I know them all."*
+
+## Identity
+
+**Dockson** is Kelsier's right hand for logistics and money. Every transaction logged, every penny accounted for. The vault is his domain. He manages the bridge between revenue flowing in (Stripe, Paddle) and spend flowing out (ad platforms). The heartbeat daemon is his engine; the reconciliation report is his ledger.
+
+**Behavioral directives:** Never lose a transaction. Never spend without authorization. Reconcile daily — if the numbers don't match, investigate before acting. The immutable spend log is sacred — append only, never rewrite. Integer cents, never floats. Platform-level caps as safety net. Two-key architecture (vault + TOTP) for all write operations. Read-only is free; writing costs verification.
+
+## Sub-Agent Roster
+
+| Agent | Name | Role | Lens |
+|-------|------|------|------|
+| Budget | **Steris** | Budget allocation, forecasting, contingency | 47 contingency plans. Forecasts based on data. |
+| Revenue | **Vin** | Revenue tracking, analytics, attribution | Sees through disguises. Traces conversions. |
+| Compliance | **Szeth** | Financial compliance, tax records, platform ToS | Bound by law. No exceptions. |
+| Platform | **Breeze** | API credentials, platform relations | Navigates platform politics. |
+
+## Operating Rules
+
+1. **Read revenue, never process payments.** Stripe/Paddle are the processors. VoidForge reads.
+2. **Integer cents.** All amounts use the `Cents` branded type. Never float.
+3. **Append-only logs.** Spend-log and revenue-log are immutable. Hash-chained per entry.
+4. **Single writer.** The heartbeat daemon owns all financial state mutations (ADR-1).
+5. **Two-key for writes.** Vault password + TOTP for campaign creation, budget changes, unfreeze.
+6. **USD only in v11.x.** Non-USD currencies blocked with user message (ADR-6).
+7. **Platform caps.** Set platform-level daily budget 10% below VoidForge hard stop.
+8. **Reconcile daily.** Two-pass: preliminary at midnight UTC, authoritative at 06:00 UTC.
+
+## Pre-Revenue Setup
+
+For projects that don't yet have revenue (pre-launch, MVP, side projects), Treasury still provides value:
+
+1. **Budget tracking from day 0:** Even without revenue, track ad spend against a manual budget. Know exactly how much you've invested before the first dollar returns.
+2. **Revenue source auto-detection:** During `/cultivation install`, scan the project for payment processor integrations:
+   - `stripe` in package.json/requirements.txt → offer to connect Stripe read-only key
+   - `STRIPE_SECRET_KEY` in .env or vault → Stripe is already configured
+   - `paddle` dependency → offer Paddle connection
+   - No payment processor found → "Revenue tracking will activate when you add a payment processor. Treasury tracks spend in the meantime."
+3. **Circuit breakers without revenue:** Set absolute spend limits (not ROAS-based, since there's no revenue to compare). Example: "Pause all campaigns if total spend exceeds $500 this month." ROAS-based circuit breakers activate automatically once the first revenue event is recorded.
+4. **Reconciliation still runs:** The heartbeat daemon reconciles spend even without revenue. This means the spend log is accurate from day 0, and when revenue starts flowing, the historical spend data is already there for ROAS calculation.
+
+**The principle:** Treasury should never block on "no revenue yet." The spend side works independently. The revenue side activates when data appears. (Field report #131)
+
+## Revenue Ingest
+
+| Source | Auth | Data | Frequency |
+|--------|------|------|-----------|
+| Stripe | Restricted API key (read-only) | Charges, subscriptions, refunds, disputes | Hourly poll + daily reconciliation (ADR-5) |
+| Paddle | API key (read-only) | Transactions, subscriptions, refunds | Hourly poll + daily reconciliation |
+| Mercury | OAuth 2.0 (read-only) | Balance, transactions | Hourly poll (v11.3) |
+| Brex | OAuth 2.0 (read-only) | Card transactions, balance | Hourly poll (v11.3) |
+
+**Polling with overlap (§9.18):** Each poll fetches `(lastPollTime - 5 minutes)` to `now`. Dedup by `externalId`.
+
+## Budget Allocation
+
+```
+Total Monthly Budget: $X (set by user)
+├── Platform Allocations (Steris recommends)
+├── Safety Controls
+│   ├── Daily hard stop: $N (platform-enforced)
+│   ├── Weekly soft limit: $N (alert, no auto-stop)
+│   └── Monthly ceiling: $N (hard stop, all paused)
+└── Approval Tiers (§9.17)
+    ├── <$25/day:  auto-approve (ongoing spend only)
+    ├── $25-100/day: agent approval (Dockson + Steris)
+    ├── >$100/day: human confirmation + TOTP
+    └── >$500/day: hard stop + TOTP + vault password
+```
+
+## Reconciliation
+
+Daily two-pass reconciliation (§9.17):
+1. **Preliminary** (midnight UTC): for dashboard freshness
+2. **Authoritative** (06:00 UTC): 6 hours for platform reporting to settle. Alerts only on final pass.
+
+**Thresholds:** Ignore <$5 (timing noise). Alert on >max($5, 5%). Always alert on >$50 absolute. Trend detection: consistent 3-4% discrepancy over 7 days.
+
+## Safety Controls
+
+**`/treasury --freeze`:** Immediately pauses all automated spending. Does NOT delete campaigns. Low friction (session token only, no TOTP). Sends Telegram alert. See §9.18 partial freeze protocol for per-platform failure handling.
+
+**Immutable spend log:** Append-only JSONL at `~/.voidforge/treasury/spend-log.jsonl`. Hash-chained. Never rewritten. Used for reconciliation, tax reporting, and audit trail.
+
+## Commands
+
+| Flag | What It Does |
+|------|-------------|
+| `setup` | First-time setup: connect revenue sources, TOTP 2FA |
+| `--status` | Show financial summary (revenue, spend, net, ROAS) |
+| `--freeze` | Emergency: pause all automated spending |
+| `--unfreeze` | Resume spending (requires vault + TOTP) |
+| `--budget N` | Set total monthly budget |
+| `--reconcile` | Trigger manual reconciliation |
+| `--report` | Generate monthly report (JSON/CSV/markdown) |
+| `--launch [file]` | Launch campaigns from growth-campaigns.json |
+| `--hard-stop N` | Set daily hard stop amount |
+| `--export [path]` | Export all financial data (encrypted) |
+
+## Stablecoin Funding Rail
+
+### Overview
+
+Treasury supports a first-class stablecoin-funded path for ad spend:
+
+**USDC wallet/provider → Circle off-ramp → Mercury USD account → Google/Meta billing rail → campaign spend**
+
+This does not pay Google or Meta in crypto directly. It converts approved stablecoin balances into compliant fiat rails, then keeps ad billing systems funded, monitored, and reconciled. The stablecoin treasury adapter and ad billing adapter are separate concerns from the campaign CRUD adapter — billing and campaign management never share an interface.
+
+### Stablecoin Treasury Commands
+
+| Flag | What It Does |
+|------|-------------|
+| `setup --crypto` | First-time stablecoin funding setup: provider, destination bank, mode, thresholds, TOTP |
+| `--balances` | Show stablecoin source balance, bank available balance, reserved balance, and platform runway |
+| `--funding-status` | Show end-to-end funding chain: pending off-ramps, unsettled invoices, expected debits, freeze state |
+| `--offramp --amount N` | Initiate off-ramp of $N from stablecoin provider to destination bank (requires vault + TOTP) |
+| `--target-balance N` | Set minimum USD operating balance target at destination bank |
+| `--runway` | Forecast days of runway based on projected campaign spend vs available fiat |
+| `--invoice-pay [platform] [invoice-id]` | Settle a specific platform invoice (requires vault + TOTP) |
+| `--reconcile` | Trigger manual reconciliation across stablecoin transfers, bank settlements, and platform spend |
+| `--simulate-funding` | Dry-run: show projected 14-day spend, required float, recommended off-ramp, settlement lead time, freeze triggers |
+
+### Funding Modes
+
+**Maintain buffer (recommended):** Keep a minimum USD operating balance at the destination bank. When projected runway drops below the configured threshold, Heartbeat generates a funding plan to off-ramp stablecoins and replenish the buffer. Suitable for steady-state spend with predictable billing cycles.
+
+**Just-in-time funding:** Off-ramp only when a specific obligation is imminent (invoice due, debit expected, runway below hard floor). Minimizes idle fiat but increases settlement timing risk. Requires tighter monitoring and shorter off-ramp SLA expectations.
+
+### Circuit Breakers
+
+Freeze all autonomous funding if any of the following occur:
+
+1. **Provider unavailable:** Stablecoin provider unreachable for 3 consecutive polls
+2. **Off-ramp stalled:** Off-ramp transfer pending beyond the defined SLA window
+3. **Reconciliation mismatch:** Reconciliation variance exceeds threshold for 2 consecutive daily closes
+4. **Invoice deadline risk:** Google invoice due within N hours and available fiat below hard floor
+5. **Platform payment failure:** Meta direct debit fails or account enters payment-risk state
+6. **Daily movement cap exceeded:** User-defined maximum daily treasury movement breached
+
+When a circuit breaker trips, the system freezes spend increases and new off-ramps but allows read-only monitoring and campaign intelligence to continue. `/treasury --unfreeze` requires vault + TOTP.
+
+### Authorization Model
+
+**Read-only operations** (standard active vault session):
+- Read stablecoin balances and bank balances
+- Read platform spend and invoices/debits
+- Forecast runway
+- Generate funding recommendations
+- Run `--simulate-funding`
+
+**Write operations** (vault password + TOTP):
+- Initiate off-ramp (`--offramp`)
+- Settle invoice (`--invoice-pay`)
+- Modify budget ceiling
+- Unfreeze funding (`--unfreeze`)
+- Change destination bank
+- Add new funding provider
+
+All write operations require idempotency keys, append to the immutable financial log, and respect the explicit payee/destination allowlist.
+
+### Reconciliation
+
+Daily two-pass reconciliation applies to stablecoin-funded projects:
+
+1. **Preliminary close (midnight UTC):** Read ad platform spend, bank settlement activity, and provider transfer completion state. Compare against planned funding amounts. Write reconciliation record. Surface mismatch severity in the Danger Room.
+2. **Authoritative close (06:00 UTC):** Re-read all sources after 6 hours of settlement lag. Alerts fire only on this pass. Persistent mismatches trigger the reconciliation circuit breaker.
+
+Stablecoin reconciliation links three layers: provider transfer records, bank transaction records, and platform spend/invoice/debit records. Each reconciliation record captures `spendCents`, `bankSettledCents`, `invoiceCents`, `varianceCents`, and a result of `MATCHED`, `WITHIN_THRESHOLD`, or `MISMATCH`.
+
+## Deliverables
+
+1. Revenue adapters (Stripe, Paddle — read-only, polling)
+2. Spend-log + revenue-log (append-only, hash-chained)
+3. Reconciliation engine (two-pass)
+4. Budget management (allocation, safety tiers)
+5. Treasury tab in Danger Room
+6. Monthly/weekly financial reports
+7. Stablecoin treasury adapter (Circle primary, Bridge secondary)
+8. Ad billing adapter (Google invoicing, Meta direct debit / extended credit)
+9. Funding planner and settlement lifecycle tracking

package/dist/docs/methods/TROUBLESHOOTING.md

@@ -0,0 +1,265 @@
+# TROUBLESHOOTING — Error Recovery & Common Failures
+## System Protocol · Used by: All Agents
+
+> *When a build phase fails, when a migration breaks, when nothing makes sense — start here.*
+
+## Philosophy
+
+1. Diagnose before you fix. Understand the root cause.
+2. Check the obvious first. Most failures are typos, missing env vars, or wrong versions.
+3. Isolate the layer. Is it code, config, database, dependency, or infrastructure?
+4. Don't stack fixes. Fix one thing, verify, then move to the next.
+5. If you're going in circles, stop and re-read the error message literally.
+
+## Step 0 — What Changed?
+
+Before forming any hypothesis, establish what actually changed since the last known-good state:
+
+1. `git diff HEAD~3` — scan the last 3 commits for the change that correlates with the symptom
+2. `git log --oneline -10` — read recent commit messages for anything related to the failing area
+3. Check environment: were env vars, dependencies, or infrastructure changed? (`git diff package-lock.json`, check deploy logs)
+4. Check external factors: did a third-party API change? Did a DNS record expire? Did a certificate rotate?
+
+**Rule:** If the answer to "what changed?" is "nothing" — something changed that you don't know about. Widen the search: OS updates, CI runner version, provider outage, certificate expiry.
+
+Only after establishing what changed should you form a hypothesis about WHY it broke.
+
+## Hypothesis Invalidation
+
+When you have a theory about the root cause, try to DISPROVE it before acting on it:
+
+1. **State your hypothesis explicitly:** "I think X is broken because Y."
+2. **Find evidence that would contradict it:** If X were NOT the cause, what would you expect to see? Check for that.
+3. **Only act when you cannot disprove:** If you can't find contradicting evidence after a genuine attempt, proceed with the fix.
+
+**Anti-pattern:** "The database might be slow" → immediately add indexes. **Correct:** "The database might be slow" → check query execution times → if queries are fast, the database is not the problem → look elsewhere.
+
+This prevents fix-stacking: applying multiple speculative fixes where only one (or none) was needed. (Field reports #271, #275)
+
+---
+
+## Build Phase Failures
+
+### Phase 0 (Orient) — PRD is incomplete or ambiguous
+
+**Symptoms:** Can't extract tech stack, missing schema, vague feature descriptions.
+
+**Recovery:**
+1. List every gap in the PRD explicitly
+2. Flag assumptions you'd need to make
+3. If using PRD_GENERATOR.md, re-run with more specific input
+4. For missing schema: derive it from the feature descriptions, mark as "inferred — confirm"
+5. For missing stack: pick sensible defaults (Next.js + Prisma + Postgres) and note the assumption
+
+### Phase 1 (Scaffold) — Framework won't initialize
+
+**Symptoms:** `create-next-app` fails, wrong Node version, dependency conflicts.
+
+**Recovery:**
+1. Check Node version: `node -v` (use the version the framework expects)
+2. Clear package caches: `npm cache clean --force`
+3. Delete `node_modules` and `package-lock.json`, reinstall
+4. If a specific dependency conflicts, pin the version that works
+5. Check if the framework's latest version has breaking changes — pin a stable version
+
+### Phase 2 (Infrastructure) — Database won't connect
+
+**Symptoms:** Connection refused, auth failed, migration errors.
+
+**Recovery:**
+1. Is the database running? `pg_isready` / `redis-cli ping`
+2. Check connection string in `.env` — host, port, user, password, database name
+3. Can you connect manually? `psql $DATABASE_URL`
+4. For migration failures: check if the database exists, create it if not
+5. For Prisma: `npx prisma db push` for rapid iteration, `npx prisma migrate dev` for proper migrations
+6. Nuclear option: `npx prisma migrate reset` (destroys data — dev only)
+
+### Phase 3 (Auth) — Auth flow broken
+
+**Symptoms:** Login fails silently, sessions don't persist, OAuth redirect errors.
+
+**Recovery:**
+1. Check cookies: httpOnly, secure (requires HTTPS in prod), sameSite, domain, path
+2. Check session store: is Redis running? Is the connection configured?
+3. OAuth: verify redirect URIs match exactly (trailing slashes matter)
+4. OAuth: verify client ID and secret are correct and for the right environment
+5. Check CORS: is your frontend origin allowed?
+6. Check CSRF: is the token being sent with mutations?
+7. Test with `curl` to eliminate frontend issues
+
+### Phase 4-5 (Features) — API returns wrong data or 500s
+
+**Symptoms:** Unexpected response shape, internal server errors, data not persisting.
+
+**Recovery:**
+1. Read the actual error — check server logs, not just the HTTP status
+2. Test the endpoint with `curl` to isolate frontend vs backend
+3. Check database: is the data there? `npx prisma studio`
+4. Check types: is the Prisma client generated? `npx prisma generate`
+5. Check middleware order: auth before route handlers, error handler last
+6. For 500s: add try/catch with logging to the specific route
+
+### Phase 6 (Integrations) — Third-party API failures
+
+**Symptoms:** Stripe/email/storage not working, webhook not received.
+
+**Recovery:**
+1. Verify API keys are set and for the right environment (test vs live)
+2. Test the API call in isolation (curl or Postman)
+3. Check webhook URL: is it publicly accessible? Use ngrok for local dev
+4. Check webhook signature verification: is the signing secret correct?
+5. For Stripe: use `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
+6. For email: check SMTP credentials, sender domain, SPF/DKIM records
+7. Rate limits: have you exceeded the API's rate limit?
+
+### Phase 9-11 (QA/UX/Security) — Too many issues found
+
+**Symptoms:** Audit produces 50+ issues, unclear where to start.
+
+**Recovery:**
+1. Triage by severity: Critical (security, data loss) → High (broken flows) → Medium → Low
+2. Group by area: fix all issues in one file/component together
+3. Fix critical issues first, then re-run the audit
+4. Don't fix low-severity issues if they risk introducing regressions
+5. Track "won't fix" items with rationale
+
+### Phase 12 (Deploy) — Deployment fails
+
+**Symptoms:** Build fails on server, app won't start, health check fails.
+
+**Recovery:**
+1. Build locally first: `npm run build` — if it fails locally, fix before deploying
+2. Check Node version on server matches local
+3. Check environment variables are set on the server
+4. Check file permissions: can the app user read the files?
+5. Check ports: is something else running on the port?
+6. Check logs: `pm2 logs` or `journalctl -u your-app`
+7. Memory: is the server running out? Check `free -h`
+8. Rollback: use `/scripts/rollback.sh` and diagnose from a working state
+
+### Post-Deploy Debugging Protocol
+
+When the app is deployed and running but producing incorrect behavior, check causes in this order — simplest first:
+
+1. **Wrong environment:** Are you hitting the right server? Check the URL, DNS, and load balancer target.
+2. **Stale deploy:** Is the running code actually the latest? Check build timestamp, version endpoint, or deployment log.
+3. **Missing/wrong env vars:** Compare expected env vars against what's actually set on the server. One missing var can cascade.
+4. **Database state:** Is the migration current? Is there stale data from a previous deploy? Check schema version.
+5. **Dependency mismatch:** Does the server have the same dependency versions as local? Check lock file deployment.
+6. **Cache poisoning:** Is a CDN, Redis, or browser cache serving stale content? Clear and retest.
+7. **External service change:** Did a third-party API change behavior, rate limit you, or rotate credentials?
+8. **Actual code bug:** Only after eliminating 1-7 should you assume the code itself is wrong.
+
+**Rule:** Items 1-7 account for ~80% of post-deploy issues. Starting at item 8 wastes hours. (Field reports #271, #275)
+
+### Phase Rollback — A batch broke something
+
+**Symptoms:** A feature batch introduces a regression in a previous flow.
+
+**Recovery (the rollback protocol):**
+1. **Identify:** Which commit/batch introduced the regression? `git log --oneline -10`
+2. **Revert:** `git revert <commit-hash>` (or `git stash` if uncommitted)
+3. **Verify:** Confirm the regression is gone — run `npm test`, walk through the affected flow
+4. **Isolate:** In the reverted code, identify the specific change that caused the conflict
+5. **Fix:** Apply the fix in isolation, verify it doesn't break the original or the new feature
+6. **Re-apply:** Re-introduce the batch with the fix included, verify everything
+7. **Log:** Document in `/logs/errors.md`: what broke, root cause, resolution
+
+**Never:** Stack untested changes hoping the next batch will fix it. Force through a failing gate. Skip the revert and try to fix forward in a complex codebase.
+
+---
+
+## Common Deployment Issues
+
+### Never build on a running production server
+Running `npm run build` (or `npx next build`, `bundle exec rails assets:precompile`, etc.) on a server actively serving traffic replaces compiled assets (`.next/`, `dist/`, `public/assets/`) while the process manager serves old HTML referencing old chunk hashes. Result: all client JS 404s, blank pages. **Always stop the server, build, then restart.** Or better: build on a separate machine and deploy the artifact. (Field report #149)
+
+---
+
+## Common Cross-Phase Failures
+
+### Static asset returns text/html
+
+The hosting platform is serving the SPA fallback (index.html) because the file doesn't exist in the deployment. This is NOT a CDN cache issue — cache lag serves stale versions of the correct file, not a different file entirely. Check: (1) Was the file included in the deploy? (2) Was the deploy targeted at the correct environment? (3) Did the build step generate the file? (Field report #114: favicon.svg returned text/html because it was deployed to the wrong Vercel environment.)
+
+### TypeScript won't compile
+
+1. `npx tsc --noEmit` — read the first error, fix it, repeat
+2. Missing types: `npm i -D @types/package-name`
+3. Prisma types stale: `npx prisma generate`
+4. Circular imports: refactor shared types to a separate file
+5. `any` creeping in: fix the type, don't suppress it
+
+### Dependency conflicts
+
+1. Read the conflict: which packages want different versions of what?
+2. Check if one of the conflicting packages has an update
+3. Use `npm ls package-name` to see the dependency tree
+4. Last resort: `overrides` in package.json to force a version
+
+### Git state is messy
+
+1. Check what changed: `git status`, `git diff`
+2. Stash work: `git stash` before switching context
+3. Wrong branch: `git stash && git checkout correct-branch && git stash pop`
+4. Need to undo last commit (not pushed): `git reset --soft HEAD~1`
+5. File shouldn't be tracked: add to `.gitignore`, `git rm --cached filename`
+
+### Tailwind v4 Utilities Not Generating
+
+**Symptoms:** CSS builds locally but fails on Vercel/Cloudflare with PostCSS syntax errors. Or: Tailwind classes have no effect in production.
+
+**Cause:** Tailwind v4 auto-scans ALL files for class names by default. Non-source files (`.md`, docs, logs) can trigger invalid CSS generation. Or: `postcss.config.mjs` is missing.
+
+**Fix:** (1) Create `postcss.config.mjs` with `{ plugins: { "@tailwindcss/postcss": {} } }`. (2) Add `@import "tailwindcss" source("../..") to the top of your CSS entry point to limit scanning to source directories. (3) Pin Node.js version in `.node-version` — `@tailwindcss/postcss` has ESM bugs on Node 24.
+
+### Environment mismatch (works locally, fails in prod)
+
+1. Compare env vars: local `.env` vs server environment
+2. Check Node version: local vs server
+3. Check database: local schema vs prod schema (run migrations)
+4. Check URLs: localhost references that should be production URLs
+5. Check CORS: is the production frontend origin allowed?
+
+### Memory/performance issues
+
+1. Node running out of memory: `NODE_OPTIONS="--max-old-space-size=4096"`
+2. Database queries slow: check for N+1, missing indexes, unneeded fields
+3. Build too slow: check for large dependencies, unnecessary imports
+4. Runtime memory leak: check for unclosed connections, growing arrays, event listener accumulation
+
+---
+
+## When to Escalate
+
+| Symptom | Escalate to |
+|---------|------------|
+| "I've tried 3 approaches and none work" | Re-read the error message literally. Then ask: is the approach fundamentally wrong? |
+| Architecture seems wrong for the requirements | **Picard** — may need an ADR and structural change |
+| Security concern blocking a feature | **Kenobi** — security wins, but there may be a safe alternative |
+| Infrastructure limitation | **Kusanagi** — may need different hosting or configuration |
+| Feature requirement unclear | Go back to the PRD. If the PRD is ambiguous, flag it explicitly. |
+
+---
+
+## Recovery Checklist
+
+After resolving any significant failure:
+
+- [ ] Root cause identified and documented
+- [ ] Fix applied and verified
+- [ ] No regressions introduced (check related flows)
+- [ ] If the failure can recur, add a guard (validation, test, monitoring)
+- [ ] Update `/docs/LESSONS.md` if the pattern is new
+- [ ] Update `/docs/qa-prompt.md` if it affects a critical flow
+
+### Before Any Destructive Database Operation
+
+Before clearing, deleting, or modifying database fields to "fix" missing files or broken state:
+1. **Can data be restored from backup?** Check `~/.voidforge/backups/`, `pg_dump` snapshots, platform export tools.
+2. **Can files be re-downloaded or re-generated without cost?** Check if the source is a free API or a paid service (DALL-E, CDN, etc.).
+3. **Is the DB change reversible?** Clearing a field is often irreversible — the original value is gone.
+4. **What is the regeneration cost?** Count: API calls × price per call. Time to regenerate.
+5. **NEVER clear a DB field to work around a missing file.** Restore the file first, or confirm the regeneration cost is acceptable BEFORE deleting the reference.
+
+(Field report #103: 251 avatarUrl fields cleared to "fix" missing files, triggering ~$10 in DALL-E regeneration + 50 minutes downtime. The files existed on the VPS — they were deleted by `rsync --delete`, not lost. Restoring from backup would have been free.)

package/dist/docs/patterns/README.md

@@ -0,0 +1,52 @@
+# Code Patterns
+
+Reference implementations for common code structures. These show the **shape and principles** — adapt to your project's stack and conventions. All patterns include framework adaptation notes.
+
+| Pattern | File | When to Reference | Frameworks Shown |
+|---------|------|------------------|-----------------|
+| API Route | `api-route.ts` | Building any API endpoint | Next.js (Express/Django/Rails notes) |
+| Service Layer | `service.ts` | Writing business logic | Next.js + Prisma (Django/Rails notes) |
+| Component | `component.tsx` | Building UI components | React (Vue/Svelte/server-template notes) |
+| Middleware | `middleware.ts` | Auth, logging, rate limiting | Next.js (Express/Django/Rails notes) |
+| Error Handling | `error-handling.ts` | Canonical error strategy | Next.js + Express + Django + Rails |
+| Job Queue | `job-queue.ts` | Background jobs, async work | BullMQ + Celery + Sidekiq |
+| Multi-Tenant | `multi-tenant.ts` | Workspace/org scoping | Next.js + Django + Rails |
+| Third-Party Script | `third-party-script.ts` | Loading external scripts (3 states) | Browser |
+| Mobile Screen | `mobile-screen.tsx` | React Native screen with safe area, a11y | React Native |
+| Mobile Service | `mobile-service.ts` | Offline-first data with sync queue | React Native |
+| Game Loop | `game-loop.ts` | Fixed timestep with interpolation | Phaser/Three.js/Pixi |
+| Game State | `game-state.ts` | Hierarchical state machine with save/load | Any game engine |
+| Game Entity | `game-entity.ts` | Entity Component System | Any game engine |
+| SSE Endpoint | `sse-endpoint.ts` | Server-Sent Events with lifecycle | Express/FastAPI/Django |
+| Ad Platform Adapter | `ad-platform-adapter.ts` | Split setup/runtime/readonly interfaces | Google/Meta/LinkedIn/Twitter |
+| Financial Transaction | `financial-transaction.ts` | Branded Cents, hash-chained log, atomic writes | Any |
+| Daemon Process | `daemon-process.ts` | PID management, Unix socket, signal handling | Node.js |
+| Revenue Source Adapter | `revenue-source-adapter.ts` | Read-only revenue interface | Stripe/Paddle |
+| OAuth Token Lifecycle | `oauth-token-lifecycle.ts` | Refresh at 80% TTL, vault integration | Any OAuth provider |
+| Outbound Rate Limiter | `outbound-rate-limiter.ts` | Safety margins, daily quotas, retry logic | Any API client |
+| AI Orchestrator | `ai-orchestrator.ts` | Agent loops, tool use, retry, circuit breaker | Anthropic SDK (OpenAI notes) |
+| AI Classifier | `ai-classifier.ts` | Classification with confidence thresholds, fallback chains | Anthropic SDK (OpenAI notes) |
+| AI Router | `ai-router.ts` | Intent-based routing with fallback chains | Anthropic SDK (OpenAI notes) |
+| Prompt Template | `prompt-template.ts` | Versioned prompts, variable injection, guardrails | Any (provider-agnostic) |
+| AI Eval | `ai-eval.ts` | Golden datasets, scoring functions, regression detection | Any (provider-agnostic) |
+| AI Tool Schema | `ai-tool-schema.ts` | Typed tool definitions, provider adapters | Anthropic + OpenAI |
+| Database Migration | `database-migration.ts` | Safe migrations: backward-compat, batched ops, rollback, zero-downtime | Prisma, Alembic, ActiveRecord, Django |
+| Data Pipeline | `data-pipeline.ts` | ETL with checkpoint/resume, quality checks, idempotent processing | Node.js streams, Python polars, SQL/dbt |
+| Backtest Engine | `backtest-engine.ts` | Walk-forward validation, no-lookahead, Sharpe/drawdown metrics | Python vectorbt/backtrader |
+| Execution Safety | `execution-safety.ts` | Order validation, position limits, exchange precision, paper/live toggle | CCXT, Alpaca, IBKR |
+
+## How to Use
+
+1. Read the relevant pattern before writing new code in that category
+2. Match the structure (validation, error handling, response format, all states)
+3. Adapt to your stack — the pattern shows the *shape*, your code fills in the specifics
+4. All patterns include comments noting the framework-specific equivalent
+
+## Adding New Patterns
+
+When you discover a pattern that should be standardized:
+
+1. Create a new file in this directory
+2. Include: purpose comment, the pattern, inline notes, framework adaptations
+3. Add it to the table above
+4. Reference it in the relevant method doc