@tidyfactor/marketing 1.3.0

package/bin/create-kit.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+/* Lightweight Zero-Dependency ANSI formatting */
+const chalk = {
+  cyan: (str) => `\x1b[36m${str}\x1b[0m`,
+  green: (str) => `\x1b[32m${str}\x1b[0m`,
+  yellow: (str) => `\x1b[33m${str}\x1b[0m`,
+  red: (str) => `\x1b[31m${str}\x1b[0m`,
+  bold: (str) => `\x1b[1m${str}\x1b[0m`,
+  dim: (str) => `\x1b[2m${str}\x1b[0m`,
+};
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const pkg = require(path.join(PACKAGE_ROOT, 'package.json'));
+
+console.log(chalk.bold(chalk.cyan(`\n======================================================`)));
+console.log(chalk.bold(chalk.cyan(`  TidyFactor Marketing Engine — CLI Setup (v${pkg.version})`)));
+console.log(chalk.bold(chalk.cyan(`======================================================\n`)));
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const ask = (query, defaultVal) =>
+  new Promise((resolve) => {
+    rl.question(chalk.yellow(`${query} `) + (defaultVal ? chalk.dim(`[${defaultVal}]: `) : ''), (answer) => {
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+
+async function main() {
+  const targetDirInput = await ask('1. Target Directory to initialize marketing engine:', './');
+  const targetDir = path.resolve(process.cwd(), targetDirInput);
+
+  console.log(chalk.cyan('\nSelect Primary Target Market:'));
+  console.log('  1) Global / Western (English Direct Response)');
+  console.log('  2) MENA / GCC (Arabic Modern Standard + Regional Payments)');
+  console.log('  3) Dual Bilingual (English + Arabic Parity)');
+  const marketChoice = await ask('Select market (1-3):', '3');
+
+  console.log(chalk.cyan('\nSelect Primary Growth Focus:'));
+  console.log('  1) B2B SaaS & Enterprise (LinkedIn, Cold InMail, Demo Funnels)');
+  console.log('  2) E-Commerce & DTC (Meta/TikTok Ads, Abandoned Cart, UGC)');
+  console.log('  3) High-Ticket Services / Info-Products (Webinars, VSLs, Email Drips)');
+  console.log('  4) Full 360° Growth Suite (All 7 Pillars)');
+  const focusChoice = await ask('Select focus (1-4):', '4');
+
+  console.log(chalk.green(`\nInitializing TidyFactor Marketing Engine in: ${targetDir}...`));
+
+  // Copy references and SKILL.md to target directory .agents/skills/tidyfactor-marketing
+  const skillDestDir = path.join(targetDir, '.agents', 'skills', 'tidyfactor-marketing');
+  fs.mkdirSync(skillDestDir, { recursive: true });
+
+  const filesToCopy = ['SKILL.md', 'package.json', 'README.md', 'README.ar.md', 'LICENSE', 'brand.json', '.tidyfactor'];
+  for (const f of filesToCopy) {
+    const srcFile = path.join(PACKAGE_ROOT, f);
+    if (fs.existsSync(srcFile)) {
+      fs.copyFileSync(srcFile, path.join(skillDestDir, f));
+    }
+  }
+
+  // Copy references recursively
+  const copyDir = (src, dest) => {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const item of fs.readdirSync(src)) {
+      const srcItem = path.join(src, item);
+      const destItem = path.join(dest, item);
+      if (fs.statSync(srcItem).isDirectory()) {
+        copyDir(srcItem, destItem);
+      } else {
+        fs.copyFileSync(srcItem, destItem);
+      }
+    }
+  };
+
+  copyDir(path.join(PACKAGE_ROOT, 'references'), path.join(skillDestDir, 'references'));
+
+  console.log(chalk.bold(chalk.green('\n✅ TidyFactor Marketing Engine installed successfully!')));
+  console.log(chalk.dim(`Installed at: ${skillDestDir}`));
+  console.log(chalk.cyan('\n🚀 Available Slash Commands:'));
+  console.log('  - /marketing strategy      -> Brand Positioning & Launch Plans');
+  console.log('  - /marketing content       -> Multi-Platform Content & SEO Topic Clusters');
+  console.log('  - /marketing social        -> LinkedIn B2B & Instagram/TikTok Hooks');
+  console.log('  - /marketing email         -> Welcome Drips & Cart Recovery Flows');
+  console.log('  - /marketing ads           -> 3-Angle Ad Copy Matrices & CRO Audits');
+  console.log('  - /marketing promo         -> 72-Hour Flash Sales & Decoy Pricing');
+  console.log('  - /marketing growth        -> Retention, Churn Reduction & Referral Loops\n');
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error(chalk.red(`\n❌ Error: ${err.message}`));
+  rl.close();
+  process.exit(1);
+});

package/bin/remove-skill.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+/* Lightweight Zero-Dependency ANSI formatting */
+const chalk = {
+  cyan: (str) => `\x1b[36m${str}\x1b[0m`,
+  green: (str) => `\x1b[32m${str}\x1b[0m`,
+  yellow: (str) => `\x1b[33m${str}\x1b[0m`,
+  red: (str) => `\x1b[31m${str}\x1b[0m`,
+  bold: (str) => `\x1b[1m${str}\x1b[0m`,
+  dim: (str) => `\x1b[2m${str}\x1b[0m`,
+};
+
+const targetDir = process.cwd();
+const skillDestDir = path.join(targetDir, '.agents', 'skills', 'tidyfactor-marketing');
+
+if (fs.existsSync(skillDestDir)) {
+  fs.rmSync(skillDestDir, { recursive: true, force: true });
+  console.log(chalk.bold(chalk.yellow(`\n🗑️ Removed TidyFactor Marketing Skill from .agents/skills/tidyfactor-marketing\n`)));
+} else {
+  console.log(chalk.dim(`\nNo TidyFactor Marketing Skill found at: ${skillDestDir}\n`));
+}

package/brand.json

@@ -0,0 +1,67 @@
+{
+  "name": "TidyFactor Marketing",
+  "version": "1.3.0",
+  "schemaVersion": "brand-core-v2",
+  "meta": {
+    "product": "TidyFactor Marketing Engine",
+    "tagline": "AI Direct Response & 360° Growth Marketing Engine",
+    "description": "A production-grade, AI-native marketing and growth engine following TidyFactor Skill architecture. Handles 7 pillars and 28 capabilities with zero fluff, data-backed metrics, quantitative benchmarks, and platform-native direct-response conversion frameworks.",
+    "version": "1.1.1",
+    "lastUpdated": "2026-08-25"
+  },
+  "identity": {
+    "logo": {
+      "full": "assets/logo.svg",
+      "fullDark": "assets/logo-dark.svg",
+      "mark": "assets/logo-mark.svg",
+      "favicon": "assets/favicon.svg",
+      "minClearSpace": "1x logo-mark height on all sides",
+      "minSizePx": 24
+    },
+    "socialPreview": {
+      "ogImage": "assets/og-default.png",
+      "ogDimensions": "1200x630"
+    }
+  },
+  "voice": {
+    "tone": "direct, evidence-first, quantitative, authentic, teacher-practitioner",
+    "vocabulary": {
+      "preferred": [
+        "direct response",
+        "conversion rate",
+        "margin protection",
+        "CAC payback",
+        "LTV:CAC",
+        "ROAS",
+        "anti-cliché",
+        "pillar-cluster",
+        "search intent",
+        "retention loop"
+      ],
+      "banned": [
+        "cutting-edge",
+        "seamless experience",
+        "innovative solutions",
+        "take your business to the next level",
+        "one-stop shop",
+        "نسعى دائماً لتقديم الأفضل",
+        "فريق من الخبراء",
+        "حلول متكاملة ومبتكرة"
+      ]
+    },
+    "principles": [
+      "Every sentence must carry a mechanism, a concrete number, or a verifiable proof point.",
+      "Never price cut without calculating unit gross margin impact.",
+      "Respect audience attention with high-signal, zero-throat-clearing direct copy."
+    ]
+  },
+  "pillars": {
+    "1_strategy": "Brand Voice, Positioning Statement, Competitive Differentiation, Phased Launch (T-30 to T+14)",
+    "2_content": "Pillar + Cluster SEO, Multi-Platform Posts, Publishing Grids, Newsletters",
+    "3_social": "LinkedIn B2B & Founder Personal Branding, Instagram/TikTok 0-3s Hooks, 0-1k Roadmap",
+    "4_email": "Lead Magnet Mechanics, 5-Email Welcome Flow, 3-Stage Cart Recovery, Win-Back Sequences",
+    "5_advertising": "3-Angle Ad Copy Matrices, 7-Dimension CRO Landing Page Wireframes, Meta & Google Ads",
+    "6_promotions": "72-Hour Flash Sales, Decoy Pricing Architecture, Viral Contests, Margin-Safe Coupons",
+    "7_growth": "2-Sided Viral Referral Loops, Influencer Vetting & Cold Outreach, Retention & Churn Diagnosis"
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@tidyfactor/marketing",
+  "version": "1.3.0",
+  "description": "TidyFactor Marketing — AI Direct-Response Marketing, Pillar-Cluster SEO & Multi-Channel Growth Engine with Contextual Decision Layer (CDL)",
+  "main": "SKILL.md",
+  "bin": {
+    "tidyfactor-marketing": "./bin/create-kit.js",
+    "add-skill": "./bin/add-skill.js",
+    "remove-skill": "./bin/remove-skill.js"
+  },
+  "scripts": {
+    "validate": "python tools/validate_skill.py",
+    "build": "node tools/build-skill.js",
+    "release": "python ../tools/release_skill.py .",
+    "start": "node bin/create-kit.js",
+    "add-skill": "node bin/add-skill.js",
+    "remove-skill": "node bin/remove-skill.js"
+  },
+  "keywords": [
+    "tidyfactor",
+    "marketing",
+    "growth",
+    "direct-response",
+    "copywriting",
+    "seo",
+    "b2b-marketing",
+    "linkedin",
+    "retention",
+    "loyalty",
+    "pricing",
+    "cro",
+    "meta-ads",
+    "google-ads"
+  ],
+  "author": "TidyFactor <hello@tidyfactor.com> (https://tidyfactor.com)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TidyFactor/Marketing.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/TidyFactor/Marketing/issues"
+  },
+  "homepage": "https://tidyfactor.com",
+  "files": [
+    ".tidyfactor",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.ar.md",
+    "README.de.md",
+    "README.es.md",
+    "README.fa.md",
+    "README.fr.md",
+    "README.md",
+    "README.pt.md",
+    "README.zh.md",
+    "SKILL-REGISTRY.md",
+    "SKILL.md",
+    "VISION.md",
+    "assets",
+    "bin",
+    "brand.json",
+    "references",
+    "tools"
+  ]
+}

package/references/commands/advertising.md

@@ -0,0 +1,27 @@
+# Command: advertising
+
+Runtime dispatcher for Direct Response Ad Copy (Meta/Facebook, Google Ads, TikTok), Landing Page Wireframe Messaging, and Campaign Scaling Architectures.
+
+---
+
+## Capabilities Handled
+
+1. **Write Ad Copy**: 3 distinct psychological angles (Pain/Loss Aversion, Logic/ROI/Efficiency, Aspirational/Social Proof) with anti-cliché replacements.
+2. **Landing Page Strategy**: 8-section high-converting wireframe messaging (Hero, Proof Bar, Contrast Table, Benefits, Reviews, Pricing Stack, FAQs, CTA).
+3. **Google Ads (RSA)**: 15 diverse headlines + 4 descriptions + negative keyword lists.
+4. **Meta Ads Plan**: Creative format mix (UGC, Statics, Carousels), Advantage+ budget scaling, and stop-loss kill rules.
+5. **First Ad Campaign**: 72-hour test budget blueprint with creative testing matrix.
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/paid-acquisition.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/ad-copy-templates.md` + `../memory/metrics-benchmarks.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/social-growth.md` (organic social profile growth is handled by `../commands/social.md`).
+- Do not load `../workflows/email-lifecycle.md` (email onboarding sequences are handled by `../commands/email.md`).

package/references/commands/brief.md

@@ -0,0 +1,17 @@
+# Marketing Brief Command (`/brief`)
+
+> **Dispatches to**: `references/workflows/brief.md`
+> **Memory Loaded**: `references/memory/decision-points.md` + `references/memory/quality-bar.md` + `references/memory/frameworks.md`
+
+---
+
+## 🎯 Command Intent
+Conducts a rapid, structured 3-question marketing discovery interview to establish strategic parameters (Market, Voice, Funnel Stage, Offer) and writes `.tidyfactor/marketing-brief.md` as the authoritative baseline for all subsequent campaigns, ads, emails, and content generation.
+
+---
+
+## ⚡ Execution Protocol
+1. Load `references/memory/decision-points.md`.
+2. Execute `references/workflows/brief.md`.
+3. Save resulting decisions into `.tidyfactor/marketing-brief.md`.
+4. Conclude with a clear brief summary.

package/references/commands/content.md

@@ -0,0 +1,26 @@
+# Command: content
+
+Runtime dispatcher for Social Media Content Batches, SEO Strategy & Pillar Pages, Content Calendars, and Newsletter Strategy.
+
+---
+
+## Capabilities Handled
+
+1. **Social Media Content Batch**: Multi-platform post batches with 3-second hooks, line-break rhythm, and actionable CTAs.
+2. **SEO Strategy (Pillar + Cluster)**: Pillar page architecture, long-tail cluster topics, search intent mapping (Informational, Commercial, Transactional).
+3. **Content Calendar**: Weekly/monthly scheduling grids with content pillars (Authority, Contrarian, Tactical, Culture).
+4. **Newsletter Strategy**: High-open newsletter layouts (Curiosity A/B subject lines, Hook-Story-Offer narrative, primary CTAs).
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/content-engine.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/frameworks.md` + `../memory/platform-specs.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/paid-acquisition.md` or `../memory/ad-copy-templates.md` (paid ad campaigns are handled by `../commands/advertising.md`).
+- Do not load `../workflows/email-lifecycle.md` (automated drip onboarding sequences are handled by `../commands/email.md`).

package/references/commands/email.md

@@ -0,0 +1,26 @@
+# Command: email
+
+Runtime dispatcher for Email List Growth, 5-Part Welcome Sequences, Abandoned Cart Recoveries, and Broadcast Campaigns.
+
+---
+
+## Capabilities Handled
+
+1. **Grow Email List**: High-converting lead magnet design, low-friction opt-in copy, and placement strategy (exit popup, sticky bar).
+2. **Welcome Email Sequence**: 5-part indoctrination drip (Day 0 Delivery, Day 1 Origin Story, Day 2 Myth Busting, Day 3 Case Study, Day 4 Invitation).
+3. **Abandoned Cart Emails**: 3-stage sequential recovery flow (Hour 1 Support -> Hour 24 Social Proof -> Hour 48 Urgency Discount).
+4. **Win-Back Flows**: Inactive subscriber reactivation sequences.
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/email-lifecycle.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/lifecycle-flows.md` + `../memory/frameworks.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/paid-acquisition.md` (paid traffic acquisition is handled by `../commands/advertising.md`).
+- Do not load `../workflows/promo-conversion.md` (detailed discount unit economics are handled by `../commands/promotions.md`).

package/references/commands/growth.md

@@ -0,0 +1,27 @@
+# Command: growth
+
+Runtime dispatcher for Customer Retention, Churn Reduction, Loyalty Programs, 2-Sided Referral Programs, Influencer Outreach, and Brand Awareness.
+
+---
+
+## Capabilities Handled
+
+1. **Customer Retention & Reduce Churn**: Drop-off diagnosis across SaaS, E-Commerce, and Service business models.
+2. **Loyalty Program Design**: Points, Tiered Status, Cashback, or Perks-Based architectures.
+3. **2-Sided Referral Program**: "Give $X, Get $Y" customer referral loops with gamified milestone unlocks.
+4. **Influencer Outreach**: Quantitative vetting scorecard and cold outreach DM/email scripts.
+5. **Brand Awareness & Distribution**: Podcast pitching, co-marketing webinars, and 1-to-many repurposing flywheels.
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/viral-retention.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/frameworks.md` + `../memory/metrics-benchmarks.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/promo-conversion.md` (flash seasonal discounts are handled by `../commands/promotions.md`).
+- Do not load `../workflows/content-engine.md` (organic social post writing is handled by `../commands/content.md`).

package/references/commands/promotions.md

@@ -0,0 +1,26 @@
+# Command: promotions
+
+Runtime dispatcher for Flash Sales, Seasonal Promotions, Decoy Pricing Structures, Viral Contests, and Margin-Safe Coupon Strategies.
+
+---
+
+## Capabilities Handled
+
+1. **Plan a Sale / Flash Sales**: 72-hour countdown promotion execution timeline (Teaser, Launch Day, Momentum, Hard Close).
+2. **Margin-Safe Coupon Strategy**: Contribution margin safeguards and threshold-based bundling ("Spend $100 Get $15").
+3. **Decoy Pricing & Anchoring**: 3-tier Good/Better/Best table design with decoy placement and annual discount framing.
+4. **Giveaway / Contest Architecture**: Dream customer niche prizes, viral referral loops, and non-winner consolation offers.
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/promo-conversion.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/promotions-math.md` + `../memory/frameworks.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/paid-acquisition.md` (paid ad traffic management is handled by `../commands/advertising.md`).
+- Do not load `../workflows/viral-retention.md` (standing affiliate loyalty loops are handled by `../commands/growth.md`).

package/references/commands/social.md

@@ -0,0 +1,27 @@
+# Command: social
+
+Runtime dispatcher for LinkedIn B2B Thought Leadership, Founder Personal Branding, Instagram/TikTok Strategy, Social Media Audits, and Growth Sprints.
+
+---
+
+## Capabilities Handled
+
+1. **LinkedIn B2B & Founder Personal Branding**: Personal vs company page strategy, 4 B2B post types, 3-touch outbound outreach cadence.
+2. **Instagram & TikTok Strategy**: 5 short-form video hooks, visual directions, posting cadences, and daily Story engagement playbooks.
+3. **Social Media Audit**: Conversion audit of bio, handle, CTA links, and pinned story highlights.
+4. **First 1,000 Followers Roadmap**: 60-day cold-start organic sprint ($1.80 strategy, collaborative flywheels).
+5. **Hashtag Strategy**: 3-tier hashtag taxonomy (Broad, Niche, Micro/Branded).
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/social-growth.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/platform-specs.md` + `../memory/frameworks.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/paid-acquisition.md` (paid Meta/TikTok ad creative is handled by `../commands/advertising.md`).
+- Do not load `../workflows/viral-retention.md` (customer referral programs are handled by `../commands/growth.md`).

package/references/commands/strategy.md

@@ -0,0 +1,25 @@
+# Command: strategy
+
+Runtime dispatcher for Brand Voice, Market Positioning, Campaign Strategy, and Product Launch Plans.
+
+---
+
+## Capabilities Handled
+
+1. **Brand Voice & Positioning**: Core positioning statement, competitive differentiation matrix (own 1 attribute), tone-of-voice pillars by contrast, and channel tone flex.
+2. **Campaign Strategy**: Multi-channel marketing plan with target audience, channel budget distribution, messaging pillars, and target KPIs.
+3. **Product Launch Plan**: Phased timeline (Pre-launch waitlist T-30, Launch day blitz T-0, Post-launch momentum T+14).
+
+---
+
+## What It Loads
+
+- **Workflow**: `../workflows/campaign-launch.md`
+- **Memory**: `../memory/decision-points.md` + `../memory/quality-bar.md` + `../memory/frameworks.md` + `../memory/metrics-benchmarks.md`
+
+---
+
+## What It Does NOT Load
+
+- Do not load `../workflows/paid-acquisition.md` or `../memory/ad-copy-templates.md` (detailed ad copy copywriting is handled by `../commands/advertising.md`).
+- Do not load `../workflows/content-engine.md` (batch social post calendars are handled by `../commands/content.md`).

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

@@ -0,0 +1,93 @@
+# 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

@@ -0,0 +1,71 @@
+# Arabic Direct-Response & Copywriting Engineering
+
+<!-- last-verified: 2026-08-29 -->
+
+Deterministic rules and linguistic frameworks for composing Arabic marketing, growth, and conversion copy natively without translation artifacts.
+
+---
+
+## 1. Register & Linguistic Taxonomy
+
+Unless explicitly directed to use a localized dialect, default to **Modern Standard Arabic (الفصحى المعاصرة الرنانة)**:
+- Direct, clear, modern business Arabic.
+- Zero flowery classical rhetoric or archaic vocabulary.
+- Active voice over passive voice.
+
+### Grammar & Linguistic Integrity Rules
+
+| Category | High-Converting Standard | Slop / Failure Pattern |
+|---|---|---|
+| **Voice** | Active: `نساعدك على مضاعفة مبيعاتك` | Passive: `يتم تقديم المساعدة لزيادة المبيعات` ❌ |
+| **Pronominal Efficiency** | Streamlined verbs: `نبني، نطور، نطلق` | Over-indexing on `نحن`: `نحن نبني ونحن نطور` ❌ |
+| **Agreement** | Proper gender/number agreement (`الشركات الرائدة`) | Broken agreement (`الشركات الرائد`) ❌ |
+| **Idafa (الإضافة)** | Tight construct: `منصة إدارة الحملات` | False construct: `منصة الإدارة للحملات` ❌ |
+| **Punctuation** | Native Arabic: `،` (فاصلة), `؛` (منقوطة), `؟` (استفهام) | English punctuation in Arabic text ❌ |
+| **Digits** | Western digits (`1, 2, 3`) for web/mobile UI conversion | Mixing Indic digits in modern digital apps |
+
+---
+
+## 2. Dialectical Voice Calibration
+
+When a campaign explicitly targets regional consumer vernacular, calibrate the **Tone and Conversational Connectors** only — preserve grammatical rigor and offer structure:
+
+| Market | Target Vernacular | High-Performing Channel | Dialectical Guidance |
+|---|---|---|---|
+| 🇪🇬 **Egypt** | Egyptian العامية المصرية | Social Content, TikTok, Meta Ads, WhatsApp | Natural conversational flow, warmth, humor, value-first clarity. Keep core B2B value proposition in clear simplified Fus'ha. |
+| 🇸🇦 **Saudi Arabia / Gulf** | Khaleeji اللهجة الخليجية البيضاء | Snapchat Ads, TikTok, Instagram | Polite, welcoming, premium, respect-driven. Highlight convenience, status, and local relevance. |
+| 🇱🇾 **Libya / Maghreb** | Simplified Fus'ha فصحى مبسطة | Meta Ads, WhatsApp Direct | Clean Fus'ha with direct, trust-building commercial terms. |
+| 🌐 **Multi-Market MENA** | Pan-Arab Fus'ha فصحى معاصرة موحدة | Landing Pages, B2B SaaS, Pitch Decks | The universal conversion standard across all 22 Arab countries. |
+
+---
+
+## 3. High-Converting Arabic Copywriting Formulas
+
+### A. PAS (المشكلة ➔ الإثارة ➔ الحل)
+```text
+1. Problem (المشكلة): "هل تعاني من إهدار ميزانية الإعلانات دون تحقيق مبيعات فعلية؟"
+2. Agitation (الإثارة): "كل يوم يمر دون تتبع دقيق للتحويلات، تدفع فيه لمنصات الإعلانات أكثر مما تكسب."
+3. Solution (الحل): "نظام TidyFactor للتسويق الدقيق يمنحك لوحة تحكم واحدة لتوجيه كل دولار نحو العميل الأكثر ربحية."
+```
+
+### B. AIDA (الانتباه ➔ الاهتمام ➔ الرغبة ➔ الإجراء)
+```text
+1. Attention (انتباه): "ضاعف معدل تحويل متجرك بـ 3 تعديلات بسيطة فقط."
+2. Interest (اهتمام): "أكثر من 80% من زوار المتاجر في الخليج يتركون السلة بسبب غياب خيارات الدفع المحلية (Mada, Tabby, Apple Pay)."
+3. Desire (رغبة): "وفر لعملائك تجربة دفع في خطوة واحدة وارفع مبيعاتك بنسبة تصل إلى 38% خلال 14 يوماً."
+4. Action (إجراء): "ابدأ تجربتك المجانية اليوم — بدون بطاقة ائتمانية."
+```
+
+---
+
+## 4. Anti-Slop Banned Phrases (Arabic Marketing)
+
+Reject all empty AI marketing clichés:
+- ❌ `في عالمنا اليوم المتسارع...`
+- ❌ `نحن فخورون بتقديم أفضل الخدمات المبتكرة والفريدة من نوعها...`
+- ❌ `انضم إلى الثورة الرقمية مع حلولنا الاستثنائية...`
+- ❌ `بوابتك نحو النجاح والتميز بلا حدود...`
+
+**Replace with Concrete Data & Specific Outcomes:**
+- ✅ `نظام مؤتمت يقلل تكلفة الاستحواذ على العميل (CAC) بنسبة 25%.`
+- ✅ `أطلق حملتك الإعلانية خلال 48 ساعة مع 3 زوايا إبداعية مجربة.`