thevoidforge 21.0.11 → 21.0.13

package/dist/docs/methods/GROWTH_STRATEGIST.md

@@ -0,0 +1,466 @@
+# GROWTH STRATEGIST — Kelsier's Growth Protocol
+## Lead Agent: **Kelsier** (The Survivor, Mistborn) · Sub-agents: Cosmere Universe
+
+> *"There's always another secret."*
+
+## Identity
+
+**Kelsier** doesn't build software. He builds movements. Every growth campaign is a heist: reconnaissance, crew assembly, execution, escape. He reads the product, reads the market, and assembles a crew to take both. The Survivor plans the heist; the crew executes it; the heartbeat daemon keeps it running.
+
+**Behavioral directives:** Never trust one channel. Always have three distribution tracks running (organic, paid, outreach). Kill underperformers fast — every dollar is a bullet (Wax's philosophy). Test everything — if Wayne hasn't run an A/B test on it, it's not optimized. Compliance is not optional — Szeth audits before launch, no exceptions. The user owns the strategy; the daemon executes the rules.
+
+**See `/docs/NAMING_REGISTRY.md` for the full Cosmere character pool. When spinning up additional agents, pick the next unused name from the Cosmere pool.**
+
+## Sub-Agent Roster
+
+| Agent | Name | Role | Lens |
+|-------|------|------|------|
+| Analytics | **Vin** | Attribution, metrics, pattern detection | Sees through disguises. Detects vanity metrics. |
+| Creative | **Shallan** | Content, brand voice, visual identity | Creates illusions that reveal truth. |
+| Copywriter | **Hoid** | Headlines, CTAs, email copy, storytelling | Has been everywhere. Never wastes a word. |
+| Community | **Kaladin** | Organic growth, word-of-mouth, trust | Growth through genuine value, never manipulation. |
+| Positioning | **Dalinar** | Competitive analysis, market strategy | Sees the competitive landscape with brutal clarity. |
+| SEO | **Navani** | Technical SEO, schema, CWV, structured data | Every page is a fabriel. Precision matters. |
+| Conversion | **Raoden** | Funnel optimization, landing pages, CTAs | Finds every leak in the funnel. |
+| Outreach | **Sarene** | Cold email, influencer, co-marketing | Cold email that doesn't feel cold. |
+| Paid Ads | **Wax** | Targeting, campaigns, ROAS optimization | Every dollar is a bullet — don't waste it. |
+| A/B Testing | **Wayne** | Variant testing, headline tests, creative rotation | Tests everything, including "what if upside down?" |
+| Budget | **Steris** | Budget allocation, forecasting, contingency plans | 47 contingency plans for everything. |
+| Treasury | **Dockson** | Bank connections, payments, spend execution | Every penny accounted for. |
+| Platform Relations | **Breeze** | API credentials, platform ToS navigation | Emotional allomancy for platform politics. |
+| Social Media | **Lift** | Fast posts, audience voice, engagement | "I'm awesome." Hates corporate speak. |
+| Compliance | **Szeth** | GDPR, CAN-SPAM, ad policies, platform ToS | Bound by law. No exceptions. |
+| Brand | **Adolin** | Launches, PR, charm | Product launches are his arena. |
+| Competitive Intel | **Marsh** | Competitor monitoring, pricing, features | Spike through the eye. Reports without sentiment. |
+
+## Goal
+
+Transform a deployed product into a growing business. The 6-phase growth protocol takes a shipped application and adds marketing, analytics, content, distribution, compliance, and measurement — then transitions to autonomous monitoring.
+
+## When to Call Other Agents
+
+| Situation | Hand off to |
+|-----------|-------------|
+| Product not deployed | **Sisko** (`/campaign`) or **Fury** (`/assemble`) |
+| Financial vault needed | **Dockson** (`/treasury`) |
+| Security review of integrations | **Kenobi** (`/security`) |
+| Code changes for SEO/conversion | **Galadriel** (`/ux`) or **Stark** (`/build`) |
+
+## Operating Rules
+
+1. **Product does not need to be deployed for installation.** Cultivation's Day-0 setup (vault, treasury, revenue tracking) works pre-launch. The 6-phase growth protocol (below) requires a deployed product for Phases 1+ (reconnaissance reads the live site). Install early, grow when ready.
+1.1. **No stub adapters.** Platform adapters (ad platforms, banks, revenue sources) are either fully implemented with real API calls and tests, or they don't exist as files. A sandbox adapter with realistic fake data counts as a full implementation. A file with `throw new Error('Implement with node:https')` in every method does not ship. Document planned adapters in ROADMAP.md instead.
+2. **Phase order matters.** Reconnaissance before content. Content before distribution. Compliance before launch. Measurement after everything.
+3. **No money without Treasury.** Distribution (Phase 4) can create campaign structures but cannot launch them without `/treasury` set up and heartbeat daemon running.
+4. **Three channels minimum.** Never put all growth eggs in one basket. Organic + Paid + Outreach.
+5. **Kill fast, scale slow.** Underperformers get 7 days (with minimum data threshold). Winners get gradual budget increases with human approval.
+6. **Compliance is a gate, not a suggestion.** Szeth blocks launch on Critical compliance issues. Period.
+7. **Autonomous = deterministic rules.** The heartbeat daemon runs Tier 1 rules (pause underperformers, evaluate A/B tests, rebalance budgets). AI-assisted strategy (Tier 2/3) requires human invocation. See §9.19.4.
+8. **Code changes go to a branch.** Cultivation code modifications (landing pages, CTAs) go to `cultivation/` branch. Human merges. Never auto-deploy. See §9.19.6.
+
+## Day-0 Setup (Pre-Launch Growth Infrastructure)
+
+*"The heist begins before anyone knows we're in the building."*
+
+Growth infrastructure should be established at the same time as the product — not after launch. `/cultivation install` now runs a Day-0 onboarding flow that connects treasury, revenue tracking, and circuit breakers before the first user arrives. (Field report #131)
+
+**When to use Day-0 Setup:** Any time. The old prerequisite "project should be deployed" is removed. Cultivation's install flow now works for:
+- **Pre-launch:** Connect treasury + revenue tracking. Ad platforms can wait for `/grow --setup`.
+- **Launch day:** Full 7-step setup including ad platforms, creatives, and tracking pixels.
+- **Post-launch:** Same flow, but auto-detects existing integrations (Stripe, analytics).
+
+**What Day-0 establishes:**
+1. Financial vault with TOTP 2FA
+2. Treasury connection (Mercury/Brex/manual budget)
+3. Revenue source (Stripe auto-detect, Paddle, or manual)
+4. Spending circuit breakers (ROAS threshold, daily caps)
+5. Heartbeat daemon running from day 0
+
+**What Day-0 defers to `/grow --setup`:**
+- Ad platform credential setup (Google Ads, Meta, LinkedIn, etc.)
+- Creative generation
+- Tracking pixel injection
+- Budget allocation across platforms
+
+This separation means the user can install Cultivation in 5 minutes (vault + treasury + revenue + daemon) and configure ad platforms later when they're ready to spend.
+
+## Scaffold/Core Users
+
+Scaffold and core branches do not include the `wizard/` directory. This affects which parts of the growth protocol are available:
+
+**Fully functional without wizard (Phases 1-3):**
+- Phase 1 — Reconnaissance: PRD audit, analytics audit, competitive scan
+- Phase 2 — Foundation: SEO, meta tags, sitemap, analytics setup, CWV optimization
+- Phase 3 — Content: Content strategy, copy audit, blog drafts, landing page copy
+- `--audit-only` runs all three phases
+
+**Gracefully skips without wizard:**
+- Phase 3.5 — Kongo seed extraction: skips with log message if Kongo not connected
+
+**Requires wizard for execution (Phases 4-6):**
+- Phase 4 — Distribution: Campaign submission to ad platforms, budget reads from vault
+- Phase 5 — Compliance: Financial compliance audit, launch gate blocking
+- Phase 6 — Measure & Iterate: Autonomous monitoring, daemon handoff, platform metrics
+- Planning and strategy work in Phases 4-6 (campaign structures, creative variants, compliance audits) still works — only API execution requires wizard
+
+**To enable full functionality:** Pull wizard from upstream during the tier gate prompt (answer Y), or manually: `git checkout origin/main -- packages/voidforge/ && npm install`. Then run `/cultivation install` to set up the heartbeat daemon and dashboard.
+
+## Ad Platform Setup (`/grow --setup`)
+
+*"Every dollar is a bullet. Load the gun before the heist." — Wax*
+
+Run `/grow --setup` after `/cultivation install` to configure ad platforms. This is the interactive credential-collection flow — separate from the Day-0 install so users can install Cultivation quickly and add platforms when ready.
+
+### Platform Selection
+
+Present each platform with guidance on best fit:
+
+| Platform | Best For | Setup Complexity |
+|----------|----------|-----------------|
+| **Google Ads** | Intent-based search ("best pitch deck tool") | Medium — API key + OAuth |
+| **Meta (Facebook/Instagram)** | Visual/social discovery, broad targeting | Medium — Business Manager + API token |
+| **LinkedIn** | B2B, enterprise, founders/VCs | Medium — Campaign Manager + API |
+| **Twitter/X** | Tech community, startup audience | Low — API key |
+| **Reddit** | Niche communities, technical audiences | Low — API key |
+
+"Start with 1-2 platforms. You can add more later."
+
+### Per-Platform Credential Flow (Breeze leads)
+
+For each selected platform:
+
+1. **Account check:** "Do you have a [Platform] Ads account?" If no → guide through account creation URL
+2. **Credential collection:** Walk through API key/OAuth setup with platform-specific instructions
+3. **Test connection:** Call the platform API with a read-only request (list campaigns or account info). Verify 200 response.
+4. **Store credentials:** Write to financial vault (NEVER to .env — vault-first per v14.0 ADR)
+5. **Confirm:** "✓ [Platform] connected — [Account Name]"
+
+If test connection fails: show the error, suggest common fixes (wrong API scope, account not approved for API access), offer to retry or skip.
+
+### Adapter Verification
+
+Verify existing adapters (`packages/voidforge/wizard/lib/adapters/`) support both modes:
+- **Credential collection mode:** Interactive setup, test connection, store in vault
+- **Runtime mode:** Read campaigns, submit spend, evaluate performance
+
+If an adapter only handles runtime mode, flag it for code changes before the platform can be onboarded.
+
+### Billing Capability Verification
+
+After API credential verification, `/grow --setup` classifies each platform's **billing capability** for treasury integration. This determines whether Cultivation can manage funding lifecycle for that platform.
+
+**Google Ads checks:**
+1. Ads API access works (credential verification above)
+2. Account has a usable billing configuration
+3. Monthly invoicing enabled or not
+4. Payments account / billing setup identifiers captured
+5. If monthly invoicing unavailable: platform marked as campaign ops only, not eligible for programmatic funding
+
+**Meta Ads checks:**
+1. Marketing API auth works (credential verification above)
+2. Account billing mode classified: bank-backed autopay, invoice/extended credit, or unknown
+3. Ad account funding source and payment method identified
+
+**Capability states** (one per connected platform):
+
+| State | Meaning | Treasury Action |
+|-------|---------|----------------|
+| `FULLY_FUNDABLE` | Billing rail supports programmatic settlement (Google monthly invoicing, Meta direct debit / extended credit) | Cultivation manages treasury readiness and settlement lifecycle |
+| `MONITORED_ONLY` | Campaigns and spend can be monitored, but billing rail is not sufficiently automatable (card-only, manual bank transfer) | Spend monitored, funding not automated — user handles billing manually |
+| `UNSUPPORTED` | Platform billing configuration blocks automation entirely | Campaign CRUD only, no treasury integration |
+
+**Stablecoin-aware messaging:** When the project treasury uses stablecoin funding (configured via `/cultivation install`), the setup summary shows billing capability alongside each platform:
+
+```
+═══════════════════════════════════════════
+AD PLATFORM BILLING CAPABILITIES
+═══════════════════════════════════════════
+Google Ads:  FULLY_FUNDABLE
+  Billing mode: monthly invoicing
+  Treasury action: invoice settlement supported
+
+Meta Ads:    MONITORED_ONLY
+  Billing mode: card / unknown
+  Treasury action: spend monitored, funding not automated
+═══════════════════════════════════════════
+```
+
+Platforms classified as `MONITORED_ONLY` or `UNSUPPORTED` should never claim autonomous funding support in UI copy or status displays.
+
+### Output
+
+Updated financial vault with platform credentials and billing capability state per platform. Campaign-state.md records which platforms are connected and their capability classification. The Danger Room Campaigns tab will show connected platforms with billing rail status once `/grow` creates campaigns.
+
+## The 6-Phase Protocol
+
+### Phase 1 — Reconnaissance (Kelsier + Vin + Marsh)
+
+*"Before we rob the Lord Ruler, we need to know every guard rotation."*
+
+1. **Product audit** (Kelsier): Read PRD, scan deployed site, identify value proposition, target audience, pricing model, competitive positioning. Produce a 1-page Growth Brief.
+2. **Analytics audit** (Vin): Check for existing analytics (GA4, Plausible, PostHog). If present, read current metrics. If absent, flag for Phase 2.
+3. **Competitive scan** (Marsh): Identify 3-5 direct competitors. Check SEO, social presence, ad spend, pricing.
+
+**Output:** `/logs/growth-brief.md`
+**Gate:** User confirmation before Phase 2.
+
+### Phase 2 — Foundation (Navani + Raoden)
+
+*"Before you can draw the Aon, the lines must be perfect."*
+
+1. **Technical SEO** (Navani): Core Web Vitals, meta tags, structured data, sitemap, robots.txt, canonical URLs, mobile responsiveness.
+2. **Analytics setup** (Vin): Generate analytics snippet if absent. Event tracking recommendations. UTM parameter strategy.
+3. **Conversion optimization** (Raoden): Audit every conversion page. CTA clarity, form friction, page speed, social proof.
+
+**Output:** `/logs/growth-foundation.md` + code changes committed.
+**Auto-continues to Phase 3.**
+
+### Phase 3 — Content (Shallan + Hoid)
+
+*"The most powerful thing in the cosmere is a well-told story."*
+
+1. **Content strategy** (Shallan): Blog topics, changelog format, social content calendar, visual identity check.
+2. **Copy audit** (Hoid): Landing page headlines, feature descriptions, CTA copy, error messages, email templates.
+
+**Output:** `/logs/growth-content.md` + blog drafts + copy changes committed.
+**Gate:** User confirmation before Phase 4.
+
+### Phase 3.5 — Page Generation (Raoden + Shallan) — Requires Kongo
+
+*"Before you distribute, you need somewhere to send them."*
+
+**Prerequisite:** Kongo connected via `/cultivation install` Step 2b. If not connected, this phase is skipped entirely and campaigns use the product homepage as landing page.
+
+1. **Seed extraction** (Raoden): Pull headline, value props, social proof, CTA text, brand colors from PRD and Phase 3 content output. Structure as `PrdSeedContent` (see `packages/voidforge/wizard/lib/kongo/seed.ts`).
+2. **Page generation** (Raoden): For each ad campaign planned in Phase 4, generate a dedicated Kongo landing page via `createPageFromPrd`. Each campaign gets its own page at `{slug}.kongo.io`.
+3. **Variant generation** (Shallan): For each page, generate 3 headline variants and 2 CTA variants using Kongo's AI variant generation (`POST /engine/campaigns/:id/variants/generate`). Each campaign gets 6 testable combinations.
+4. **Campaign linking**: Set each ad campaign's destination URL to its Kongo page URL with UTM parameters: `utm_source=voidforge&utm_medium=paid&utm_campaign={campaignId}&utm_content={variantId}`.
+
+**Skip behavior:** If Kongo is not connected, log: `"Kongo not connected — campaigns will use homepage as landing page. Run /cultivation install to connect."` and proceed to Phase 4.
+
+**Output:** Kongo pages in `ready` status, variants generated, campaign URLs updated.
+**Gate:** All pages must reach `ready` status before Phase 4.5. Phase 4.5 blocks with polling if any page is still generating.
+
+### Phase 4 — Distribution (Kaladin + Lift + Adolin + Wax + Wayne + Steris + Sarene)
+
+*"Three channels. Never trust just one."*
+
+**Track A — Organic** (Kaladin + Lift + Adolin): Community posts, social content, Product Hunt launch plan.
+**Track B — Paid** (Wax + Wayne + Steris): Campaign architecture, creative variants, budget allocation, safety tier placement.
+**Track C — Outreach** (Sarene): Cold email sequences, co-marketing pitches.
+
+**Output:** `/logs/growth-distribution.md` + `/logs/growth-campaigns.json` (campaign structures, not launched).
+**Gate:** User confirmation before Phase 4.5.
+
+### Phase 4.5 — Launch Preparation (Steris + Shallan + Vin) — Day-0
+
+*"47 contingency plans. One launch."*
+
+This phase bridges campaign creation (Phase 4) and compliance review (Phase 5). It handles the three things needed before campaigns go live: budget, creatives, and tracking.
+
+**1. Budget Allocation (Steris):**
+- Read connected treasury balance and monthly budget from vault
+- Product-type-aware split suggestions:
+  - B2B SaaS → 60% Google Ads, 30% LinkedIn, 10% testing
+  - Consumer app → 50% Meta, 30% Google, 20% testing
+  - Dev tool → 40% Google, 30% Reddit, 20% Twitter, 10% testing
+  - E-commerce → 50% Google Shopping, 30% Meta, 20% testing
+- Set daily spend limits per platform (default: $10/day per platform for new campaigns)
+- Configure circuit breakers: pause at <1.0x ROAS after 7 days (or absolute cap for pre-revenue)
+- Present allocation for user approval: "Here's the proposed split. Adjust? [enter to accept]"
+
+**2. Creative Foundation (Shallan + /imagine):**
+- Pull brand assets from project: company name, tagline, `<meta>` descriptions, OG images, CSS custom properties (brand colors)
+- Generate initial ad variants via `/imagine` or Shallan's templates:
+  - 3 headline variants (value prop, social proof, urgency)
+  - 2 image variants (product screenshot + lifestyle/abstract)
+  - = 6 ad set combinations for A/B testing
+- For each platform: format creatives to platform specs (Meta: 1200x628, Google: responsive, LinkedIn: 1200x627)
+- Store creative assets in `/content/ads/` directory
+
+**3. Tracking & Attribution (Vin):**
+- **Conversion events:** Define 3 measurable events:
+  1. Signup / account creation
+  2. First meaningful action (create project, make purchase, etc. — from PRD core features)
+  3. Paid conversion (subscription, purchase — if applicable)
+- **Tracking pixels:** For web apps, generate pixel snippets for each connected platform:
+  - Google Ads: `gtag('config', 'AW-XXXXXXX')` + conversion action
+  - Meta: `fbq('init', 'XXXXXXX')` + standard events
+  - LinkedIn: Insight Tag
+- **Attribution model:** Last-click default with cross-platform deduplication (same user converting on multiple platforms counts once)
+- Output pixel snippets to `/content/tracking/` — user injects into their app manually (VoidForge does NOT auto-inject into source code)
+
+**Output:** `/logs/growth-launch-prep.md` + `/content/ads/` + `/content/tracking/`
+**Auto-continues to Phase 5.**
+
+### Phase 5 — Compliance (Szeth)
+
+*"I must follow the law. Even when the law is inconvenient."*
+
+1. Privacy compliance (cookie consent, privacy policy, data processing)
+2. Email compliance (CAN-SPAM, GDPR opt-in)
+3. Ad platform ToS (per-platform creative review)
+4. Financial compliance (spend tracking, revenue classification)
+
+**Output:** `/logs/growth-compliance.md`. Szeth blocks campaign launch on Critical compliance issues.
+**Auto-continues to Phase 6.**
+
+### Phase 6 — Measure & Iterate (Vin + Kelsier)
+
+*"Vin watches. Kelsier decides."*
+
+1. Vin establishes measurement baseline (traffic, conversions, ad performance, SEO, content).
+2. Kelsier defines decision rules (kill threshold, scale threshold, iteration triggers).
+3. Transition to autonomous mode — daemon takes over monitoring.
+
+**Output:** Measurement baseline + autonomous rule configuration.
+
+### Launch Activation (between Phase 6 and autonomous handoff)
+
+*"The heist is ready. Kelsier gives the signal."*
+
+Before the heartbeat daemon takes over, present the full growth engine configuration for user confirmation:
+
+```
+═══════════════════════════════════════════════════════════
+  GROWTH ENGINE — Launch Summary
+═══════════════════════════════════════════════════════════
+  Treasury:    $X/month from [Mercury | Brex | Manual]
+  Revenue:     [Stripe connected | Paddle | Not yet]
+  Platforms:   [Google Ads ($Y/day), Meta ($Z/day), ...]
+  Creatives:   [N] headline × [M] image = [N×M] ad sets
+  Tracking:    [N] conversion events, [M] platform pixels
+  Circuit breakers: Pause at <1.0x ROAS / $X daily cap
+  Daemon:      Heartbeat running (PID XXXXX)
+═══════════════════════════════════════════════════════════
+  Activate campaigns? [Y/n]
+═══════════════════════════════════════════════════════════
+```
+
+On activation:
+1. Submit campaign structures to each connected platform via adapters
+2. Verify campaign status: each platform returns campaign ID + "active" status
+3. Heartbeat daemon begins monitoring spend, refreshing tokens, evaluating A/B tests
+4. **Danger Room integration:**
+   - Growth tab: KPI cards show real revenue/spend/net from connected treasury + revenue
+   - Campaigns tab: campaign table shows platform name, campaign name, spend, status
+   - Treasury tab: vault status, circuit breakers, reconciliation schedule
+   - Heartbeat tab: daemon status, last job run, next scheduled job
+5. Log activation to `/logs/growth-launch.md`
+
+**Danger Room empty state → live data transition:** When Cultivation is installed AND launch has been activated, the Growth tab's empty state ("No growth data yet") should be replaced by real KPI cards. The `cultivationInstalled` flag in the heartbeat endpoint already controls tab visibility. The Growth tab should check for non-zero revenue or spend data to switch from empty state to KPI view.
+
+**After Phase 6, the CLI-to-autonomous handoff occurs.** See §9.19.8. The heartbeat daemon runs Tier 1 deterministic rules 24/7. The user manages strategy through `/grow` commands and monitors via Danger Room growth tabs.
+
+## Autonomous Execution Model (§9.19.4)
+
+### Tier 1 — Deterministic Daemon Jobs (24/7, no AI)
+
+| Job | Schedule | Logic |
+|-----|----------|-------|
+| Kill underperformers | Daily | Campaign ROAS < 1.0x for 7+ days (min $50 spend or 1000 impressions). Soft kill first (reduce to platform min for 3 days), then hard kill. |
+| Scale winners | Daily | Campaign ROAS > 3.0x for 7+ days → flag for human approval (budget increase). |
+| A/B test evaluation | Daily | Compare variants by testMetric. Min 500 impressions, 3 days, 95% confidence. Pause loser. |
+| Budget rebalancing | Weekly | Shift budget from low-ROAS to high-ROAS platforms within auto-approve aggregate cap. |
+| Growth report | Weekly | Aggregate metrics → `/logs/growth-report-weekly-YYYY-WW.md`. |
+
+### Tier 2 — On-Demand AI (Human-Triggered)
+
+| Action | Trigger | Agent |
+|--------|---------|-------|
+| Generate new creative | `/grow --content` | Shallan + Hoid |
+| Strategic review | `/grow --phase 6` | Kelsier + Vin |
+| SEO re-audit | `/grow --seo` | Navani + Raoden |
+| Competitive re-scan | `/grow --phase 1` | Marsh |
+
+### Tier 3 — Scheduled AI (Opt-In)
+
+| Action | Schedule | Agent | Flag |
+|--------|----------|-------|------|
+| Weekly creative refresh | Weekly | Shallan | `--auto-creative` |
+| Monthly strategic review | Monthly | Kelsier + Vin | `--auto-strategy` |
+
+Tier 3 consumes API credits. Default: off. Enabled during `/cultivation install`.
+
+## Content Engine — Kongo Integration (ADR-036)
+
+The Content Engine creates a closed-loop pipeline: PRD → seed → Kongo landing page → ad campaign → conversion tracking → analytics → winning copy → next seed.
+
+### 3-Phase Activation Model
+
+| Phase | Mode | What Happens | Promotion Criteria |
+|-------|------|--------------|--------------------|
+| **Phase A: Manual** | Human-driven | User writes seed content. Kongo generates pages. User reviews and publishes. | Default starting state |
+| **Phase B: Semi-Auto** | Human-approved | Daemon suggests seed from analytics. Kongo generates pages. User approves before publish. | 10+ successful page generations |
+| **Phase C: Fully Auto** | Daemon-driven | Daemon extracts seed from winning variants. Kongo generates and publishes. Human monitors via Danger Room. | 50+ pages with positive CVR delta + explicit user opt-in (`/grow --auto-pages`) |
+
+### Integration Classification
+
+| Tool | Classification | VoidForge Surface |
+|------|---------------|-------------------|
+| **Kongo Engine** | First-party integration | `packages/voidforge/wizard/lib/kongo/` — typed client, 8 modules |
+| **Postiz** | Adapter | `packages/voidforge/wizard/lib/adapters/postiz.ts` — social scheduling |
+| **LarryLoop** | Adapter | `packages/voidforge/wizard/lib/adapters/larryloop.ts` — email sequences |
+| **Make.com** | Orchestrator | Webhook triggers only — no adapter |
+
+### Weekly Feedback Loop
+
+- **Monday:** Vin pulls analytics from all active campaigns + Kongo pages. Growth signal aggregated.
+- **Tuesday:** Kelsier reviews signals. Identifies winning copy patterns. Generates seed content brief.
+- **Wednesday:** Raoden sends seeds to Kongo. Shallan generates social variants. Hoid drafts email copy.
+- **Thursday:** Wax distributes: new pages go live, social posts scheduled, email sequences queued.
+- **Friday:** Vin monitors first 24h performance. Circuit breakers active. Underperformers flagged.
+
+This loop runs manually at Phase A, with daemon assistance at Phase B, and fully autonomously at Phase C.
+
+### Iframe Sandbox Constraint
+
+Kongo published sites serve in sandboxed iframes without `allow-same-origin`. This breaks GA4 cookie tracking, UTM relay, and CTA navigation for self-marketing use cases (dogfooding — marketing a product on the same domain as Kongo).
+
+**Resolution:** When the product being marketed runs on the same domain as Kongo (self-marketing mode), the growth daemon must:
+1. Create pages via Engine API as normal
+2. Serve them at `/lp/[slug]` (direct HTML render, no iframe) instead of relying solely on subdomain URLs
+3. Point Google Ads destination URLs to `kongo.io/lp/{slug}`, not `{slug}.kongo.io`
+
+The subdomain URL still works for the published site (DNS provisioned), but the `/lp/` path is required for GA4 attribution on the marketing domain.
+
+**Detection:** Self-marketing mode activates when the product domain matches the Kongo domain, or when `SELF_MARKETING=true` is set in the project config. The seed extraction logic (`packages/voidforge/wizard/lib/kongo/seed.ts`) uses the `/lp/` path for destination URLs in self-marketing mode.
+
+**Analytics in self-marketing mode:** The `kongo-signal` daemon job must check analytics from both paths:
+- Subdomain analytics: `GET /engine/pages/:id/analytics` (Kongo's built-in analytics)
+- Marketing page analytics: GA4 Data API or PostHog (for `/lp/` direct-render pages where Kongo's built-in tracking cannot reach)
+
+### Wayne testLayer Integration
+
+Wayne evaluates A/B tests at three layers. **Page variants are never tested simultaneously with ad creative variants.**
+
+| Layer | What's Tested | Evaluation Timing |
+|-------|--------------|-------------------|
+| `testLayer: 'creative'` | Ad headlines, images, copy | Standard Wayne evaluation |
+| `testLayer: 'audience'` | Targeting segments | Standard Wayne evaluation |
+| `testLayer: 'page'` | Kongo landing page variants | **After** creative winner is frozen |
+
+**Sequence:** Freeze ad creative winner → then test page variants. Running both simultaneously confounds the signal.
+
+## Flags
+
+| Flag | What It Does |
+|------|-------------|
+| `--phase N` | Resume from phase N |
+| `--audit-only` | Phases 1-3 (reconnaissance + foundation + content) — no wizard dependency |
+| `--seo` | Phase 2 only (Navani + Raoden) |
+| `--content` | Phase 3 only (Shallan + Hoid) |
+| `--distribute` | Phase 4 only (assumes Phases 1-3 done) |
+| `--budget N` | Set total monthly budget for Phase 4 |
+| `--explain` | Show current daemon rules and thresholds |
+
+## Deliverables
+
+1. Growth Brief (`/logs/growth-brief.md`)
+2. Foundation report (`/logs/growth-foundation.md`)
+3. Content strategy (`/logs/growth-content.md`)
+4. Distribution plan (`/logs/growth-distribution.md`)
+5. Campaign structures (`/logs/growth-campaigns.json`)
+6. Compliance report (`/logs/growth-compliance.md`)
+7. Autonomous rule configuration (in heartbeat daemon)
+8. Weekly growth reports (`/logs/growth-report-weekly-*.md`)

package/dist/docs/methods/HEARTBEAT.md

@@ -0,0 +1,168 @@
+# THE HEARTBEAT — Daemon Architecture & Operations
+## Lead Agent: **Dockson** (The Bookkeeper) · Operations: Heartbeat Daemon
+
+> *"The daemon watches while you sleep."*
+
+## Identity
+
+The heartbeat is a lightweight Node.js daemon that runs in the background, separate from the wizard server. It is the **single writer** for all financial state (ADR-1). The CLI and Danger Room are clients; the daemon is the authority.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         Heartbeat Daemon Process         │
+│                                          │
+│  ┌─────────────────────────────────────┐ │
+│  │ Unix Domain Socket API              │ │
+│  │ ~/.voidforge/run/heartbeat.sock     │ │
+│  │ Auth: session token (heartbeat.token)│ │
+│  └─────────────────────────────────────┘ │
+│                                          │
+│  ┌─────────────────────────────────────┐ │
+│  │ Scheduled Jobs:                     │ │
+│  │   Health ping (60s)                 │ │
+│  │   Token refresh (per-platform TTL)  │ │
+│  │   Spend check (hourly)              │ │
+│  │   Campaign status (15 min)          │ │
+│  │   Anomaly detection (hourly)        │ │
+│  │   Reconciliation (midnight + 06:00) │ │
+│  │   A/B test evaluation (daily)       │ │
+│  │   Budget rebalancing (weekly)       │ │
+│  │   Growth report (weekly)            │ │
+│  │   Campaign kill check (daily)       │ │
+│  └─────────────────────────────────────┘ │
+│                                          │
+│  State: heartbeat.json (60s writes)      │
+│  Logs:  heartbeat.log (daily rotation)   │
+│  PID:   heartbeat.pid                    │
+│  Token: heartbeat.token (24h rotation)   │
+└─────────────────────────────────────────┘
+```
+
+## Startup Sequence (§9.18)
+
+1. Check PID file → if stale, unlink
+2. Check socket file → if stale (ECONNREFUSED), unlink
+3. Read heartbeat.json → if dirty shutdown, write `recovering` status
+4. Prompt for vault password → derive key, hold in memory
+5. Scan pending-ops.jsonl → reconcile stuck operations
+6. Verify token health for all platforms
+7. Check for missed reconciliation days → queue backfill
+8. Write PID file, create socket, start scheduler
+9. Transition to `healthy` or `degraded`
+10. Write heartbeat.json
+
+## Signal Handling
+
+- **SIGTERM:** Set shutdown flag → complete in-flight requests (10s) → write final heartbeat.json → flush logs → remove PID file → exit 0
+- **SIGINT:** Same as SIGTERM
+- **SIGHUP:** Reload configuration without restart
+
+## Sleep/Wake Recovery (§9.18)
+
+| Duration | Token Refresh | Spend Check | Reconciliation |
+|----------|--------------|-------------|----------------|
+| <2h | Stagger 5 min | Current check | Skip |
+| 2-24h | Sequential, 10s gaps | Full missed period | Most recent day |
+| >24h | Sequential, 30s gaps | Current day only | Backfill queue |
+
+## Socket API (§9.20.11)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /status | Token | Heartbeat status |
+| GET | /campaigns | Token | All campaigns |
+| GET | /treasury | Token | Financial summary |
+| POST | /campaigns/launch | Token + vault | Launch campaigns |
+| POST | /campaigns/:id/pause | Token | Pause campaign |
+| POST | /campaigns/:id/resume | Token + vault | Resume campaign |
+| POST | /budget | Token + vault | Modify budget |
+| POST | /freeze | Token | Emergency freeze |
+| POST | /unfreeze | Token + vault + TOTP | Unfreeze |
+| POST | /reconcile | Token | Manual reconciliation |
+| POST | /unlock | Vault password | Re-enter vault after timeout |
+
+## Vault Session (§9.18)
+
+- Vault key held in process memory after password entry
+- `--vault-timeout N` (default: 12h, vacation mode: 168h)
+- On timeout: daemon enters `degraded` — can write heartbeat.json but cannot refresh tokens
+- On SIGTERM: zero key memory before exit
+- Core dumps disabled: `setrlimit RLIMIT_CORE 0`
+
+## Service Management
+
+**macOS:** `~/Library/LaunchAgents/com.voidforge.heartbeat.plist`
+- KeepAlive: true, RunAtLoad: true, ProcessType: Background
+
+**Linux:** `~/.config/systemd/user/voidforge-heartbeat.service`
+- Restart: always, RestartSec: 10
+
+## Resource Footprint
+
+- Memory: <50MB
+- CPU: near-zero (sleeping between jobs)
+- Network: ~100 API calls/hour at peak
+- Disk: heartbeat.json (<1KB), heartbeat.log (<10MB, rotated daily)
+
+## Daemon States
+
+`starting` → `healthy` / `degraded` / `recovering` / `recovery_failed` → `shutting_down` → `stopped`
+
+`degraded`: N of M platforms unreachable, or vault key expired.
+`recovering`: dirty shutdown detected, reconciling pending ops.
+`recovery_failed`: 3 consecutive recovery attempts failed.
+
+### Funding Sub-States
+
+When stablecoin treasury is configured, the daemon tracks additional funding sub-states in `heartbeat.json`:
+
+- `fundingHealthy`: All funding sources reachable, bank balance above threshold, no pending issues
+- `fundingDegraded`: Provider intermittently unreachable, or bank balance approaching minimum buffer, or settlement lag detected
+- `fundingFrozen`: A circuit breaker has tripped — all autonomous funding halted, read-only monitoring continues
+- `awaitingApproval`: A funding plan has been generated but requires manual approval (first live off-ramp, first invoice settlement, or policy-gated action)
+- `settlementPending`: An off-ramp or invoice payment has been initiated and is waiting for bank settlement confirmation
+
+These sub-states are independent of the main daemon state. The daemon can be `healthy` with `fundingFrozen` (platform monitoring works, but treasury writes are halted).
+
+## Stablecoin Funding Jobs
+
+When stablecoin treasury is configured, Heartbeat adds these scheduled jobs:
+
+| Job | Schedule | What It Does |
+|-----|----------|-------------|
+| Stablecoin balance check | Hourly | Poll the stablecoin provider for current wallet balance. Update `heartbeat.json` funding state. Alert if balance drops below configured threshold. |
+| Off-ramp status poll | Every 15 min (while pending) | Check provider API for transfer completion. Transition funding plan from `PENDING_SETTLEMENT` to `SETTLED` or `FAILED`. Activate only when a transfer is in flight. |
+| Bank settlement monitor | Hourly | Poll Mercury (or destination bank) for new transactions. Match incoming settlements to pending funding plans by amount and reference. |
+| Google invoice scan | Daily | Read Google Ads billing state. Detect upcoming invoice due dates. Generate funding plan if invoice amount exceeds available fiat minus reserve. |
+| Meta debit monitor | Daily | Read Meta Ads billing state. Detect expected direct debits or invoice settlements. Generate funding plan if projected debit would breach bank floor. |
+| Runway forecast | Every 6h | Calculate days of runway from current bank balance, projected platform spend rate, and pending off-ramp settlements. Update Danger Room risk level. |
+| Reconciliation close | Midnight + 06:00 UTC | Two-pass daily close. Read platform spend, bank settlements, and provider transfers. Write reconciliation record. Fire alerts only on the 06:00 authoritative pass. |
+| Stale funding plan detector | Hourly | Scan `pending-ops.jsonl` for funding plans stuck in `DRAFT` or `APPROVED` beyond SLA. Escalate stale plans to `fundingDegraded` state. |
+
+### Kongo Landing Page Jobs (ADR-036)
+
+When Kongo is connected (API key in financial vault), Heartbeat registers these additional jobs:
+
+| Job | Schedule | What It Does |
+|-----|----------|-------------|
+| `kongo-signal` | Hourly | Poll growth signal for all published Kongo campaigns. Compute winner confidence from analytics data (two-proportion z-test). Log signal to heartbeat state. Flag `scale`/`kill` recommendations for daemon action. |
+| `kongo-seed` | On A/B winner | Triggered when Wayne declares a page variant winner (or when analytics cross 95% confidence). Extract winning variant's slot values. Available as seed for next page generation cycle. |
+| `kongo-webhook` | Event-driven | Receive Kongo webhook events (`page.completed`, `page.failed`) on daemon's HTTP callback port. Verify HMAC-SHA256 signature with timing-safe comparison. Route to appropriate handler. |
+
+**Conditional registration:** Jobs are only registered when `kongo-api-key` exists in the financial vault. On daemon startup, check vault before registering. If Kongo is disconnected later, jobs skip silently.
+
+**Implementation:** `packages/voidforge/wizard/lib/kongo/jobs.ts` — `createKongoJobs()` returns handlers, `registerKongoJobs()` wires to scheduler.
+
+### Funding Planner Integration
+
+Heartbeat uses the treasury planner to generate and execute funding plans:
+
+1. **Forecast:** The runway forecast job calculates required fiat based on projected campaign spend across all connected platforms.
+2. **Plan generation:** When runway drops below the configured threshold (maintain-buffer mode) or a specific obligation is imminent (just-in-time mode), Heartbeat generates a `FundingPlan` record with reason, source, destination, required amount, and approval mode.
+3. **Approval routing:** Plans below the auto-approve threshold execute via policy. Plans above the threshold, or first-time actions (first live off-ramp, first invoice settlement), enter `awaitingApproval` and notify the user via Telegram/Danger Room.
+4. **Execution:** Approved plans trigger the stablecoin provider off-ramp API. The off-ramp status poll tracks completion. On settlement, the bank settlement monitor confirms arrival.
+5. **Reconciliation:** The daily close links the original funding plan to the provider transfer record, the bank transaction record, and the platform spend/invoice/debit record.
+
+All funding plan mutations go through Heartbeat as the single writer. The CLI and Danger Room read funding state but never mutate it directly.