@tidyfactor/marketing 1.3.0 → 1.6.0

package/brand.yaml

@@ -0,0 +1,55 @@
+name: "TidyFactor Marketing"
+version: "1.6.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.6.0"
+  lastUpdated: "2026-09-09"
+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/hero-banner.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/manifest.json

@@ -0,0 +1,256 @@
+{
+  "manifest_schema_version": "1.1.0",
+  "skill_id": "tidyfactor-marketing",
+  "skill_root_anchor": "self",
+  "tools": [
+    {
+      "name": "audit_copy",
+      "description": "Audits direct-response marketing copy against AI anti-patterns, banned cliches, tone rules, and 7-axis critique stamps.",
+      "entrypoint": {
+        "runtime": "python3",
+        "script": "scripts/audit_copy.py"
+      },
+      "invocation": {
+        "cli_pattern": "{runtime} {skill_root}/{script} {target_path} {flags}",
+        "args": [
+          {
+            "name": "target",
+            "type": "path",
+            "required": true,
+            "description": "Path to marketing copy file or markdown file to audit"
+          },
+          {
+            "name": "json",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "flag": "--json",
+            "description": "Output structured JSON report"
+          }
+        ]
+      },
+      "output": {
+        "format": "json",
+        "channel": "stdout"
+      },
+      "runtime_requirements": {
+        "isolation_recommended": false,
+        "dependencies": []
+      },
+      "invoked_by_commands": ["content", "advertising", "email", "audit"]
+    },
+    {
+      "name": "calc_promo_math",
+      "description": "Calculates unit economics, gross margins, break-even ROAS targets, and discount safety thresholds.",
+      "entrypoint": {
+        "runtime": "python3",
+        "script": "scripts/calc_promo_math.py"
+      },
+      "invocation": {
+        "cli_pattern": "{runtime} {skill_root}/{script} {flags}",
+        "args": [
+          {
+            "name": "price",
+            "type": "number",
+            "required": true,
+            "flag": "--price",
+            "description": "Original retail product price"
+          },
+          {
+            "name": "cogs",
+            "type": "number",
+            "required": true,
+            "flag": "--cogs",
+            "description": "Cost of Goods Sold (COGS)"
+          },
+          {
+            "name": "discount",
+            "type": "number",
+            "required": false,
+            "flag": "--discount",
+            "description": "Discount percentage"
+          },
+          {
+            "name": "cac",
+            "type": "number",
+            "required": false,
+            "flag": "--cac",
+            "description": "Estimated Customer Acquisition Cost (CAC)"
+          },
+          {
+            "name": "json",
+            "type": "boolean",
+            "required": false,
+            "default": true,
+            "flag": "--json",
+            "description": "Output structured JSON metrics"
+          }
+        ]
+      },
+      "output": {
+        "format": "json",
+        "channel": "stdout"
+      },
+      "runtime_requirements": {
+        "isolation_recommended": false,
+        "dependencies": []
+      },
+      "invoked_by_commands": ["promotions", "growth"]
+    },
+    {
+      "name": "clean_orphaned_assets",
+      "description": "Scans image assets for SHA-256 binary duplicates, unreferenced orphan files, and compression opportunities.",
+      "entrypoint": {
+        "runtime": "python3",
+        "script": "scripts/clean_orphaned_assets.py"
+      },
+      "invocation": {
+        "cli_pattern": "{runtime} {skill_root}/{script} {flags}",
+        "args": [
+          {
+            "name": "check",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "flag": "--check",
+            "description": "Run check mode returning non-zero if issues exist"
+          }
+        ]
+      },
+      "output": {
+        "format": "text",
+        "channel": "stdout"
+      },
+      "runtime_requirements": {
+        "isolation_recommended": false,
+        "dependencies": []
+      },
+      "invoked_by_commands": ["audit"]
+    }
+  ],
+  "decision_gates": [
+    {
+      "command": "brief",
+      "description": "Decision gate evaluating market context, audience register, brand voice, and offer model before marketing copy generation.",
+      "decisions": [
+        {
+          "key": "target_market",
+          "description": "Target regional market and cultural calibration",
+          "type": "enum",
+          "options": ["gcc", "egypt_levant", "global_saas", "bilingual_mena"],
+          "default": "bilingual_mena",
+          "priority": 1,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "brand.yaml",
+              "json_path": "$.targetMarket",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "brand.json",
+              "json_path": "$.targetMarket",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "BRAND-GUIDELINES.md",
+              "track_staleness": true
+            },
+            {
+              "source": "brain_ki",
+              "ki_type": "project"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/marketing-brief.snapshot.yaml" },
+            "brain_ki": {
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        },
+        {
+          "key": "brand_voice",
+          "description": "Brand voice archetype and tone register",
+          "type": "enum",
+          "options": ["authoritative_challenger", "empathetic_guide", "elite_luxury", "high_energy_direct_response"],
+          "default": "authoritative_challenger",
+          "priority": 2,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "brand.yaml",
+              "json_path": "$.voice.archetype",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "brand.json",
+              "json_path": "$.voice.archetype",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "BRAND-GUIDELINES.md",
+              "track_staleness": true
+            },
+            {
+              "source": "brain_ki",
+              "ki_type": "project"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/marketing-brief.snapshot.yaml" },
+            "brain_ki": {
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        },
+        {
+          "key": "funnel_stage",
+          "description": "Primary conversion funnel focus",
+          "type": "enum",
+          "options": ["tofu_lead_magnet", "mofu_trial_demo", "bofu_direct_sale"],
+          "default": "bofu_direct_sale",
+          "priority": 3,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": ".tidyfactor/marketing-brief.md"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/marketing-brief.snapshot.yaml" }
+          }
+        },
+        {
+          "key": "core_offer",
+          "description": "Value proposition and main transaction vehicle",
+          "type": "string",
+          "default": "Direct Product Offer",
+          "priority": 4,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "brand.yaml",
+              "json_path": "$.offer.headline",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "brand.json",
+              "json_path": "$.offer.headline",
+              "track_staleness": true
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/marketing-brief.snapshot.yaml" }
+          }
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/marketing",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "description": "TidyFactor Marketing — AI Direct-Response Marketing, Pillar-Cluster SEO & Multi-Channel Growth Engine with Contextual Decision Layer (CDL)",
   "main": "SKILL.md",
   "bin": {
@@ -66,8 +66,12 @@
     "VISION.md",
     "assets",
     "bin",
+    "brand.yaml",
     "brand.json",
+    "manifest.json",
     "references",
+    "scripts",
+    "tests",
     "tools"
   ]
 }

package/references/commands/audit.md

@@ -0,0 +1,34 @@
+# Command: audit
+
+Audits marketing copy, ad headlines, landing pages, and email drafts for AI clichés, banned fluff, and compliance with the 7-axis pre-emit critique stamp (`P5 H5 E5 S5 R5 V5 D5`).
+
+---
+
+## What It Loads
+
+- **Script**: `scripts/audit_copy.py`
+- **Memory**: `references/memory/quality-bar.md`
+- **Memory**: `references/memory/arabic-writing.md`
+
+---
+
+## Execution Pattern
+
+### 1. Direct Target File Audit
+```bash
+python scripts/audit_copy.py path/to/marketing-copy.md --json
+```
+
+### 2. Inline Copy String Audit
+```bash
+python scripts/audit_copy.py --text "Unleash your business with our game-changing platform" --json
+```
+
+---
+
+## Validation checklist
+
+- [ ] Command routes deterministically to `scripts/audit_copy.py`.
+- [ ] Returns structured JSON with line numbers, severity, and matched patterns.
+- [ ] Validates 7-axis pre-emit critique stamp presence.
+- [ ] Reports zero false positives on clean technical copy.

package/references/commands/brief.md

@@ -6,12 +6,14 @@
 ---
 
 ## 🎯 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.
+Conducts a rapid, structured discovery protocol 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.
+1. **Delta Auto-Sensing**: Inspect `brand.yaml` and `.tidyfactor/` before prompting the user.
+2. **Interactive Modal Wizard (CDL v2.0)**: Present genuine Unknowns exclusively via the native interactive modal tool (`ask_question`). Never dump static chat questionnaires.
+3. **Dual Operational Modes**:
+   - **Mode A (Smart 3-Round Protocol)**: R1 Market & ICP → R2 Voice & Mechanism → R3 Funnel & Margin Guardrails.
+   - **Mode B (Debate Mode — `/debate`)**: Relentlessly stress-tests marketing claims, price elasticity, CAC payback, and competitive moat until explicit user sign-off.
+4. **SSOT Persistence**: Save resulting decisions into `.tidyfactor/marketing-brief.md` and `.tidyfactor/marketing-brief.snapshot.yaml`.

package/references/memory/20-brain-baas-integration.md

@@ -0,0 +1,89 @@
+<!-- last-verified: 2026-09-02 -->
+# Brain MCP & Sovereign BaaS Marketing Integration Contract
+
+Authoritative operational specification governing how `tidyfactor-marketing` integrates with self-hosted `tidyfactor-brain` MCP instances and sovereign agency nodes without creating hard dependencies or blocking offline workflows.
+
+---
+
+## 🏛️ 1. Sovereign Architecture Model (Self-Hosted Primacy)
+
+TidyFactor Marketing operates on a **Sovereign, Self-Hosted Architecture**:
+- **Zero Centralized SaaS Dependency**: `tidyfactor-brain` and its MCP server run locally on the developer's machine or on an agency's self-hosted server instance.
+- **Tenant Definition**: A `tenant` represents an isolated client or brand workspace (e.g. `tenant_alwkala`, `tenant_client_a`) mapped to a dedicated SQLite file (`data/tenants/{tenant_id}_brain.sqlite`) or scoped local knowledge directory (`~/.gemini/knowledge/projects/{project_id}/`).
+- **No Global Auth Overhead**: Local stdio connections run authentication-free. Remote self-hosted nodes use static bearer tokens configured in `mcp_config.json`.
+
+---
+
+## ⚡ 2. The Deterministic Fail-Open Contract
+
+Brain MCP is strictly an **optional acceleration layer**, NEVER a required runtime dependency.
+
+### Strict Resolution Algorithm:
+
+```
+Step 1: Check Local Disk Workspace
+        ├── IF `BRAND-GUIDELINES.md` or `.tidyfactor/marketing-brief.md` exists:
+        │   └── LOAD directly from disk without asking questions. Done.
+        └── ELSE: Proceed to Step 2.
+
+Step 2: Check Active MCP Toolset Availability
+        ├── IF tool `search_knowledge_base` is present in agent's active tool list:
+        │   ├── Execute: `search_knowledge_base(query="marketing persona brand voice", scope="project", project_id=CURRENT_PROJECT)`
+        │   ├── IF valid marketing KI returned:
+        │   │   └── POPULATE context baseline immediately. Done.
+        │   └── ELSE (Empty/Error):
+        │       └── Silent fallback (0ms delay) to Step 3.
+        └── ELSE (Tool not registered / Standalone environment / Offline):
+            └── Silent fallback (0ms delay) to Step 3.
+
+Step 3: Interactive Micro-Discovery (CDL 3-Question Dialogue)
+        └── Present concise, structured A/B/C/D choices to the user. Zero conversational preamble. Done.
+```
+
+### Invariants:
+1. **Zero Robotic Preamble**: Never output introductory greetings like *"أهلاً بك بصفتي محرك التسويق..."* or ask the user whether a brief exists on disk.
+2. **Instant Silent Bypass**: If MCP is unavailable or errors, proceed immediately to the 3-question interview without delay or error messages.
+
+---
+
+## 📦 3. Marketing Strategy Knowledge Item (KI) Contract
+
+When exporting marketing baselines via explicit `--sync-brain` flag on `/brief` or `/strategy`, the deliverable formats as an Atomic KI conforming to the following JSON payload:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "ki_type": "marketing_strategy_baseline",
+  "project_id": "current-project-slug",
+  "timestamp": "2026-09-02T06:00:00Z",
+  "persona": {
+    "target_market": "GCC|Egypt|Levant|Global_B2B|Bilingual_MENA",
+    "voice_archetype": "authoritative_challenger|empathetic_guide|elite_luxury|direct_response",
+    "funnel_stage": "top_of_funnel|middle_of_funnel|bottom_of_funnel",
+    "core_offer": "lead_magnet|trial_demo|direct_sale",
+    "primary_conversion_channel": "whatsapp|direct_checkout|strategy_call|instapay"
+  },
+  "trust_signals": [
+    "cash_on_delivery",
+    "installments_tabby_tamara",
+    "official_cr_tax_id"
+  ],
+  "artifacts": [
+    ".tidyfactor/marketing-brief.md",
+    "copy/campaign-strategy.md"
+  ]
+}
+```
+
+---
+
+## 🛠️ 4. Tooling Execution Bridge (`run_skill_tool`)
+
+When `tidyfactor-brain` executes `tidyfactor-marketing` scripts via `manifest.json`:
+
+| Tool Name | Script Entrypoint | Latency Class | Execution Mode |
+|---|---|---|---|
+| `audit_copy` | `scripts/audit_copy.py` | Sub-second (<100ms) | Direct CLI / Text AST & Cliché Linter |
+| `calc_promo_math` | `scripts/calc_promo_math.py` | Sub-second (<50ms) | Deterministic Profit & ROAS Calculator |
+
+---