@tidyfactor/marketing 1.3.0 → 1.6.0

package/references/memory/ad-copy-templates.md

@@ -1,93 +1,94 @@
-# Marketing Memory: Ad Copy Templates & Platform Matrices
-
-Operational plug-and-play ad copy architectures for Meta, Google Search, TikTok, and LinkedIn.
-
----
-
-## 1. Meta Ads (Facebook & Instagram) Direct Response Matrix
-
-### Format A: The 3-Part Micro-Story (Best for Cold TOFU & Warm MOFU)
-```
-[HOOK / PATTERN INTERRUPT]: 
-Stop [common painful action] to achieve [desired outcome]. Most [niche/target] think [myth], but here is the truth...
-
-[BODY / MECHANISM]: 
-When we tested [method] with over [number/proof], we discovered:
-👉 Benefit 1 (Speed/Simplicity)
-👉 Benefit 2 (Cost/Efficiency)
-👉 Benefit 3 (Risk Removal)
-
-[CALL TO ACTION / OFFER]: 
-Get instant access to [Lead Magnet / Offer Name] today.
-Tap [Learn More / Shop Now] below before [scarcity/urgency trigger].
-🔗 [Link URL]
-```
-
-### Format B: The Side-by-Side Comparison (Old Way vs. New Way)
-```
-❌ THE OLD WAY TO [GOAL]:
-• Spend 15 hours a week on [painful task]
-• Pay $2,500/mo to agencies with zero accountability
-• Guess your numbers and hope for the best
-
-✅ THE [BRAND/PRODUCT] WAY:
-• Automated in under 5 minutes a day
-• Predictable, transparent [key metric/result]
-• 100% money-back guarantee if not thrilled in 30 days
-
-Ready to switch? 
-👉 Tap below to see how [Product] works in 90 seconds.
-```
-
----
-
-## 2. Google Responsive Search Ads (RSA) Matrix
-
-Google RSA requires up to **15 Headlines** (max 30 chars each) and **4 Descriptions** (max 90 chars each).
-
-### Headline Distribution Rule (15 Headlines):
-- **Positions 1-4 (Keywords & Solution)**: Exact match search query & primary value (e.g. `Automate Your Invoicing`, `Fast Cloud Server Hosting`).
-- **Positions 5-8 (Benefits & Speed)**: Outcome & speed metrics (e.g. `Save 12+ Hours Every Week`, `Deploy in Under 60 Seconds`).
-- **Positions 9-12 (Social Proof & Authority)**: Numbers & credibility (e.g. `Trusted by 10,000+ Teams`, `Rated 4.9/5 by 800+ Users`).
-- **Positions 13-15 (Offers & CTAs)**: Immediacy & risk-free actions (e.g. `Start Free 14-Day Trial`, `Get 30% Off Today Only`, `No Credit Card Required`).
-
-### Description Distribution Rule (4 Descriptions):
-- **Desc 1 (Problem -> Solution)**: Eliminate [pain point] with [Product]. Experience seamless [benefit] starting today.
-- **Desc 2 (Social Proof + Offer)**: Over [X] customers trust [Brand] for [outcome]. Sign up in 60 seconds with 0 setup fees.
-- **Desc 3 (Feature Breakdown)**: Includes [Feature 1], [Feature 2], and 24/7 dedicated support. Try risk-free for 30 days.
-- **Desc 4 (Direct CTA)**: Ready to double your [metric]? Discover why industry leaders choose [Product]. Get started now!
-
----
-
-## 3. TikTok & Reels Short-Form Video Script Architecture
-
-### Structure (15s to 45s Total Runtime):
-1. **0:00 - 0:03 (Visual & Verbal Hook)**:
-   - *Visual*: Show drastic before/after, unexpected movement, or screen recording.
-   - *Verbal*: "If you're still doing [X] in 2026, you're losing money..."
-2. **0:03 - 0:15 (The Problem & Insight)**:
-   - Agitate why current tools/methods fail. "Here is what no one is telling you..."
-3. **0:15 - 0:30 (The Demonstration / Proof)**:
-   - Screen capture or hands-on walkthrough showing product solving problem in 3 clicks.
-4. **0:30 - 0:40 (The Call to Action)**:
-   - "Comment '[KEYWORD]' and I'll DM you the direct link" OR "Link in bio to test it completely free."
-
----
-
-## 4. Arabic Ad Copy Variations (نماذج الإعلانات المباشرة بالعربية)
-
-### نموذج إعلان تفاعلي (Direct Response Meta / TikTok):
-```
-🛑 توقف عن إهدار [المال / الوقت] على [المشكلة الشائعة]!
-
-أغلب [أصحاب الأعمال / المستقلين / رواد الأعمال] يظنون أن الحل هو [الاعتقاد الخاطئ]، لكن الحقيقة أسهل بكثير:
-
-مع [اسم المنتج / المنظومة] ستتمكن من:
-🔹 [الميزة الأولى + النتيجة الرقمية الملموسة]
-🔹 [الميزة الثانية + توفير الجهد أو الوقت]
-🔹 [ضمان استرداد الأموال أو تجربة مجانية]
-
-⚡ عرض خاص لفترة محدودة: احصل على [الخصم أو البونص] الآن!
-👇 اضغط على الرابط بالأسفل وابدأ فوراً:
-[رابط العرض]
-```
+<!-- last-verified: 2026-09-02 -->
+# Marketing Memory: Ad Copy Templates & Platform Matrices
+
+Operational plug-and-play ad copy architectures for Meta, Google Search, TikTok, and LinkedIn.
+
+---
+
+## 1. Meta Ads (Facebook & Instagram) Direct Response Matrix
+
+### Format A: The 3-Part Micro-Story (Best for Cold TOFU & Warm MOFU)
+```
+[HOOK / PATTERN INTERRUPT]: 
+Stop [common painful action] to achieve [desired outcome]. Most [niche/target] think [myth], but here is the truth...
+
+[BODY / MECHANISM]: 
+When we tested [method] with over [number/proof], we discovered:
+👉 Benefit 1 (Speed/Simplicity)
+👉 Benefit 2 (Cost/Efficiency)
+👉 Benefit 3 (Risk Removal)
+
+[CALL TO ACTION / OFFER]: 
+Get instant access to [Lead Magnet / Offer Name] today.
+Tap [Learn More / Shop Now] below before [scarcity/urgency trigger].
+🔗 [Link URL]
+```
+
+### Format B: The Side-by-Side Comparison (Old Way vs. New Way)
+```
+❌ THE OLD WAY TO [GOAL]:
+• Spend 15 hours a week on [painful task]
+• Pay $2,500/mo to agencies with zero accountability
+• Guess your numbers and hope for the best
+
+✅ THE [BRAND/PRODUCT] WAY:
+• Automated in under 5 minutes a day
+• Predictable, transparent [key metric/result]
+• 100% money-back guarantee if not thrilled in 30 days
+
+Ready to switch? 
+👉 Tap below to see how [Product] works in 90 seconds.
+```
+
+---
+
+## 2. Google Responsive Search Ads (RSA) Matrix
+
+Google RSA requires up to **15 Headlines** (max 30 chars each) and **4 Descriptions** (max 90 chars each).
+
+### Headline Distribution Rule (15 Headlines):
+- **Positions 1-4 (Keywords & Solution)**: Exact match search query & primary value (e.g. `Automate Your Invoicing`, `Fast Cloud Server Hosting`).
+- **Positions 5-8 (Benefits & Speed)**: Outcome & speed metrics (e.g. `Save 12+ Hours Every Week`, `Deploy in Under 60 Seconds`).
+- **Positions 9-12 (Social Proof & Authority)**: Numbers & credibility (e.g. `Trusted by 10,000+ Teams`, `Rated 4.9/5 by 800+ Users`).
+- **Positions 13-15 (Offers & CTAs)**: Immediacy & risk-free actions (e.g. `Start Free 14-Day Trial`, `Get 30% Off Today Only`, `No Credit Card Required`).
+
+### Description Distribution Rule (4 Descriptions):
+- **Desc 1 (Problem -> Solution)**: Eliminate [pain point] with [Product]. Experience seamless [benefit] starting today.
+- **Desc 2 (Social Proof + Offer)**: Over [X] customers trust [Brand] for [outcome]. Sign up in 60 seconds with 0 setup fees.
+- **Desc 3 (Feature Breakdown)**: Includes [Feature 1], [Feature 2], and 24/7 dedicated support. Try risk-free for 30 days.
+- **Desc 4 (Direct CTA)**: Ready to double your [metric]? Discover why industry leaders choose [Product]. Get started now!
+
+---
+
+## 3. TikTok & Reels Short-Form Video Script Architecture
+
+### Structure (15s to 45s Total Runtime):
+1. **0:00 - 0:03 (Visual & Verbal Hook)**:
+   - *Visual*: Show drastic before/after, unexpected movement, or screen recording.
+   - *Verbal*: "If you're still doing [X] in 2026, you're losing money..."
+2. **0:03 - 0:15 (The Problem & Insight)**:
+   - Agitate why current tools/methods fail. "Here is what no one is telling you..."
+3. **0:15 - 0:30 (The Demonstration / Proof)**:
+   - Screen capture or hands-on walkthrough showing product solving problem in 3 clicks.
+4. **0:30 - 0:40 (The Call to Action)**:
+   - "Comment '[KEYWORD]' and I'll DM you the direct link" OR "Link in bio to test it completely free."
+
+---
+
+## 4. Arabic Ad Copy Variations (نماذج الإعلانات المباشرة بالعربية)
+
+### نموذج إعلان تفاعلي (Direct Response Meta / TikTok):
+```
+🛑 توقف عن إهدار [المال / الوقت] على [المشكلة الشائعة]!
+
+أغلب [أصحاب الأعمال / المستقلين / رواد الأعمال] يظنون أن الحل هو [الاعتقاد الخاطئ]، لكن الحقيقة أسهل بكثير:
+
+مع [اسم المنتج / المنظومة] ستتمكن من:
+🔹 [الميزة الأولى + النتيجة الرقمية الملموسة]
+🔹 [الميزة الثانية + توفير الجهد أو الوقت]
+🔹 [ضمان استرداد الأموال أو تجربة مجانية]
+
+⚡ عرض خاص لفترة محدودة: احصل على [الخصم أو البونص] الآن!
+👇 اضغط على الرابط بالأسفل وابدأ فوراً:
+[رابط العرض]
+```

