@tidyfactor/marketing 1.3.0 → 1.6.0

package/references/workflows/brief.md

@@ -1,72 +1,111 @@
 # Marketing Discovery & Brief Workflow
 
-> **Outcome**: Generates an authoritative `.tidyfactor/marketing-brief.md` file capturing target market, brand voice, funnel stage, conversion model, and delivery scope.
+> **Outcome**: Generates an authoritative `.tidyfactor/marketing-brief.md` baseline capturing target market, brand voice, funnel stage, conversion model, and delivery scope.
 
 ---
 
-## 📋 Step 0: Check Existing Baseline
+## 📋 Step 0: Context Delta Resolution Engine
 
-1. Check if `.tidyfactor/marketing-brief.md` already exists on disk.
-2. If it exists and user did not specify `--force` or `--reset`:
-   - Display the active brief summary.
-   - Ask if the user wants to keep the existing baseline or update specific parameters.
+Before asking any questions, execute the mechanical resolution formula:
 
----
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
 
-## 💬 Step 1: Conduct 3-Question Targeted Discovery
+### 1. Required Decisions Set (from `manifest.json["decision_gates"]`):
+- `target_market`: Regional calibration (GCC, Egypt/Levant, Global B2B SaaS, Bilingual MENA).
+- `brand_voice`: Voice archetype (Authoritative Challenger, Empathetic Guide, Elite Luxury, High-Energy Direct Response).
+- `funnel_stage`: Conversion focus (Top / Middle / Bottom of funnel).
+- `core_offer`: Headline value proposition and transaction vehicle.
 
-If no baseline exists, present at most 3 clear, structured questions in a single turn:
+### 2. Discovered Facts (Auto-Sensing + Local Staleness Tracking):
+- Inspect `brand.yaml`, `brand.json`, and `BRAND-GUIDELINES.md` on disk.
+- If `track_staleness: true` is configured, verify file hash/mtime against stored snapshot.
+- Any decision successfully extracted from local disk is removed from $\text{Unknowns}$.
 
-### Question 1: Target Market & Regional Tone (M1)
-- **A) Gulf / GCC (Saudi Arabia 🇸🇦, UAE 🇦🇪, Kuwait 🇰🇼, Qatar 🇶🇦)** — High prestige, trust-first, WhatsApp/Installments framing, modern polished Arabic.
-- **B) Egypt & Levant (Egypt 🇪🇬, Jordan 🇯🇴)** — Practical ROI, high energy, relatable wit, cash-on-delivery & InstaPay framing.
-- **C) Global / B2B SaaS** — Direct, metric-dense, self-serve focused, English-first.
-- **D) Bilingual / Unified MENA** (Default).
+### 3. Fail-Open MCP Brain Acceleration:
+- If unresolved unknowns remain AND `search_knowledge_base` is available:
+  - Query `search_knowledge_base(query="marketing persona brand voice", scope="project")`.
+  - If a valid marketing KI exists, populate the context and remove from $\text{Unknowns}$.
+- **Fail-Open Invariant**: If Brain MCP is unavailable or offline, skip instantly with 0ms delay without warnings.
 
-### Question 2: Brand Voice Archetype (M2)
-- **A) Authoritative Challenger** (Direct, contrarian, proof-backed, no-nonsense).
-- **B) Empathetic Guide** (Supportive, story-driven, transformational, warm).
-- **C) Elite Luxury / High-End** (Minimalist, aspirational, refined confidence).
-- **D) High-Energy Direct Response** (Urgent, benefit-stacked, conversion-focused).
+---
 
