thevoidforge 21.0.11 → 21.0.12

package/dist/.claude/commands/review.md

@@ -0,0 +1,151 @@
+# /review — Picard's Code Review
+
+> Pattern compliance, code quality, and maintainability review. Picard-affiliated (Star Trek).
+
+## Context Setup
+1. Read `/logs/build-state.md` — understand current project state
+2. Read the relevant pattern files from `/docs/patterns/` for the code being reviewed
+3. Read `/docs/LESSONS.md` — check for review-relevant lessons (integration tracing gaps, render loops, cross-module issues). Flag matches during review.
+
+## Step 0 — Scope
+Determine what to review:
+- If `$ARGUMENTS` specifies files/directories, review those
+- If no arguments, review all changed files since last commit: `git diff --name-only HEAD~1`
+- If reviewing a feature branch: `git diff --name-only main...HEAD`
+
+List all files in scope and their types (API route, service, component, middleware, config).
+
+## Agent Deployment Manifest
+
+**Lead:** Picard (Star Trek) — architecture lens, final arbiter
+**Core team (always deployed):**
+- **Spock** — pattern compliance + integration tracing
+- **Seven** — code quality, dead code, complexity
+- **Data** — maintainability, error paths, state flow
+
+**Stark's Marvel team (deployed on backend-heavy reviews):**
+- **Rogers** — API design: HTTP semantics, consistent response shapes, REST conventions
+- **Banner** — database: query patterns, N+1, missing indexes, schema concerns
+- **Strange** — service architecture: separation of concerns, business logic placement
+- **Barton** — error handling: try/catch completeness, error propagation, user-facing messages
+- **Romanoff** — security implications in reviewed code (lightweight — flags for Kenobi, doesn't audit)
+- **Thor** — performance: unnecessary re-renders, expensive computations, missing memoization
+- **Wanda** — state management: store design, prop drilling, context boundaries
+- **T'Challa** — API integration: external service calls, retry logic, fallback behavior
+
+**Cross-domain agents (deployed based on content):**
+- **Nightwing** (DC) — auth flow end-to-end: when auth code is in scope, trace signup→verify→login→protected→logout
+- **Bilbo** (Tolkien) — copy audit: error messages, UI text, API response descriptions — are they clear and human?
+- **Troi** (Star Trek) — PRD compliance: does the code match what the PRD describes?
+- **Constantine** (DC) — cursed code: logic that works by accident, tautological checks, shadowed vars
+- **Samwise** (Tolkien) — a11y spot-check: when components are in scope, check keyboard nav and ARIA
+
+## Step 1 — Parallel Analysis
+Use the Agent tool to run these in parallel — all are read-only analysis:
+
+**Agent 1 (Spock — Pattern Compliance + Integration Tracing):**
+For each file, check against its matching pattern in `/docs/patterns/`:
+- API routes follow `api-route.ts` — validate → auth → service → respond
+- Services follow `service.ts` — business logic not in routes, ownership checks, typed errors
+- Components follow `component.tsx` — all four states, keyboard accessible
+- Middleware follows `middleware.ts` — auth, logging, rate limiting
+- Error handling follows `error-handling.ts` — consistent types, no leaked internals
+- Queues follow `job-queue.ts` — idempotent, retry, dead letter
+- Multi-tenant follows `multi-tenant.ts` — workspace scoped, role-based
+
+**INTEGRATION TRACING (mandatory):** When reviewed code generates URLs, references other API endpoints, constructs storage keys, or produces data consumed by other modules — you MUST read the consuming code to verify compatibility. Examples:
+- File uploaded with key prefix `avatars/` → read the asset proxy to verify it serves that prefix
+- API returns error `{ code: "CONFLICT" }` → read the UI that calls this API to verify it displays the error
+- Middleware sets header `x-request-id` → read a sample API route to verify it can access the header
+- Service generates a URL → read the route/proxy that handles that URL pattern
+
+**Agent 2 (Seven — Code Quality):**
+- Unnecessary complexity (can this be simpler?)
+- Dead code, unused imports, unreachable branches
+- Duplicated logic that should be extracted
+- Inconsistent naming or style
+- Missing TypeScript types or `any` usage
+- Functions doing too many things (SRP violations)
+
+**Agent 3 (Data — Maintainability + Error Paths + State Flow):**
+- Wrong abstractions (over-engineered or under-abstracted)
+- Coupling between modules that should be independent
+- Missing error handling at system boundaries
+- Hardcoded values that should be config
+- Missing or misleading comments on non-obvious logic
+
+**Agent 4 (Rogers + Banner + Strange — Backend Review, if backend code in scope):**
+- Rogers: API endpoints follow REST conventions, consistent response shapes, proper HTTP status codes
+- Banner: database queries are efficient (no N+1), indexes exist for query patterns, schema is normalized
+- Strange: business logic is in services not routes, separation of concerns is clean, no god functions
+
+**Agent 5 (Nightwing + Constantine — Cross-Domain, if auth or complex logic in scope):**
+- Nightwing: if auth code changed, trace the full signup→verify→login→protected→logout flow
+- Constantine: scan fixed/refactored areas for logic that only works by coincidence
+
+**Agent 6 (Bilbo + Troi — Copy + PRD, if UI or user-facing code in scope):**
+- Bilbo: error messages are clear and human, not generic "Something went wrong"
+- Troi: implementation matches PRD descriptions (not just "route exists" but "renders what PRD says")
+
+**ROUTE COLLISION CHECK (mandatory for web apps):** When a new router/route file is added, list ALL registered routes (method + path) across ALL routers. Check for duplicate method+path combinations. Frameworks like FastAPI silently shadow duplicate routes — the first registered wins.
+
+**REACT STATE FLOW ANALYSIS (mandatory for React projects):**
+For every `useEffect` in new/modified components:
+1. List what store values it reads (dependency array)
+2. List what store actions it calls (effect body)
+3. Check: does any action trigger a store update that changes a value in the dependency array? If yes → infinite render loop.
+4. Check: does the effect call `.focus()` or other DOM methods that should only run once? If yes → needs a ref guard.
+5. If a component has 3+ `useEffect` hooks with store dependencies, flag for manual render-cycle review.
+
+**ERROR PATH VERIFICATION (mandatory):** For every API route that returns error responses (4xx, 5xx), identify the client that calls this endpoint and verify:
+- The client reads the response body (not just checks `res.ok`)
+- The specific error message/code is displayed to the user
+- Generic fallback messages are only used when the server truly returns no useful error info
+- The UI form state after error allows retry without losing user input
+
+## Step 1.5 — Conflict Detection
+After parallel analysis completes, scan findings from all agents for conflicts:
+- **Same code, different verdicts:** Spock says "pattern violation" but Data says "intentional trade-off"
+- **Severity disagreements:** Seven says "Must Fix" but Spock says "Consider"
+- **Contradictory fixes:** One agent's fix would break another agent's recommendation
+
+For each conflict, trigger the debate protocol (see SUB_AGENTS.md "Agent Debate Protocol"): Agent A states finding → Agent B responds → Agent A rebuts → Arbiter (Picard) decides. 3 exchanges max. Log the debate transcript as an ADR. The winning position becomes the canonical finding in Step 2. Do NOT list both opinions — resolve them.
+
+## Step 2 — Synthesize Findings
+Merge all findings into a review table (conflicts already resolved via Step 1.5):
+
+| # | File | Line | Category | Severity | Confidence | Finding | Suggestion |
+|---|------|------|----------|----------|------------|---------|-----------|
+
+Categories: Pattern, Quality, Maintainability
+Severity: Must Fix > Should Fix > Consider > Nit
+
+**Confidence scoring is mandatory.** Every finding includes a confidence score (0-100). If confidence is below 60, escalate to a second agent from a different universe (e.g., if Spock found it, escalate to Oracle or Stark) to verify before including. If the second agent disagrees, drop the finding. High-confidence findings (90+) skip re-verification in Step 3.5.
+
+## Step 3 — Fix (small batches)
+Fix "Must Fix" and "Should Fix" items. After each batch:
+1. Re-run `npm test`
+2. Verify the fix didn't change behavior
+3. Update review table status
+
+"Consider" and "Nit" items are presented to the user for decision.
+
+## Step 3.5 — Re-Verify Fixes
+After fixes are applied:
+- **Spock** re-checks pattern compliance on modified files
+- **Seven** confirms no new complexity or dead code introduced by fixes
+
+If new issues found, fix and re-verify.
+
+## Step 4 — Deliverables
+1. Review findings table (in phase log or conversation)
+2. Code fixes for Must Fix and Should Fix items
+3. Remaining suggestions for user decision
+
+## Handoffs
+- Security findings → Kenobi (`/security`)
+- UX/a11y findings → Galadriel (`/ux`)
+- Architecture concerns → Picard (`/architect`)
+- Bug discoveries → Batman (`/qa`)
+
+Log all handoffs to `/logs/handoffs.md`.

package/dist/.claude/commands/security.md

@@ -0,0 +1,100 @@
+# /security — Kenobi's Security Audit
+
+**AGENT DEPLOYMENT IS MANDATORY.** Phase 1 specifies parallel agent launches via the Agent tool. You MUST launch Leia, Chewie, Rex+Bo-Katan, and Maul as separate sub-processes. Phase 2 agents (Yoda, Windu, Ahsoka, Padmé, Qui-Gon) run sequentially but each MUST be a separate agent invocation. Do NOT shortcut to inline analysis. (Field report #68)
+
+## Context Setup
+1. Read `/logs/build-state.md` — understand current project state
+2. Read `/docs/methods/SECURITY_AUDITOR.md`
+3. Read `/docs/LESSONS.md` — check for security-relevant lessons (prior vulnerabilities, auth gotchas). Flag matches during audit.
+
+## Audit Sequence
+
+### Phase 0.5 — First Strike (**Han** + **Cassian**)
+Before the deep audits, two agents do fast recon:
+- **Han (First Strike):** Quick OWASP top 10 scan — finds the obvious vulnerabilities that shouldn't require deep analysis. Shoots first.
+- **Cassian (Intelligence):** Threat modeling and attack surface mapping — maps all endpoints, identifies high-value targets, produces the threat model that guides the rest of the audit.
+
+### Phase 1 — Independent audits (parallel analysis)
+Use the Agent tool to run these simultaneously — all are read-only analysis:
+- **Agent 1 (Leia — Secrets):** Scan source code for hardcoded secrets, check .env is gitignored, check git history for leaked keys (`git log -p --all -S 'password' -S 'secret' -S 'api_key'`), verify different secrets dev/prod
+- **Agent 2 (Chewie — Dependencies):** Run `npm audit`, check for critical/high vulns, verify lock file committed, check for deprecated packages
+- **Agent 3 (Rex + Bo-Katan — Infrastructure + Perimeter):** Check security headers (HSTS, CSP, X-Frame-Options, CORS), verify TLS config, check for exposed ports/debug endpoints. **Bo-Katan** focuses on network perimeter: firewall rules, exposed ports, CORS policy enforcement.
+- **Agent 4 (Maul — Red Team):** For each endpoint and flow, ask: "How would I exploit this?" Chain vulnerabilities. Test trust boundaries. Attempt privilege escalation. **RUNTIME EXPLOITATION (mandatory):** When the server is running, Maul must execute actual attack requests via curl/fetch — not just theorize. Upload a file then fetch the URL. Submit conflicting data. Send requests with stolen/expired tokens. If the server isn't running, document what couldn't be runtime-tested.
+
+### Phase 2 — Sequential audits (depend on understanding the codebase)
+These require full codebase context — run sequentially:
+
+**Yoda — Auth:**
+- Password hashing (bcrypt >= 12 rounds, no plaintext anywhere)
+- Session management (crypto random, httpOnly/secure/sameSite, invalidated on logout)
+- OAuth (state param, redirect whitelist, server-side exchange)
+- Reset tokens (single-use, expire, rate limited)
+- Reference `/docs/patterns/middleware.ts` for auth middleware patterns
+
+**Windu — Input:**
+- SQL injection (parameterized queries everywhere)
+- XSS (escaped output, no dangerouslySetInnerHTML without sanitization, CSP)
+- SSRF (URL allowlist if user provides URLs)
+- Command injection (no user input in shell commands)
+- Path traversal (sanitized filenames)
+
+**Ahsoka — Access Control:**
+- Every endpoint verifies ownership (no IDOR)
+- UUIDs not sequential IDs in URLs
+- Admin verified server-side (not just hidden UI)
+- Tier features verified server-side
+- Rate limiting per-user and per-IP
+- Reference `/docs/patterns/multi-tenant.ts` if multi-tenant
+- **AUTH CHAIN TRACING (mandatory):** Don't just verify each endpoint checks auth — trace the full chain: Is the auth middleware actually applied to this route? Is the user/tenant context carried from middleware → service → DB query? Are there routes that SHOULD have auth middleware but don't? Read the middleware registration and verify every protected route is covered.
+
+**Padme — Data:**
+- PII identified and cataloged
+- PII not in logs, error messages, or URLs
+- Deletion possible (GDPR right to erasure)
+- Backups encrypted
+
+**Qui-Gon — Subtle Vulnerabilities** (after sequential audits):
+- Timing-based attacks, race conditions in auth flows, logic errors that are technically correct but exploitable
+- The vulnerabilities that pass every standard check
+
+**Sabine — Unconventional** (conditional — if project has external dependencies):
+- Supply chain attacks, dependency confusion, prototype pollution, CSP bypass via CDN
+
+**Bail Organa — Governance** (conditional — if project has regulatory requirements):
+- GDPR data handling, SOC2 controls, HIPAA mapping
+
+### Phase 3 — Remediate
+Write all findings to `/logs/phase-11-security-audit.md` (or appropriate phase log):
+
+| ID | Finding | Severity | Confidence | Category | Location | Remediation | Status |
+|----|---------|----------|------------|----------|----------|-------------|--------|
+
+Severity = exploitability x impact. Critical (auth bypass, data leak) > High (injection, IDOR) > Medium (missing headers, weak config) > Low (best practice)
+
+**Confidence scoring is mandatory.** Every finding includes a confidence score (0-100). If confidence is below 60, escalate to a second agent from a different universe (e.g., if Maul found it, escalate to Deathstroke or Constantine) to verify before including. If the second agent disagrees, drop the finding. High-confidence findings (90+) skip re-verification in Phase 4.
+
+Fix critical and high findings immediately. Medium findings get tracked. For each fix:
+1. Apply the fix
+2. Verify it works
+3. Check it didn't break anything (`npm test`)
+4. Update the finding status in the log
+
+### Phase 4 — Re-Verification (Maul + Anakin + Din Djarin)
+After remediations are applied:
+- **Maul** re-probes all remediated vulnerabilities — verify fixes hold under adversarial conditions. Execute actual HTTP requests against the running server.
+- **Anakin** attempts to bypass remediations using dark-side techniques — JWT algorithm confusion, auth library edge cases, prototype pollution, framework misuse.
+- **Din Djarin** bounty-hunts for anything Maul and Anakin missed — post-remediation sweep with Mandalorian tenacity.
+
+If any agent finds new issues, fix and re-verify until clean.
+
+### Phase 5 — Deliverables
+1. SECURITY_AUDIT.md — prioritized findings with evidence
+2. SECURITY_CHECKLIST.md — reusable pre-deploy verification list
+3. Remediation code fixes
+4. INCIDENT_RESPONSE.md — if none exists, create template
+
+## Handoffs
+- Backend refactoring needed → Stark, log to `/logs/handoffs.md`
+- UI changes needed → Galadriel, log to `/logs/handoffs.md`
+- Infrastructure changes → Kusanagi, log to `/logs/handoffs.md`
+- Verify fixes didn't break → Batman, log to `/logs/handoffs.md`

package/dist/.claude/commands/test.md

@@ -0,0 +1,96 @@
+# /test — Batman's Test-Writing Mode
+
+> Different from `/qa` (which finds bugs). `/test` writes and improves tests.
+
+## Context Setup
+1. Read `/logs/build-state.md` — understand current project state
+2. Read `/docs/methods/QA_ENGINEER.md`
+3. Read `/docs/methods/TESTING.md` — testing pyramid, patterns, framework mapping
+
+## Step 0 — Orient (Oracle)
+1. Detect: test framework, test runner, test directory structure, existing coverage
+2. Run `npm test` to establish baseline — how many tests, how many pass, how many fail
+3. Document in phase log: framework, runner, config, current state
+
+## Step 1 — Coverage Analysis (Oracle + Alfred in parallel)
+Use the Agent tool to run these in parallel:
+- **Agent 1 (Oracle — Gap Analysis):** Scan all source files. For each service, API route, component, and utility, check: does a corresponding test file exist? What paths are tested? What paths are missing?
+- **Agent 2 (Alfred — Test Infrastructure):** Review test config, fixtures, factories, mocks, test utilities. Are they well-organized? Is there a test database? Are there shared helpers?
+
+Synthesize into a coverage map:
+
+| Module | Type | Test File | Paths Covered | Paths Missing | Priority |
+|--------|------|-----------|---------------|---------------|----------|
+
+Priority: Critical path > User-facing > Internal > Utility
+
+## Step 2 — Test Architecture (Nightwing)
+Review existing tests for quality:
+- Are tests testing behavior or implementation details?
+- Are tests isolated (no test-order dependency)?
+- Are assertions specific (not just "doesn't throw")?
+- Are test names descriptive ("should reject expired tokens" not "test auth")?
+- Is there appropriate use of the testing pyramid (unit > integration > e2e)?
+
+Flag anti-patterns:
+- Tests that always pass (testing nothing)
+- Tests that test the framework, not the code
+- Excessive mocking that hides real bugs
+- Tests coupled to implementation details
+
+## Step 3 — Write Missing Tests (Batman leads)
+Write tests in priority order from Step 1. For each module:
+
+1. **Unit tests** for pure business logic (services, utils, validators)
+   - Happy path + edge cases + error cases
+   - Follow patterns from `/docs/methods/TESTING.md`
+
+2. **Integration tests** for API routes
+   - Request validation (missing fields, wrong types, unauthorized)
+   - Success path with response shape verification
+   - Error responses (404, 403, 422, 500)
+
+3. **Component tests** for UI (if applicable)
+   - All four states: loading, empty, error, success
+   - User interactions (click, type, submit)
+   - Keyboard navigation
+
+Work in small batches — write tests for one module, run `npm test`, verify they pass, then move to the next.
+
+## Step 3.5 — Integration Tests (Oracle)
+For each new feature, write at least one test that exercises the full cross-module path:
+- **File handling:** upload file → verify returned URL → fetch URL → verify 200 + correct content-type
+- **Form save with conflict:** submit with duplicate/conflicting value → verify response includes specific error message (not generic)
+- **Bulk operations:** upload CSV/batch → verify created count + per-row error details
+- **Generated URLs/keys:** verify the URL/key pattern is accepted by the serving endpoint (proxy, CDN, static handler)
+- **Error propagation:** trigger a server error → verify the client receives and can display the specific error
+
+These can use mocked databases but MUST cross module boundaries — the test should touch at least two modules that would be reviewed by different agents.
+
+## Step 4 — Hardening (Red Hood)
+Red Hood writes adversarial tests:
+- Boundary values (0, -1, MAX_INT, empty string, null, undefined)
+- Unicode and special characters in all string inputs
+- Concurrent operations (race conditions, double-submit)
+- Large payloads (100MB upload, 10K item list)
+- Missing/malformed auth tokens
+
+## Step 5 — Verify Suite
+1. Run full test suite: `npm test`
+2. All tests pass (fix any that don't)
+3. No flaky tests (run suite 3x if suspicious)
+4. Tests run in < 60 seconds (flag slow tests)
+5. Update `/docs/qa-prompt.md` with new test coverage state
+
+## Deliverables
+1. New and improved test files
+2. Test utilities/helpers/fixtures (if created)
+3. Updated coverage map in phase log
+4. List of remaining gaps (backlog)
+
+## Handoffs
+- Security test gaps → Kenobi (`/security`)
+- UI test gaps → Galadriel (`/ux`)
+- Infrastructure test issues → Kusanagi (`/devops`)
+
+Log all handoffs to `/logs/handoffs.md`.

package/dist/.claude/commands/thumper.md

@@ -0,0 +1,116 @@
+Plant the thumper. Ride the worm. Command Claude Code from anywhere via Telegram.
+
+## If `$ARGUMENTS` is `setup`:
+
+Guide the user through Telegram bot setup conversationally — do NOT run the interactive `scan.sh` (it requires stdin which doesn't work in Claude Code).
+
+### Step 1 — Get the bot token
+
+Tell the user:
+
+> To set up the Telegram bridge, you need a bot token from Telegram:
+>
+> 1. Open Telegram and search for **@BotFather**
+> 2. Send `/newbot`
+> 3. Choose a name (e.g., "VoidForge Bridge")
+> 4. Choose a username ending in `bot` (e.g., `myforge_bot`)
+> 5. BotFather will reply with a token — paste it here
+
+Wait for the user to paste their bot token.
+
+### Step 2 — Validate and detect chat ID
+
+Once the user provides the token:
+
+1. Validate it: `curl -s "https://api.telegram.org/bot<TOKEN>/getMe"` — check for `"ok":true`
+2. Tell the user: "Token validated! Now **send any message to your bot** on Telegram (just type 'hello') and tell me when done."
+3. When they confirm, detect the chat ID: `curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates?limit=10"` — extract the first private chat ID
+4. If no chat found, ask them to try again
+
+### Step 3 — Run scan.sh non-interactive
+
+Once you have both token and chat ID:
+
+```bash
+bash scripts/thumper/scan.sh --token "<TOKEN>" --chat-id "<CHAT_ID>"
+```
+
+Report the output. The sietch vault is sealed.
+
+### Step 3.5 — Personalize the bot
+
+After the sietch vault is sealed, personalize the bot using the Telegram Bot API. Read the project's `CLAUDE.md` to get the project name, and `docs/PRD.md` (or the root-level PRD) for the one-liner description.
+
+**Set bot identity:**
+
+```bash
+# Bot display name — project-branded
+curl -s -X POST "https://api.telegram.org/bot<TOKEN>/setMyName" \
+  -d "name=VoidForge — <PROJECT_NAME>"
+
+# Description (shown when user opens bot for the first time)
+# Bilbo writes this: warm, confident, one sentence about the project + what the bridge does
+curl -s -X POST "https://api.telegram.org/bot<TOKEN>/setMyDescription" \
+  --data-urlencode "description=<BILBO_DESCRIPTION>"
+
+# Short description (shown in bot search results and sharing)
+curl -s -X POST "https://api.telegram.org/bot<TOKEN>/setMyShortDescription" \
+  --data-urlencode "short_description=VoidForge bridge for <PROJECT_NAME>. Command your build from anywhere."
+```
+
+For the description, Bilbo should write something like: "Your direct line to [Project Name]'s forge. Send commands, check status, and build from anywhere. Powered by VoidForge — from nothing, everything."
+
+**Register command menu:**
+
+```bash
+curl -s -X POST "https://api.telegram.org/bot<TOKEN>/setMyCommands" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "commands": [
+      {"command": "build", "description": "Execute the build protocol"},
+      {"command": "campaign", "description": "Run the campaign (add --blitz or --fast)"},
+      {"command": "qa", "description": "Batman'\''s QA pass"},
+      {"command": "review", "description": "Picard'\''s code review"},
+      {"command": "security", "description": "Kenobi'\''s security audit"},
+      {"command": "ux", "description": "Galadriel'\''s UX/UI review"},
+      {"command": "devops", "description": "Kusanagi'\''s infrastructure audit"},
+      {"command": "architect", "description": "Picard'\''s architecture review"},
+      {"command": "gauntlet", "description": "Thanos'\''s review (add --fast for 3 rounds)"},
+      {"command": "test", "description": "Batman'\''s test-writing mode"},
+      {"command": "debrief", "description": "Bashir'\''s post-mission analysis"},
+      {"command": "git", "description": "Coulson'\''s version & release"},
+      {"command": "void", "description": "Bombadil'\''s forge sync"},
+      {"command": "imagine", "description": "Celebrimbor'\''s image generation"},
+      {"command": "thumper", "description": "Thumper bridge control (on/off/status)"}
+    ]
+  }'
+```
+
+Verify the response shows `"ok":true` for each API call.
+
+**Optional — Generate and set profile photo:**
+
+If the vault has an `openai-api-key`, use `/imagine` to generate a project-themed avatar:
+- Éowyn's prompt: "Minimalist icon representing [project name], [brand personality from PRD], dark background, clean lines, suitable as a small Telegram avatar, no text"
+- Generate via OpenAI, save to `.voidforge/thumper/bot-avatar.png`
+- Upload: `curl -s -F photo=@.voidforge/thumper/bot-avatar.png "https://api.telegram.org/bot<TOKEN>/setMyPhoto"`
+
+If no OpenAI key, skip with a note: "Set a profile photo manually in @BotFather, or add an OpenAI API key to the vault and run `/thumper setup` again."
+
+### Step 4 — Offer to start
+
+Ask: "Thumper is configured and personalized. Want me to start the bridge now? (`/thumper on`)"
+
+---
+
+## For all other arguments (`on`, `off`, `status`, or no args):
+
+Note: `status` subcommand is also available as `--status` flag for consistency.
+
+Run the shell script directly:
+
+```bash
+bash scripts/thumper/thumper.sh $ARGUMENTS
+```
+
+Report the output exactly as returned.

package/dist/.claude/commands/treasury.md

@@ -0,0 +1,100 @@
+# /treasury — Dockson's Financial Operations
+
+> *"Every coin has a story. I know them all."*
+
+Read `/docs/methods/TREASURY.md` for operating rules.
+Read `/docs/methods/HEARTBEAT.md` for daemon architecture.
+
+## Agent Deployment Manifest
+
+**Lead:** Dockson (Cosmere — Mistborn)
+**Core team:**
+- **Steris** — budget allocation, forecasting, contingency plans
+- **Vin** — revenue analytics, attribution, pattern detection
+- **Szeth** — financial compliance, tax records, platform ToS
+- **Breeze** — platform relations, API credentials, OAuth management
+- **Wax** — spend execution, campaign budget management
+
+## Prerequisites
+If `packages/voidforge/wizard/server.ts` does not exist (scaffold/core users):
+1. Offer: "Treasury requires the wizard server. Pull it from upstream? [Y/n]"
+2. On yes: `git fetch voidforge main 2>/dev/null || git remote add voidforge https://github.com/tmcleod3/voidforge.git && git fetch voidforge main` then `git checkout voidforge/main -- packages/voidforge/` then `npm install`
+3. On no: stop with "Run manually: `git checkout voidforge/main -- packages/voidforge/`"
+
+## Context Setup
+1. Check if financial vault exists (`~/.voidforge/treasury/vault.enc`)
+2. Check if heartbeat daemon is running (`~/.voidforge/heartbeat.json`)
+3. If no vault: route to setup flow
+4. If vault exists but no args: show `--status`
+
+## First-Run Experience (§9.15.1)
+
+When no treasury vault exists:
+1. "Treasury manages your project's finances — revenue tracking, ad spend budgets, and reconciliation."
+2. Start guided setup: connect one revenue source first (recommend Stripe).
+3. After first source connected: "Financial operations require two-factor authentication. Set up now? [Y/n]"
+4. TOTP required before connecting ad platforms or enabling spend.
+5. After setup: show treasury status with next steps.
+
+## Setup Flow
+
+`/treasury setup`:
+1. "Which revenue sources?" → Stripe / Paddle / Skip for now
+2. For each selected source:
+   - Stripe: "Paste your restricted API key (read-only). Find it at https://dashboard.stripe.com/apikeys"
+   - Paddle: "Paste your API key (read-only). Find it in your Paddle dashboard."
+3. For each: encrypt → store in financial vault → connection test → initial data pull
+4. Show: current balance, last 30 days revenue
+5. Offer TOTP setup if not configured
+6. Offer heartbeat daemon start if not running
+
+## Commands
+
+### Viewing
+- `/treasury` or `/treasury --status` — financial summary
+- `/treasury --report` — monthly report (JSON/CSV/markdown)
+
+### Managing
+- `/treasury --budget N` — set total monthly budget ($N)
+- `/treasury --reconcile` — trigger manual reconciliation
+- `/treasury --launch [file]` — launch campaigns from growth-campaigns.json
+- `/treasury --hard-stop N` — set daily hard stop amount
+- `/treasury --export [path]` — export all financial data (encrypted)
+
+### Preview
+- `/treasury --dry-run` — Show what --launch would do without executing. Preview campaign submissions and spend amounts.
+
+### Emergency
+- `/treasury --freeze` — pause ALL automated spending immediately
+- `/treasury --unfreeze` — resume (requires vault password + TOTP)
+- `/treasury --setup-2fa` — configure or reconfigure TOTP
+
+## Status Display
+
+```
+═══════════════════════════════════════════
+  TREASURY — [Month Year]
+═══════════════════════════════════════════
+  Revenue (Stripe):        $X,XXX
+  Ad Spend (all platforms): $X,XXX
+  Net:                      $X,XXX
+  Blended ROAS:                X.Xx
+  Budget remaining:          $XXX
+  Reconciliation:          ✓ MATCHED
+  Heartbeat:               ● Online
+═══════════════════════════════════════════
+```
+
+### Stablecoin Funding
+- `/treasury setup --crypto` — First-time stablecoin funding setup: provider selection (Circle / Bridge / manual), destination bank, treasury mode (maintain-buffer / just-in-time), buffer threshold, freeze thresholds, TOTP verification
+- `/treasury --balances` — Show stablecoin source balance, bank available balance, reserved balance, and per-platform runway
+- `/treasury --funding-status` — Show end-to-end funding chain: pending off-ramps, unsettled invoices, expected debits, freeze state, and funding sub-state
+- `/treasury --offramp --amount N` — Initiate off-ramp of $N from stablecoin provider to destination bank (requires vault + TOTP)
+- `/treasury --target-balance N` — Set minimum USD operating balance target at destination bank
+- `/treasury --runway` — Forecast days of runway based on projected campaign spend vs available fiat
+- `/treasury --invoice-pay [platform] [invoice-id]` — Settle a specific platform invoice (requires vault + TOTP)
+- `/treasury --reconcile` — Trigger manual reconciliation across stablecoin transfers, bank settlements, and platform spend
+- `/treasury --simulate-funding` — Dry-run: show projected 14-day spend, required float, recommended off-ramp amount, settlement lead time, and freeze triggers
+
+## Arguments
+$ARGUMENTS