package/references/memory/arabic-writing.md

@@ -1,6 +1,6 @@
 # Arabic Direct-Response & Copywriting Engineering
 
-<!-- last-verified: 2026-08-29 -->
+<!-- last-verified: 2026-09-02 -->
 
 Deterministic rules and linguistic frameworks for composing Arabic marketing, growth, and conversion copy natively without translation artifacts.
 

package/references/memory/campaign-mindmap.md

@@ -0,0 +1,85 @@
+<!-- last-verified: 2026-09-09 -->
+# Memory: campaign-mindmap
+
+Mermaid visual architecture illustrating the 7 marketing pillars, audience progression, and conversion loops within the TidyFactor Marketing Engine.
+
+---
+
+## 1. 360° Growth & Pillar Architecture
+
+```mermaid
+graph TD
+    classDef foundation fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
+    classDef topFunnel fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#f8fafc;
+    classDef midFunnel fill:#1e293b,stroke:#eab308,stroke-width:2px,color:#f8fafc;
+    classDef bottomFunnel fill:#1e293b,stroke:#22c55e,stroke-width:2px,color:#f8fafc;
+    classDef retention fill:#1e293b,stroke:#ec4899,stroke-width:2px,color:#f8fafc;
+
+    subgraph Pillar1["🏛️ Pillar 1: Strategy & Foundation"]
+        S1["Brand Positioning & Voice"]
+        S2["Competitive Differentiation"]
+        S3["Unit Economics & Margin Safety"]
+    end
+    class S1,S2,S3 foundation;
+
+    subgraph TopOfFunnel["🎯 Acquisition & Traffic (Pillars 2, 3, 5)"]
+        C1["Pillar 2: SEO Pillar-Cluster & Guides"]
+        SM1["Pillar 3: Social 0-3s Video Hooks & B2B"]
+        AD1["Pillar 5: 3-Angle Paid Ads (Pain / ROI / Proof)"]
+    end
+    class C1,SM1,AD1 topFunnel;
+
+    subgraph MiddleOfFunnel["⚡ Nurturing & Consideration (Pillars 2, 4)"]
+        N1["Pillar 2: Educational Newsletter Cadence"]
+        E1["Pillar 4: 5-Step Welcome Email Sequence"]
+        W1["Landing Page CRO Wireframe"]
+    end
+    class N1,E1,W1 midFunnel;
+
+    subgraph BottomOfFunnel["💰 Conversion & Transaction (Pillars 5, 6)"]
+        PR1["Pillar 6: 72h Flash Sale & Decoy Pricing"]
+        AD2["Pillar 5: Retargeting Ads (FOMO / Proof)"]
+        E2["Pillar 4: 3-Stage Abandoned Cart Flow"]
+    end
+    class PR1,AD2,E2 bottomFunnel;
+
+    subgraph RetentionLoop["🔄 Retention & Viral Growth (Pillar 7)"]
+        G1["Pillar 7: 2-Sided Viral Referral Program"]
+        G2["Pillar 7: Win-Back & Churn Intervention"]
+        G3["Pillar 7: VIP Loyalty & Micro-Influencers"]
+    end
+    class G1,G2,G3 retention;
+
+    %% Data flow connections
+    Pillar1 --> TopOfFunnel
+    TopOfFunnel --> MiddleOfFunnel
+    MiddleOfFunnel --> BottomOfFunnel
+    BottomOfFunnel --> RetentionLoop
+    RetentionLoop -.->|"Re-invest Margin & Referrals"| TopOfFunnel
+```
+
+---
+
+## 2. Lead Journey & Signal Progression
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Prospect / Visitor
+    participant Social as Social & Paid Ads
+    participant LP as CRO Landing Page
+    participant Email as Email Lifecycle Flow
+    participant Cart as Checkout & Payment
+
+    User->>Social: Stops scroll at 0-3s hook (Pain/ROI angle)
+    Social->>LP: Clicks standardized UTM link
+    LP->>User: Demonstrates mechanism & proof points
+    alt Takes Primary Offer
+        User->>Cart: Completes checkout with margin-safe offer
+    else Leaves without converting
+        LP->>Email: Captures lead via high-value lead magnet
+        Email->>User: Delivers 5-step nurture sequence
+        User->>Cart: Returns via cart recovery or flash sale discount
+    end
+    Cart->>User: Delivers product + triggers viral referral loop
+```

package/references/memory/decision-points.md

@@ -1,73 +1,74 @@
-# Marketing Contextual Decision Layer (CDL) — Thin Arbitration Protocol
-
-> **Purpose**: Governs pre-generation marketing elicitation. Resolves strategic, market, and copy ambiguities before campaign or copy emission without generating duplicate memory catalogs or conversational slop.
-
----
-
-## 🏛️ Marketing Decision Matrix (M1 – M5)
-
-When a marketing workflow begins and the request contains ambiguous parameters, the agent arbitrates across 5 standardized decision points:
-
-| ID | Decision Dimension | Reference SSOT Catalog | Conservative Default |
-|:---|:---|:---|:---|
-| **M1** | **Target Market & Regional Calibration** | `memory/frameworks.md` & `platform-specs.md` | `Bilingual / MENA-Ready (GCC + Egypt)` |
-| **M2** | **Brand Voice Archetype & Tone** | `memory/frameworks.md` | `Authoritative Challenger (Direct, ROI-backed)` |
-| **M3** | **Funnel Stage & User Sophistication** | `memory/lifecycle-flows.md` & `ad-copy-templates.md` | `Middle-of-Funnel (Solution-Aware)` |
-| **M4** | **Conversion Model & Core Offer** | `memory/promotions-math.md` & `frameworks.md` | `Value-First / Discovery Call / Freemium` |
-| **M5** | **Output Density & Asset Depth** | `memory/frameworks.md` | `Full Campaign Blueprint (Multi-Channel)` |
-
----
-
-## 🚦 Deterministic Boolean Skip Conditions
-
-The agent MUST skip asking questions and proceed directly to execution when any of the following conditions evaluate to `true`:
-
-```text
-1. Cached Brief Exists         → .tidyfactor/marketing-brief.md exists on disk
-2. Explicit Dimension in Prompt → User prompt explicitly specifies Region, Tone, Audience, or Offer
-3. Direct Command Invocation   → User called specific sub-command (e.g. /email, /advertising, /promotions)
-4. Copy Refresh / Optimization → Existing copy or campaign is provided for iterative rewrite
-5. Fast-Track Flag             → User appended --yes, -y, or "do not ask questions"
-```
-
----
-
-## 🎯 Direct Invocation vs. Refresh Invariants
-
-1. **Direct Invocation Invariant**: When a user explicitly runs `/advertising`, `/email`, `/promotions`, or `/strategy`, the agent skips general discovery and uses targeted command parameters immediately.
-2. **Zero-Regression Copy Refresh Bias**: When auditing, refreshing, or rewriting existing campaigns, the agent silently preserves the established brand voice, regional calibration, and offer economics unless an overhaul is explicitly requested.
-
----
-
-## ⚡ Single-Round Batching & Priority Hierarchy
-
-If multiple marketing dimensions remain ambiguous and no skip condition is met:
-
-1. **Maximum Questions**: Present at most **3 focused questions in a single round**. Never conduct multi-round interrogations.
-2. **Strict Priority Hierarchy**:
-   $$\mathbf{M1 \text{ (Region/Market)}} > \mathbf{M2 \text{ (Brand Voice)}} > \mathbf{M3 \text{ (Funnel Stage)}} > \mathbf{M4 \text{ (Offer)}} > \mathbf{M5 \text{ (Depth)}}$$
-3. **Priority Overflow**: If more than 3 dimensions are unknown, ask M1, M2, and M3; resolve M4 and M5 silently using the **Conservative Defaults**.
-
----
-
-## 🛑 Terminal Hard-Stop Contract
-
-When presenting decision options to the user, the agent MUST end its turn immediately and await user selection. It MUST NOT output partial marketing plans, draft placeholder copy, or speculate on unconfirmed choices in the same turn.
-
----
-
-## 💾 Brief Persistence Schema (`.tidyfactor/marketing-brief.md`)
-
-When `/brief` runs or decisions are confirmed, save them to `.tidyfactor/marketing-brief.md`:
-
-```markdown
-# Marketing Brief Baseline
-
-- **Product / Brand**: [Name]
-- **Target Market (M1)**: [MENA-GCC | MENA-Egypt | Global-US]
-- **Brand Voice (M2)**: [Authoritative Challenger | Empathetic Guide | Luxury Premium | Direct Response]
-- **Funnel Stage (M3)**: [Problem-Aware | Solution-Aware | Product-Aware / Most Aware]
-- **Core Offer (M4)**: [Lead Magnet | Free Trial | Discovery Call | Direct Transaction]
-- **Deliverable Scope (M5)**: [Sprint Copy | Full Campaign Blueprint]
-- **Last Updated**: [YYYY-MM-DD]
-```
+<!-- last-verified: 2026-09-02 -->
+# Marketing Contextual Decision Layer (CDL) — Thin Arbitration Protocol
+
+> **Purpose**: Governs pre-generation marketing elicitation. Resolves strategic, market, and copy ambiguities before campaign or copy emission without generating duplicate memory catalogs or conversational slop.
+
+---
+
+## 🏛️ Marketing Decision Matrix (M1 – M5)
+
+When a marketing workflow begins and the request contains ambiguous parameters, the agent arbitrates across 5 standardized decision points:
+
+| ID | Decision Dimension | Reference SSOT Catalog | Conservative Default |
+|:---|:---|:---|:---|
+| **M1** | **Target Market & Regional Calibration** | `memory/frameworks.md` & `platform-specs.md` | `Bilingual / MENA-Ready (GCC + Egypt)` |
+| **M2** | **Brand Voice Archetype & Tone** | `memory/frameworks.md` | `Authoritative Challenger (Direct, ROI-backed)` |
+| **M3** | **Funnel Stage & User Sophistication** | `memory/lifecycle-flows.md` & `ad-copy-templates.md` | `Middle-of-Funnel (Solution-Aware)` |
+| **M4** | **Conversion Model & Core Offer** | `memory/promotions-math.md` & `frameworks.md` | `Value-First / Discovery Call / Freemium` |
+| **M5** | **Output Density & Asset Depth** | `memory/frameworks.md` | `Full Campaign Blueprint (Multi-Channel)` |
+
+---
+
+## 🚦 Deterministic Boolean Skip Conditions
+
+The agent MUST skip asking questions and proceed directly to execution when any of the following conditions evaluate to `true`:
+
+```text
+1. Cached Brief Exists         → .tidyfactor/marketing-brief.md exists on disk
+2. Explicit Dimension in Prompt → User prompt explicitly specifies Region, Tone, Audience, or Offer
+3. Direct Command Invocation   → User called specific sub-command (e.g. /email, /advertising, /promotions)
+4. Copy Refresh / Optimization → Existing copy or campaign is provided for iterative rewrite
+5. Fast-Track Flag             → User appended --yes, -y, or "do not ask questions"
+```
+
+---
+
+## 🎯 Direct Invocation vs. Refresh Invariants
+
+1. **Direct Invocation Invariant**: When a user explicitly runs `/advertising`, `/email`, `/promotions`, or `/strategy`, the agent skips general discovery and uses targeted command parameters immediately.
+2. **Zero-Regression Copy Refresh Bias**: When auditing, refreshing, or rewriting existing campaigns, the agent silently preserves the established brand voice, regional calibration, and offer economics unless an overhaul is explicitly requested.
+
+---
+
+## ⚡ Single-Round Batching & Priority Hierarchy
+
+If multiple marketing dimensions remain ambiguous and no skip condition is met:
+
+1. **Maximum Questions**: Present at most **3 focused questions in a single round**. Never conduct multi-round interrogations.
+2. **Strict Priority Hierarchy**:
+   $$\mathbf{M1 \text{ (Region/Market)}} > \mathbf{M2 \text{ (Brand Voice)}} > \mathbf{M3 \text{ (Funnel Stage)}} > \mathbf{M4 \text{ (Offer)}} > \mathbf{M5 \text{ (Depth)}}$$
+3. **Priority Overflow**: If more than 3 dimensions are unknown, ask M1, M2, and M3; resolve M4 and M5 silently using the **Conservative Defaults**.
+
+---
+
+## 🛑 Terminal Hard-Stop Contract
+
+When presenting decision options to the user, the agent MUST end its turn immediately and await user selection. It MUST NOT output partial marketing plans, draft placeholder copy, or speculate on unconfirmed choices in the same turn.
+
+---
+
+## 💾 Brief Persistence Schema (`.tidyfactor/marketing-brief.md`)
+
+When `/brief` runs or decisions are confirmed, save them to `.tidyfactor/marketing-brief.md`:
+
+```markdown
+# Marketing Brief Baseline
+
+- **Product / Brand**: [Name]
+- **Target Market (M1)**: [MENA-GCC | MENA-Egypt | Global-US]
+- **Brand Voice (M2)**: [Authoritative Challenger | Empathetic Guide | Luxury Premium | Direct Response]
+- **Funnel Stage (M3)**: [Problem-Aware | Solution-Aware | Product-Aware / Most Aware]
+- **Core Offer (M4)**: [Lead Magnet | Free Trial | Discovery Call | Direct Transaction]
+- **Deliverable Scope (M5)**: [Sprint Copy | Full Campaign Blueprint]
+- **Last Updated**: [YYYY-MM-DD]
+```