-### Question 3: Funnel Focus & Core Offer (M3 + M4)
-- **A) Top-of-Funnel Lead Magnet** (Free guide, checklist, audit, quiz).
-- **B) Middle-of-Funnel Trial / Demo** (Product-led trial, 1-on-1 strategy call).
-- **C) Bottom-of-Funnel Direct Sale / Promo** (E-commerce purchase, limited-time launch offer).
+## 💬 Step 1: Interactive Modal Protocol (CDL v2.0)
+
+If $\text{Unknowns} = \emptyset$:
+- Display the synthesized 4-line baseline summary.
+- Suggest next commands (`/strategy`, `/advertising`, `/email`, `/content`) immediately.
+
+If $\text{Unknowns} \neq \emptyset$:
+- **Interactive Wizard Invariant**: Present genuine Unknowns exclusively via the native interactive question tool (`ask_question`). Never dump static text questionnaires or bullet lists in chat.
+- **Zero Robotic Preamble**: Forbid greetings or conversational filler.
+
+### Operational Mode Selection:
+
+#### [MODE A] Smart 3-Round Protocol (🎯 الارتجال الذكي المقيد)
+Presents structured choices one step at a time via `ask_question`:
+1. **Round 1 (Target Market & Regional Nuance)**:
+   - `(Recommended) Bilingual / Unified MENA` — Pan-Arab modern standard paired with English tech terminology.
+   - `Gulf / GCC (Saudi Arabia 🇸🇦, UAE 🇦🇪, Kuwait 🇰🇼, Qatar 🇶🇦)` — Prestige, trust-first, WhatsApp/Installment framing.
+   - `Egypt & Levant (Egypt 🇪🇬, Jordan 🇯🇴)` — Practical ROI, high energy, relatable wit, InstaPay framing.
+   - `Global / B2B SaaS` — Direct, metric-dense, self-serve focused, English-first.
+2. **Round 2 (Brand Voice Archetype)**:
+   - `(Recommended) Authoritative Challenger` — Direct, contrarian, proof-backed, zero-nonsense.
+   - `Empathetic Guide` — Supportive, story-driven, transformational, warm.
+   - `Elite Luxury / High-End` — Minimalist, aspirational, refined confidence.
+   - `High-Energy Direct Response` — Urgent, benefit-stacked, conversion-focused.
+3. **Round 3 (Funnel Focus & Core Offer)**:
+   - `(Recommended) Bottom-of-Funnel Direct Sale / Promo` — Immediate transaction, launch offer.
+   - `Middle-of-Funnel Trial / Demo` — Product-led trial, strategy session.
+   - `Top-of-Funnel Lead Magnet` — Free high-value guide, benchmark, audit.
+
+#### [MODE B] Debate Mode (🔥 الاستجواب والمناظرة اللانهائية)
+- Activated via `/debate`, explicit user prompt ("مناظرة" / "استجوبني"), or Mode A escalation.
+- Relentlessly challenges marketing assumptions, price elasticity, CAC-to-LTV payback periods, and unproven claims.
+- Presents binary architectural trade-offs one step at a time via `ask_question`.
+- Terminates only upon explicit user trigger (`"END DEBATE"` / `"اعتماد"`), emitting a formal synthesis.
 
 ---
 
-## 💾 Step 2: Write `.tidyfactor/marketing-brief.md`
-
-Format and persist the confirmed choices:
+## 💾 Step 2: Persist Baseline & Single-Direction Brain Push
 
+1. Format and write `.tidyfactor/marketing-brief.md`:
 ```markdown
 # Marketing Brief Baseline
 
 - **Product / Brand**: [Extracted or Confirmed Name]
-- **Target Market (M1)**: [Confirmed Selection]
-- **Brand Voice (M2)**: [Confirmed Archetype]
-- **Funnel Stage (M3)**: [Top / Middle / Bottom]
-- **Core Offer (M4)**: [Lead Magnet / Trial / Direct Transaction]
-- **Deliverable Scope (M5)**: [Sprint Copy / Multi-Channel Blueprint]
+- **Target Market**: [GCC / Egypt & Levant / Global / Unified MENA]
+- **Brand Voice**: [Authoritative / Empathetic / Luxury / Direct Response]
+- **Funnel Stage**: [Top / Middle / Bottom]
+- **Core Offer**: [Lead Magnet / Trial / Direct Transaction]
+- **Deliverable Scope**: [Sprint Copy / Multi-Channel Blueprint]
 - **Last Updated**: [Current Date]
 ```
 
+2. Format YAML snapshot `.tidyfactor/marketing-brief.snapshot.yaml` for deterministic local staleness tracking (Rule 15).
+
+3. **Anti-Dual-Write Outbound Push (`--sync-brain`)**:
+   - The local file is ALWAYS the single source of truth.
+   - When explicitly passed `--sync-brain`, format the deliverable as an Atomic KI and push to Brain MCP via `extract_knowledge_item`.
+   - Never perform simultaneous dual writes.
+
 ---
 
-## 🎯 Step 3: Self-Critique & Handoff
+## 🎯 Step 3: Self-Critique & Actionable Summary
 
 Stamp the 7-axis critique:
 ```markdown
 /* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */
 ```
+Display a concise summary and suggest the next logical marketing command (`/strategy`, `/advertising`, `/email`, `/content`, `/audit`).
 
 ---
 
-## ## Validation checklist
+## Validation checklist
 
+- [ ] Context Delta Resolution computed prior to prompting user.
+- [ ] No questions asked for parameters already discovered on disk.
+- [ ] Unknowns presented via native interactive modal tool (`ask_question`).
 - [ ] `.tidyfactor/marketing-brief.md` created or verified on disk.
-- [ ] Exactly 3 or fewer questions asked in a single round.
 - [ ] Regional calibration (GCC, Egypt, Global) explicitly recorded.
 - [ ] Brand voice archetype explicitly recorded.
-- [ ] Confirmed baseline summary displayed to user with next command suggestions (`/strategy`, `/advertising`, `/email`, `/content`).
+- [ ] Confirmed baseline summary displayed to user with next command suggestions.

package/references/workflows/campaign-launch.md

@@ -60,7 +60,7 @@ Before emitting the final strategy, evaluate against all 7 axes from `../memory/
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] Canonical positioning statement formulated with concrete proof (no generic slogans)

package/references/workflows/content-engine.md

@@ -56,7 +56,7 @@ Before emitting the final content assets, evaluate against all 7 axes from `../m
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] Every post includes a 0-3s attention hook matching platform specs

package/references/workflows/email-lifecycle.md

@@ -44,7 +44,7 @@ Before emitting the final email copy or flows, evaluate against all 7 axes from
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] Lead magnet promises a specific, actionable win achievable in < 10 minutes

package/references/workflows/paid-acquisition.md

@@ -54,7 +54,7 @@ Before emitting ad copy or landing page wireframes, evaluate against all 7 axes
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] At least 3 distinct psychological ad copy angles produced

package/references/workflows/promo-conversion.md

@@ -46,7 +46,7 @@ Before emitting pricing, promotions, or sale mechanics, evaluate against all 7 a
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] Discount structure verified against gross margins to prevent profit erosion

package/references/workflows/social-growth.md

@@ -53,7 +53,7 @@ Before emitting social media playbooks or profile copy, evaluate against all 7 a
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] Bio is optimized with clear target, authority proof, and single action CTA

package/references/workflows/viral-retention.md

@@ -51,7 +51,7 @@ Before emitting loyalty programs, referral systems, or outreach scripts, evaluat
 
 ---
 
-## Validation Checklist
+## Validation checklist
 
 - [ ] CDL brief parameters resolved from `.tidyfactor/marketing-brief.md` or prompt defaults
 - [ ] Retention drop-off point diagnosed before prescribing loyalty mechanics

package/scripts/audit_copy.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+TidyFactor Marketing Copy Quality Auditor
+Scans direct-response marketing copy, ad headlines, and landing page scripts
+for AI anti-patterns, banned cliches, robotic phrasing, and angle diversity.
+"""
+
+import sys
+import os
+import re
+import json
+import argparse
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows console
+if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+BANNED_AI_CLICHES = [
+    # English Slop
+    r"\bunleash\b", r"\belevate\b", r"\bgame-changer\b", r"\brevolutionize\b",
+    r"\bseamlessly\b", r"\btap into\b", r"\bdive deep\b", r"\bdelve into\b",
+    r"\bunlock your potential\b", r"\bin today's fast-paced world\b",
+    r"\blook no further\b", r"\bcutting-edge\b", r"\bstate-of-the-art\b",
+    # Arabic Slop
+    r"في عالمنا اليوم المتسارع", r"في عصر التكنولوجيا", r"أطلق العنان",
+    r"انغمس في", r"غيّر قواعد اللعبة", r"حلول سحرية", r"فريدة من نوعها",
+    r"نقدم لكم بكل فخر", r"لا داعي للبحث بعد الآن", r"بوابتك نحو"
+]
+
+def audit_text_content(text: str, file_name: str = "inline-copy") -> dict:
+    issues = []
+    lines = text.splitlines()
+    
+    # 1. Check for AI Cliches & Marketing Slop
+    for idx, line in enumerate(lines, start=1):
+        for pattern in BANNED_AI_CLICHES:
+            matches = re.finditer(pattern, line, re.IGNORECASE)
+            for m in matches:
+                issues.append({
+                    "type": "banned_cliche",
+                    "severity": "high",
+                    "line": idx,
+                    "matched": m.group(0),
+                    "message": f"Banned marketing cliché detected: '{m.group(0)}'. Replace with concrete proof or specific benefit."
+                })
+                
+    # 2. Check for Pre-emit critique stamp
+    has_critique = bool(re.search(r"/\*\s*Pre-emit critique:[^\*]+\*/", text, re.IGNORECASE))
+    if not has_critique and not text.startswith("#"):
+        issues.append({
+            "type": "missing_critique_stamp",
+            "severity": "medium",
+            "line": 1,
+            "message": "Missing 7-axis pre-emit critique stamp: /* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */"
+        })
+
+    # 3. Calculate Score
+    high_issues = [i for i in issues if i["severity"] == "high"]
+    med_issues = [i for i in issues if i["severity"] == "medium"]
+    
+    score = max(0, 100 - (len(high_issues) * 20) - (len(med_issues) * 10))
+    passed = len(high_issues) == 0 and score >= 80
+
+    return {
+        "file": file_name,
+        "score": score,
+        "passed": passed,
+        "total_issues": len(issues),
+        "issues": issues,
+        "timestamp": "2026-09-02T06:00:00Z"
+    }
+
+def main():
+    parser = argparse.ArgumentParser(description="TidyFactor Marketing Copy Auditor")
+    parser.add_argument("target", nargs="?", help="Path to copy file or markdown script")
+    parser.add_argument("--text", help="Direct copy string to audit")
+    parser.add_argument("--json", action="store_true", help="Output pure JSON format")
+
+    args = parser.parse_args()
+
+    if args.text:
+        content = args.text
+        filename = "string-input"
+    elif args.target and Path(args.target).exists():
+        target_path = Path(args.target)
+        content = target_path.read_text(encoding="utf-8", errors="replace")
+        filename = str(target_path)
+    else:
+        # Default sample check
+        content = "في عالمنا اليوم المتسارع، نقدم لكم بكل فخر الحل السحري لتغيير قواعد اللعبة."
+        filename = "demo-sample"
+
+    result = audit_text_content(content, filename)
+
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        status_str = "[PASS]" if result["passed"] else "[FAIL]"
+        print(f"\n{status_str} Marketing Copy Quality Audit — Score: {result['score']}/100")
+        print(f"Target: {result['file']}")
+        print(f"Issues Found: {result['total_issues']}\n")
+        for iss in result["issues"]:
+            print(f"  - [Line {iss.get('line', '?')}] [{iss['severity'].upper()}] {iss['message']}")
+        print()
+
+    sys.exit(0 if result["passed"] else 1)
+
+if __name__ == "__main__":
+    main()

package/scripts/calc_promo_math.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+TidyFactor Marketing Promotion & Margin Protection Calculator
+Calculates break-even ROAS, gross margin impact, and discount thresholds.
+"""
+
+import sys
+import json
+import argparse
+
+# Ensure UTF-8 output on Windows console
+if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+def calculate_promo_metrics(cogs: float, price: float, discount_percent: float, ad_spend_per_order: float = 0.0) -> dict:
+    if price <= 0:
+        raise ValueError("Price must be greater than 0")
+        
+    discount_amount = price * (discount_percent / 100.0)
+    discounted_price = price - discount_amount
+    gross_profit = discounted_price - cogs - ad_spend_per_order
+    gross_margin_percent = (gross_profit / discounted_price) * 100.0 if discounted_price > 0 else 0.0
+    
+    # Break-even ROAS = 1 / Gross Margin before ads
+    margin_before_ads = (discounted_price - cogs) / discounted_price if discounted_price > 0 else 0.0
+    breakeven_roas = (1.0 / margin_before_ads) if margin_before_ads > 0 else 0.0
+
+    is_margin_safe = gross_margin_percent >= 30.0 and gross_profit > 0
+
+    return {
+        "original_price": round(price, 2),
+        "discount_percent": round(discount_percent, 2),
+        "discount_amount": round(discount_amount, 2),
+        "discounted_price": round(discounted_price, 2),
+        "cogs": round(cogs, 2),
+        "ad_spend_per_order": round(ad_spend_per_order, 2),
+        "net_gross_profit": round(gross_profit, 2),
+        "net_gross_margin_percent": round(gross_margin_percent, 2),
+        "breakeven_roas": round(breakeven_roas, 2),
+        "is_margin_safe": is_margin_safe,
+        "recommendation": "SAFE_TO_RUN" if is_margin_safe else "HIGH_RISK_MARGIN_COMPRESSION"
+    }
+
+def main():
+    parser = argparse.ArgumentParser(description="TidyFactor Margin & Promo Calculator")
+    parser.add_argument("--price", type=float, default=100.0, help="Original product price")
+    parser.add_argument("--cogs", type=float, default=30.0, help="Cost of Goods Sold (COGS)")
+    parser.add_argument("--discount", type=float, default=20.0, help="Discount percentage (e.g. 20 for 20%)")
+    parser.add_argument("--cac", type=float, default=15.0, help="Estimated ad spend / CAC per order")
+    parser.add_argument("--json", action="store_true", help="Output pure JSON")
+
+    args = parser.parse_args()
+
+    result = calculate_promo_metrics(args.cogs, args.price, args.discount, args.cac)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("\n💰 TidyFactor Margin & Promotion Math Report")
+        print(f"  Price: ${result['original_price']} -> Discounted: ${result['discounted_price']} (-{result['discount_percent']}%)")
+        print(f"  COGS: ${result['cogs']} | Est. CAC: ${result['ad_spend_per_order']}")
+        print(f"  Net Gross Profit: ${result['net_gross_profit']} ({result['net_gross_margin_percent']}%)")
+        print(f"  Break-Even ROAS Target: {result['breakeven_roas']}x")
+        print(f"  Status: {result['recommendation']}\n")
+
+if __name__ == "__main__":
+    main()

package/scripts/clean_orphaned_assets.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+clean_orphaned_assets.py — TidyFactor Asset & Folder Structure Hygiene Engine.
+Detects and remediates:
+1. Binary duplicate image assets using SHA-256 hashing.
+2. Unreferenced orphan images in `assets/`.
+3. Advises WebP compression for raster assets > 50KB.
+"""
+
+import os
+import sys
+import hashlib
+import re
+import argparse
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows console
+if sys.platform == "win32":
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+def compute_sha256(filepath: Path) -> str:
+    h = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        while chunk := f.read(8192):
+            h.update(chunk)
+    return h.hexdigest()
+
+def scan_assets(root: Path):
+    assets_dir = root / "assets"
+    if not assets_dir.exists():
+        print("[INFO] No assets/ directory found.")
+        return 0
+
+    image_extensions = {".png", ".jpg", ".jpeg", ".webp", ".svg", ".gif"}
+    asset_files = [p for p in assets_dir.iterdir() if p.is_file() and p.suffix.lower() in image_extensions]
+
+    # 1. SHA-256 Duplication Check
+    hashes = {}
+    duplicates = []
+    for asset in asset_files:
+        digest = compute_sha256(asset)
+        if digest in hashes:
+            duplicates.append((asset, hashes[digest]))
+        else:
+            hashes[digest] = asset
+
+    # 2. Markdown Reference Check
+    md_files = list(root.rglob("*.md")) + [root / "brand.yaml", root / "brand.json"]
+    all_content = ""
+    for md in md_files:
+        if "dist" in md.parts or ".git" in md.parts or "__pycache__" in md.parts:
+            continue
+        if md.exists():
+            all_content += md.read_text(encoding="utf-8", errors="ignore") + "\n"
+
+    orphans = []
+    for asset in asset_files:
+        # Match asset name in text
+        if asset.name not in all_content:
+            orphans.append(asset)
+
+    print("=" * 60)
+    print("  TIDYFACTOR MARKETING ASSET HYGIENE AUDIT")
+    print("=" * 60)
+    print(f"Total assets analyzed: {len(asset_files)}")
+
+    print(f"\n[1] Duplicate Asset Check (SHA-256):")
+    if duplicates:
+        print(f"  [WARN] Found {len(duplicates)} duplicate asset(s):")
+        for dup, orig in duplicates:
+            print(f"    - {dup.name} is identical to {orig.name}")
+    else:
+        print("  [OK] Zero binary duplicates found.")
+
+    print(f"\n[2] Orphan Asset Check:")
+    if orphans:
+        print(f"  [WARN] Found {len(orphans)} unreferenced orphan asset(s):")
+        for orph in orphans:
+            print(f"    - {orph.name} ({orph.stat().st_size / 1024:.1f} KB)")
+    else:
+        print("  [OK] Zero unreferenced orphan assets found.")
+
+    print(f"\n[3] Large Raster File Check (>50KB):")
+    large_rasters = [a for a in asset_files if a.suffix.lower() in {".png", ".jpg", ".jpeg"} and a.stat().st_size > 50 * 1024]
+    if large_rasters:
+        for lr in large_rasters:
+            print(f"  [INFO] {lr.name}: {lr.stat().st_size / 1024:.1f} KB. Recommend WebP conversion for ~80% savings.")
+    else:
+        print("  [OK] All raster assets optimized or under 50KB.")
+
+    print("=" * 60)
+    return len(duplicates) + len(orphans)
+
+def main():
+    parser = argparse.ArgumentParser(description="TidyFactor Asset Hygiene Engine")
+    parser.add_argument("--check", action="store_true", help="Run audit and return non-zero if issues exist")
+    args = parser.parse_args()
+
+    root = Path(__file__).resolve().parent.parent
+    issues_count = scan_assets(root)
+
+    if args.check and issues_count > 0:
+        sys.exit(1)
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/tests/scenarios.md

@@ -0,0 +1,87 @@
+# Test Scenarios: tidyfactor-marketing
+
+Comprehensive evaluation scenarios validating deterministic command dispatch, Contextual Decision Layer auto-sensing, Arabic direct-response generation, margin math protection, and automated copy linting.
+
+---
+
+## Scenario 1: E-Commerce 72-Hour Flash Sale with Margin Guardrails (GCC / KSA 🇸🇦)
+
+### Objective
+Generate a margin-safe promotional strategy and high-urgency WhatsApp/Instagram copy for a Saudi Arabian DTC brand launching a 72-hour flash sale.
+
+### Inputs & Context
+- **Product**: Leather Travel Bag
+- **Price**: 400 SAR, **COGS**: 120 SAR, **Proposed Discount**: 25% (100 SAR off)
+- **Target Market**: Saudi Arabia (Riyadh, Jeddah)
+- **Channel**: WhatsApp Broadcast + Instagram Story Ads (9:16)
+
+### Expected Execution & Checks
+1. **Margin Safety Gate**: `calc_promo_math.py` confirms:
+   - Discounted Price: 300 SAR
+   - Net Gross Margin: 60% (>30% threshold)
+   - Status: `SAFE_TO_RUN`
+2. **Copy Generation**:
+   - High-urgency hook without slop (`"أطلق العنان"` ❌ forbidden).
+   - Trust and payment framing: Mada, Tabby, Tamara 4-installment split.
+   - 7-axis pre-emit critique stamp included.
+
+---
+
+## Scenario 2: B2B Multi-Tenant SaaS Phased Launch (Global / English)
+
+### Objective
+Formulate a complete T-30 to T+14 launch sequence, positioning statement, and competitive differentiation for an AI agent observability tool.
+
+### Inputs & Context
+- **Product**: AgentTrace (Observability for AI Coding Agents)
+- **Pricing**: $49/seat/month
+- **Primary Moat**: Zero-runtime latency, SQLite-native trace indexing.
+
+### Expected Execution & Checks
+1. **Positioning Matrix**: Formulates statement: *For [engineering leaders] who [struggle with invisible agent regressions], [AgentTrace] is an [observability engine] that [indexes traces locally in SQLite with 0ms runtime overhead] unlike [Datadog/LangSmith]*.
+2. **Phased Roadmap**:
+   - T-30 to T-15: Technical teardown blogs and waitlist alpha.
+   - T-14 to T-1: Private beta with 50 design partners.
+   - T-0: Product Hunt, Hacker News Show HN, and Twitter thread.
+   - T+1 to T+14: Onboarding case studies and customer referral loop.
+3. **Checklist Validation**: Workflow satisfies 100% of `references/workflows/campaign-launch.md` checklist.
+
+---
+
+## Scenario 3: 3-Stage Abandoned Cart Recovery Sequence (Egypt 🇪🇬)
+
+### Objective
+Build a culturally calibrated 3-email abandoned cart recovery flow for an Egyptian fashion brand utilizing local payment incentives (InstaPay, Cash on Delivery).
+
+### Inputs & Context
+- **Market**: Egypt (Cairo, Alexandria)
+- **Currency**: EGP
+- **Average Order Value**: 850 EGP
+- **Tone**: Friendly, relatable, solution-oriented Egyptian Arabic.
+
+### Expected Execution & Checks
+1. **Flow Structure**:
+   - Email 1 (1 hour post-abandonment): Gentle reminder, photo of cart items, customer service WhatsApp link.
+   - Email 2 (24 hours post-abandonment): Overcoming objections, sizing guide, InstaPay instant discount.
+   - Email 3 (48 hours post-abandonment): Final urgency notice, reserving items for 12 hours.
+2. **Quality Bar**: Free of generic translation artifacts; utilizes authentic Egyptian phrasing with clear CTAs.
+
+---
+
+## Scenario 4: Direct-Response Ad Copy Multi-Angle Audit
+
+### Objective
+Generate 3 distinct psychological ad copy angles (Pain, ROI, Proof) and verify zero AI marketing clichés via automated linter.
+
+### Inputs & Context
+- **Offer**: Fast-track web performance audit service.
+- **Audience**: Agency owners and e-commerce founders.
+
+### Expected Execution & Checks
+1. **Angles Emitted**:
+   - Angle 1 (Pain): Frustration of paying high Meta ad spend while 60% bounce on slow mobile pages.
+   - Angle 2 (ROI/Logic): Every 100ms speed improvement raises conversion rate by 1.1%, recovering lost ad spend.
+   - Angle 3 (Social Proof): Before/after case study showing Lighthouse score 34 → 98 and 2.4x ROAS increase.
+2. **Linter Execution**:
+   - Runs `python scripts/audit_copy.py target.md --json`.
+   - Result: `passed: true`, `score: 100`, zero banned clichés detected.

package/tools/build-skill.js

@@ -28,10 +28,14 @@ const OUT_FILE =
 const ROOT_COPIES = [
   "SKILL.md",
   "references",
+  "scripts",
+  "manifest.json",
   "tools",
   "bin",
   "assets",
+  "brand.yaml",
   "brand.json",
+  "tests",
   ".tidyfactor",
   "package.json",
   "AGENTS.md",