openads-ai 0.4.0 → 0.5.0

package/dist/cli.js

@@ -335,10 +335,11 @@ function getRelevantSkills(action, arAction, skillsDir, tier = 'standard') {
         }
         const expressMap = {
             'audit': [path.join(expressDir, 'audit.md'), epSkill],
-            'copy': [path.join(expressDir, 'copywriting.md'), epSkill],
+            'copy': [path.join(expressDir, 'copywriting.md'), path.join(expressDir, 'organic-social.md'), epSkill],
+            'organic': [path.join(expressDir, 'organic-social.md'), epSkill],
             'gtm': [path.join(expressDir, 'strategy.md'), epSkill],
             'autoresearch': [path.join(expressDir, 'autoresearch.md'), epSkill],
-            'chat': [epSkill],
+            'chat': [path.join(expressDir, 'organic-social.md'), epSkill],
         };
         return expressMap[action] || [epSkill];
     }
@@ -371,10 +372,20 @@ function getRelevantSkills(action, arAction, skillsDir, tier = 'standard') {
             pmSkill,
         ];
     }
-    // Copy → load copywriting + product context
+    // Copy → load copywriting + organic social + facebook organic + product context
     if (action === 'copy') {
         return [
             path.join(skillsDir, 'content', 'copywriting.md'),
+            path.join(skillsDir, 'organic', 'organic-social.md'),
+            path.join(skillsDir, 'organic', 'facebook-page.md'),
+            pmSkill,
+        ];
+    }
+    // Organic → load organic social + facebook organic + product context
+    if (action === 'organic') {
+        return [
+            path.join(skillsDir, 'organic', 'organic-social.md'),
+            path.join(skillsDir, 'organic', 'facebook-page.md'),
             pmSkill,
         ];
     }
@@ -473,6 +484,7 @@ async function main() {
                     { name: 'chat', message: `${chalk.cyan('💬')}  Ask anything` },
                     { name: 'audit', message: `${chalk.cyan('🔍')}  Quick audit — scan my campaigns` },
                     { name: 'copy', message: `${chalk.cyan('✍️')}   Write ad copy — headlines & descriptions` },
+                    { name: 'organic', message: `${chalk.cyan('📱')}  Organic posts — Instagram, LinkedIn, FB` },
                     { name: 'autoresearch', message: `${chalk.cyan('🎯')}  Generate ideas — marketing hypotheses` },
                     { name: 'gtm', message: `${chalk.cyan('📈')}  GTM brief — 1-page go-to-market plan` },
                     { name: 'setup', message: `${chalk.gray('⚙️')}   Settings` },
@@ -483,6 +495,7 @@ async function main() {
                         { name: 'chat', message: `${chalk.cyan('💬')}  Ask anything` },
                         { name: 'audit', message: `${chalk.cyan('🔍')}  Audit my ad campaigns` },
                         { name: 'copy', message: `${chalk.cyan('✍️')}   Write ad copy for any platform` },
+                        { name: 'organic', message: `${chalk.cyan('📱')}  Organic social content` },
                         { name: 'autoresearch', message: `${chalk.cyan('🔄')}  Test and improve ideas ${chalk.gray('(autoresearch)')}` },
                         { name: 'gtm', message: `${chalk.cyan('📈')}  Build a go-to-market plan` },
                         { name: 'schedule', message: `${chalk.cyan('⏰')}  Schedule automations` },
@@ -494,6 +507,7 @@ async function main() {
                         { name: 'chat', message: `${chalk.cyan('💬')}  Ask anything` },
                         { name: 'audit', message: `${chalk.cyan('🔍')}  Audit my ad campaigns ${chalk.gray('(deep analysis)')}` },
                         { name: 'copy', message: `${chalk.cyan('✍️')}   Write ad copy for any platform ${chalk.gray('(5+ variants)')}` },
+                        { name: 'organic', message: `${chalk.cyan('📱')}  Organic social posting ${chalk.gray('(Facebook integration)')}` },
                         { name: 'autoresearch', message: `${chalk.cyan('🔄')}  Test and improve ideas automatically ${chalk.gray('(autoresearch)')}` },
                         { name: 'gtm', message: `${chalk.cyan('📈')}  Build a go-to-market plan ${chalk.gray('(comprehensive)')}` },
                         { name: 'skills', message: `${chalk.cyan('📚')}  Browse available skills` },
@@ -1032,16 +1046,19 @@ async function main() {
                 const expressActionMap = {
                     chat: [],
                     copy: ['Write 5 ad headlines and 3 primary text options for my product. Follow the skill file format.'],
+                    organic: ['Write an organic social post for my product. Follow the organic-social-express skill format.'],
                     gtm: ['Create a 1-page GTM brief for my product. Follow the skill file format.'],
                 };
                 const standardActionMap = {
                     chat: [],
                     copy: ['Help me generate high-performing ad copy for my campaigns.'],
+                    organic: ['Help me draft high-performing organic social content for Instagram, LinkedIn, TikTok, or Facebook.'],
                     gtm: ['Help me build a go-to-market strategy for my product.'],
                 };
                 const fullActionMap = {
                     chat: [],
                     copy: ['Help me generate high-performing ad copy for my campaigns. Generate 5+ variants with distinct emotional registers, A/B testing rationale, and platform-specific formatting.'],
+                    organic: ['Help me plan, draft, or publish organic social content. If my Facebook Page is connected, check my recent posts first to avoid repeating topics, and format it natively for publication.'],
                     gtm: ['Help me build a comprehensive Go-To-Market strategy for my product. Include competitive positioning, channel plan with budget allocation, timeline, and success metrics.'],
                 };
                 const actionMap = tier === 'express' ? expressActionMap : tier === 'full' ? fullActionMap : standardActionMap;

package/dist/mcp-extension.js

@@ -4,7 +4,7 @@ import { hasGlobalRtk } from "./token-optimizer.js";
 import fs from "fs";
 import path from "path";
 import os from "os";
-// ─── Tier-Based Tool Filtering ──────────────────────────────────────
+// ─── Tier-Based Tool Filtering ────────────────────────────────────
 // Express → skip MCP entirely (handled by OPENADS_SKIP_MCP env var)
 // Standard → 6 read-only discovery + performance tools
 // Full → 11 tools (read + write operations)
@@ -44,7 +44,7 @@ export default async function (pi) {
         return;
     }
     const clients = [];
-    // ─── Google Ads MCP ───────────────────────────────────────────────
+    // ─── Google Ads MCP ────────────────────────────────────────────────────
     if (config.connectGoogle) {
         try {
             const useRtk = hasGlobalRtk();
@@ -63,7 +63,7 @@ export default async function (pi) {
             console.error(`[OpenAds MCP] Failed to connect to Google Ads: ${err.message}`);
         }
     }
-    // ─── Meta Ads MCP (Local Stdio Server via meta-ads-mcp) ───────────
+    // ─── Meta Ads MCP (Local Stdio Server via meta-ads-mcp) ─────────────────
     if (config.metaToken) {
         try {
             const useRtk = hasGlobalRtk();
@@ -110,7 +110,7 @@ export default async function (pi) {
                                 return {
                                     content: [{
                                             type: "text",
-                                            text: `Blocking execution of '${tool.name}' because OpenAds is in Audit Mode (Safe/Read-only). Under Audit Mode, campaign write operations are disabled. To execute active changes, please toggle to Launch Mode in Settings (\`openads setup\`).`
+                                            text: `Blocking execution of '${tool.name}' because OpenAds is in Audit Mode (Safe/Read-only). Campaign write operations are disabled. Toggle to Launch Mode in Settings (openads setup) to make changes.`
                                         }],
                                     details: {},
                                     isError: true,
@@ -159,6 +159,123 @@ export default async function (pi) {
             console.error(`[OpenAds MCP] Failed to register tools for ${serverName}: ${err.message}`);
         }
     }
+    // ─── Facebook Page Organic Posting ──────────────────────────────
+    if (config.facebookPageToken && config.facebookPageId) {
+        const FB_API = 'https://graph.facebook.com/v21.0';
+        const PAGE_ID = config.facebookPageId;
+        const PAGE_TOKEN = config.facebookPageToken;
+        // Read: get recent page posts (Standard + Full)
+        pi.registerTool({
+            name: 'get_facebook_page_posts',
+            label: 'Get Facebook Page Posts',
+            description: 'Retrieve recent organic posts from your Facebook Page. Call this before drafting new content to review posting history and avoid repeating topics.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    limit: {
+                        type: 'number',
+                        description: 'Number of recent posts to retrieve (1-25, default 10)',
+                    },
+                },
+            },
+            async execute(toolCallId, params, signal, onUpdate, ctx) {
+                const limit = Math.min(params.limit || 10, 25);
+                try {
+                    const res = await fetch(`${FB_API}/${PAGE_ID}/posts?fields=message,created_time,full_picture,permalink_url&limit=${limit}&access_token=${PAGE_TOKEN}`);
+                    const data = await res.json();
+                    if (data.error)
+                        throw new Error(data.error.message);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(data.data, null, 2) }],
+                        details: {},
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: 'text', text: `Error fetching posts: ${err.message}` }],
+                        details: {},
+                        isError: true,
+                    };
+                }
+            },
+        });
+        // Write: publish a post (Full tier only, gated by audit/launch mode)
+        if (tier === 'full') {
+            pi.registerTool({
+                name: 'post_to_facebook_page',
+                label: 'Post to Facebook Page',
+                description: 'Publish an organic text post (with optional link) to your Facebook Page.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        message: {
+                            type: 'string',
+                            description: 'The post text content',
+                        },
+                        link: {
+                            type: 'string',
+                            description: 'Optional URL to attach as a link preview',
+                        },
+                    },
+                    required: ['message'],
+                },
+                async execute(toolCallId, params, signal, onUpdate, ctx) {
+                    const p = params;
+                    if (config.mode === 'audit') {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: "Blocking 'post_to_facebook_page' — OpenAds is in Audit Mode (Read-only). Switch to Launch Mode in 'openads setup' to publish.",
+                                }],
+                            details: {},
+                            isError: true,
+                        };
+                    }
+                    if (config.mode === 'launch') {
+                        const preview = p.message.length > 120 ? p.message.slice(0, 120) + '...' : p.message;
+                        const ok = await ctx.ui.confirm('Confirm Facebook Post ⚠️', `You are about to publish to your Facebook Page:\n\n"${preview}"\n${p.link ? "\nLink: " + p.link : ""}\n\nPublish now?`);
+                        if (!ok) {
+                            return {
+                                content: [{ type: 'text', text: 'Post cancelled by user.' }],
+                                details: {},
+                                isError: true,
+                            };
+                        }
+                    }
+                    try {
+                        const body = {
+                            message: p.message,
+                            access_token: PAGE_TOKEN,
+                        };
+                        if (p.link)
+                            body.link = p.link;
+                        const res = await fetch(`${FB_API}/${PAGE_ID}/feed`, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify(body),
+                        });
+                        const data = await res.json();
+                        if (data.error)
+                            throw new Error(data.error.message);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `✅ Published!\nPost ID: ${data.id}\nURL: https://www.facebook.com/${data.id.replace("_", "/posts/")}`,
+                                }],
+                            details: {},
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            content: [{ type: 'text', text: `Error publishing post: ${err.message}` }],
+                            details: {},
+                            isError: true,
+                        };
+                    }
+                },
+            });
+        }
+    }
     // Register clean shutdown on session exit
     pi.on("session_shutdown", async () => {
         for (const { client } of clients) {

package/dist/setup.js

@@ -33,7 +33,7 @@ export async function runSetup() {
         catch (e) { }
     }
     // Step 1: Model Selection
-    console.log(chalk.cyan('Step 1/6: Choose your AI model\n'));
+    console.log(chalk.cyan('Step 1/7: Choose your AI model\n'));
     const providerChoices = [
         { name: 'google', message: 'Google (Gemini)' },
         { name: 'openai', message: 'OpenAI (ChatGPT)' },
@@ -211,7 +211,7 @@ export async function runSetup() {
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
     // Step 2: Experience Tier
-    console.log(chalk.cyan('Step 2/6: Choose your experience tier\n'));
+    console.log(chalk.cyan('Step 2/7: Choose your experience tier\n'));
     console.log('  OpenAds adapts its depth based on your model\'s capability:\n');
     console.log(`  ${chalk.yellow('⚡ Express')}   — Fast & reliable. Compact prompts, structured output.`);
     console.log(`  ${chalk.blue('📊 Standard')}  — Balanced depth. Live data tools, detailed reports.`);
@@ -250,7 +250,7 @@ export async function runSetup() {
     console.log(chalk.green(`\n✓ Experience tier: ${tierLabels[selectedTier]}.\n`));
     console.log(chalk.gray('─────────────────────────────────────────\n'));
     // Step 3: Choose operational mode
-    console.log(chalk.cyan('Step 3/6: Choose operational mode\n'));
+    console.log(chalk.cyan('Step 3/7: Choose operational mode\n'));
     console.log('OpenAds has two operational modes:');
     console.log(` - ${chalk.green.bold('Audit Mode (Safe / Read-only)')}: AI can analyze performance, find budget waste, and recommend strategies. Zero risk.`);
     console.log(` - ${chalk.red.bold('Launch Mode (Read-Write)')}: AI is authorized to optimize bids, modify budgets, and launch ads (always requires confirmation).\n`);
@@ -268,7 +268,7 @@ export async function runSetup() {
     console.log(chalk.green(`\n✓ Operational mode configured: ${mode === 'launch' ? 'Launch Mode (Read-Write)' : 'Audit Mode (Safe / Read-only)'}.\n`));
     console.log(chalk.gray('─────────────────────────────────────────\n'));
     // Step 4: Google Ads
-    console.log(chalk.cyan('Step 4/6: Connect Google Ads (optional)\n'));
+    console.log(chalk.cyan('Step 4/7: Connect Google Ads (optional)\n'));
     console.log('OpenAds can read and analyze your Google Ads campaigns, keywords, and performance.\n');
     const { connectGoogle } = await enquirer.prompt({
         type: 'confirm',
@@ -307,7 +307,7 @@ export async function runSetup() {
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
     // Step 4: Meta Ads
-    console.log(chalk.cyan('Step 5/6: Connect Meta Ads (optional)\n'));
+    console.log(chalk.cyan('Step 5/7: Connect Meta Ads (optional)\n'));
     console.log('OpenAds can read your Meta campaigns, creatives, and audience performance.\n');
     let metaToken = '';
     const { connectMeta } = await enquirer.prompt({
@@ -414,7 +414,97 @@ export async function runSetup() {
     }
     console.log(chalk.gray('─────────────────────────────────────────\n'));
     // Step 6: Business Context
-    console.log(chalk.cyan('Step 6/6: Tell me about your business\n'));
+    // Step 6/7: Facebook Page for organic posting
+    console.log(chalk.cyan('Step 6/7: Connect Facebook Page for organic posts (optional)\n'));
+    console.log('OpenAds can draft and publish organic posts to your Facebook Page.\n');
+    let facebookPageToken = existingConfig.facebookPageToken || '';
+    let facebookPageId = existingConfig.facebookPageId || '';
+    const { connectFacebookPage } = await enquirer.prompt({
+        type: 'confirm',
+        name: 'connectFacebookPage',
+        message: 'Connect a Facebook Page for organic posting?',
+        initial: existingConfig.facebookPageToken ? true : false
+    });
+    if (connectFacebookPage) {
+        const { fbAction } = await enquirer.prompt({
+            type: 'select',
+            name: 'fbAction',
+            message: 'How would you like to proceed?',
+            choices: [
+                { name: 'guide', message: 'Open Graph API Explorer (get a Page Access Token)' },
+                { name: 'skip', message: 'Skip (I already have my token and Page ID)' }
+            ]
+        });
+        if (fbAction === 'guide') {
+            await open('https://developers.facebook.com/tools/explorer/');
+            console.log(chalk.cyan('\nInstructions to get a Facebook Page Access Token:'));
+            console.log(chalk.gray('1. In Graph API Explorer, select your App.'));
+            console.log(chalk.gray('2. Click Generate Access Token and grant pages_manage_posts + pages_read_engagement.'));
+            console.log(chalk.gray('3. Run GET /me/accounts — find your Page and copy its access_token and id.\n'));
+        }
+        let fbVerified = false;
+        while (!fbVerified) {
+            const fbAnswers = await enquirer.prompt([
+                {
+                    type: 'password',
+                    name: 'facebookPageToken',
+                    message: 'Paste your Facebook Page Access Token:',
+                    initial: existingConfig.facebookPageToken || '',
+                    validate: (v) => v.trim() ? true : 'Token cannot be empty.'
+                },
+                {
+                    type: 'input',
+                    name: 'facebookPageId',
+                    message: 'Paste your Facebook Page ID (numeric):',
+                    initial: existingConfig.facebookPageId || '',
+                    validate: (v) => v.trim() ? true : 'Page ID cannot be empty.'
+                }
+            ]);
+            facebookPageToken = fbAnswers.facebookPageToken;
+            facebookPageId = fbAnswers.facebookPageId;
+            console.log(chalk.cyan('Verifying Facebook Page token...'));
+            try {
+                const res = await fetch(`https://graph.facebook.com/v21.0/${facebookPageId}?fields=name,fan_count&access_token=${facebookPageToken}`);
+                const data = await res.json();
+                if (res.ok && data.name) {
+                    console.log(chalk.green(`\n✓ Connected to Facebook Page: "${data.name}" (${(data.fan_count || 0).toLocaleString()} followers)\n`));
+                    fbVerified = true;
+                }
+                else {
+                    console.log(chalk.red(`\n🛑 Verification failed: ${data.error?.message || 'Invalid token or page ID'}\n`));
+                    const { retryAction } = await enquirer.prompt({
+                        type: 'select', name: 'retryAction', message: 'How would you like to handle this?',
+                        choices: [
+                            { name: 'retry', message: 'Try again' },
+                            { name: 'keep', message: 'Keep anyway' },
+                            { name: 'skip', message: 'Skip Facebook Page connection' }
+                        ]
+                    });
+                    if (retryAction === 'keep')
+                        fbVerified = true;
+                    else if (retryAction === 'skip') {
+                        facebookPageToken = '';
+                        facebookPageId = '';
+                        break;
+                    }
+                }
+            }
+            catch (e) {
+                console.log(chalk.red(`\n🛑 Network error: ${e.message}\n`));
+                facebookPageToken = '';
+                facebookPageId = '';
+                break;
+            }
+        }
+        if (facebookPageToken) {
+            console.log(chalk.green('✓ Facebook organic posting module enabled.\n'));
+        }
+        else {
+            console.log(chalk.yellow('✓ Facebook Page connection skipped.\n'));
+        }
+    }
+    console.log(chalk.gray('─────────────────────────────────────────\n'));
+    console.log(chalk.cyan('Step 7/7: Tell me about your business\n'));
     const { productContext } = await enquirer.prompt({
         type: 'input',
         name: 'productContext',
@@ -441,7 +531,9 @@ export async function runSetup() {
         mode,
         connectGoogle,
         metaToken,
-        productContext
+        productContext,
+        facebookPageToken,
+        facebookPageId,
     };
     fs.writeFileSync(path.join(configDir, 'openads.config.json'), JSON.stringify(config, null, 2));
     console.log('You\'re ready. Here are some things to try:\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openads-ai",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Open-source AI command center for digital marketers. Audit campaigns, write ad copy, and build strategies — from your terminal.",
   "main": "dist/cli.js",
   "bin": {

package/skills/express/organic-social.md

@@ -0,0 +1,24 @@
+---
+name: organic-social-express
+description: Plan and write organic social posts for Instagram, LinkedIn, TikTok, and Facebook.
+---
+
+# Organic Social (Express)
+
+Write platform-native organic posts using product context and brand voice.
+
+## Rules
+- Give value before any CTA — educate, entertain, or inspire first
+- Write for the platform, never repurpose copy across platforms
+- Assign every post to one pillar: Education, Social Proof, Culture, or POV
+- Hook in first 1–2 seconds (Instagram/TikTok) or first line (LinkedIn)
+- No "Excited to announce." No starting with the brand name
+- Soft CTA or memorable closer only — no hard sell on organic
+
+## Output Format
+
+### [Platform]
+**Pillar:** [Education | Social Proof | Culture | POV]
+**Hook:** [Opening line / frame / on-screen text]
+**Body:** [Post content]
+**Closer:** [Question, soft CTA, or memorable line]

package/skills/organic/facebook-page.md

@@ -0,0 +1,47 @@
+---
+name: facebook-page-organic
+description: Draft and publish organic posts to a connected Facebook Page. Use the get_facebook_page_posts and post_to_facebook_page tools when available.
+---
+
+# Facebook Page Organic Posting
+
+## When to Use
+Activate when the user wants to post to Facebook, draft organic Facebook content, review posting history, or plan their Facebook Page content calendar.
+
+Requires `facebookPageToken` and `facebookPageId` configured via `openads setup`.
+
+---
+
+## Before Drafting Any Post
+
+1. Call `get_facebook_page_posts` (limit: 10) to review what's been published recently
+2. Check for repeated topics, posting cadence, and tone patterns
+3. Never write a post that echoes a theme from the last 3 posts — deconflict first
+
+---
+
+## Facebook Post Rules
+
+- **40–80 words** for feed posts — shorter than LinkedIn, punchier than a blog
+- **Lead with the hook** — first line must earn the stop before "See More"
+- **Questions and "tag someone" prompts** drive comments, which drive algorithmic reach
+- **No link in post body** if reach matters — attach via the `link` parameter or suggest putting it in comments
+- Organic reach on Pages is ~2–5% of followers — write content people want to *share*
+
+## What NOT to Do
+- Don't start with the brand name or "Excited to announce"
+- Don't paste the same copy from Instagram or LinkedIn — adapt for platform
+- No hard CTA (buy, sign up) on organic — soft close or question only
+
+---
+
+## Output Format
+
+**Post:**
+[Post text — 40–80 words, hook first]
+
+**Link (optional):** [URL to attach as link preview]
+
+**Pillar:** [Education | Social Proof | Culture | POV]
+
+**Ready to publish** via `post_to_facebook_page` — confirm when ready.

package/skills/organic/organic-social.md

@@ -0,0 +1,171 @@
+---
+name: organic-social
+description: Plan, write, and optimize organic social content for brand awareness across Instagram, LinkedIn, TikTok, and Facebook.
+---
+
+# Organic Social
+
+## When to Use This Skill
+
+Activate when the user needs to create, plan, or improve organic (non-paid) social media content — posts, captions, Reels scripts, carousels, TikTok hooks, LinkedIn posts, or a content strategy.
+
+Read `product-marketing.md` first. Every piece of content must reflect the brand's voice, ICP, and positioning — not generic filler.
+
+---
+
+## Organic vs. Paid: The Fundamental Difference
+
+Paid content interrupts. Organic content earns attention.
+
+The single most important mindset shift: **organic content is not ads without a budget line.** It operates on a different contract with the audience — one built on consistent value, personality, and trust over time. If it feels like an ad, it loses.
+
+Rules that follow from this:
+- **Give before you ask.** Entertain, teach, or inspire before any call to action.
+- **Show the world, not just the product.** Document the life, the problem, the people — the product earns its place.
+- **Consistency of voice > frequency of posts.** A distinct, recognizable tone that shows up 3x/week beats a different persona posting daily.
+- **Platform-native wins.** Content made for the platform — not repurposed from somewhere else — consistently outperforms.
+
+---
+
+## Content Pillars
+
+Before writing any content, establish 3–4 pillars — recurring themes that define what the brand talks about. Every post should fit inside one.
+
+Good pillars for a brand-awareness strategy:
+1. **Value / Education** — Teach the audience something useful in your space. No pitch.
+2. **Social Proof / Story** — Real customers, real outcomes, real moments. Specifics over superlatives.
+3. **Culture / Behind the Scenes** — Who you are, how you work, what you believe. Makes the brand human.
+4. **POV / Opinion** — A take on the industry, the problem, or the status quo. Builds a distinct voice.
+
+Avoid mixing pillars in a single post. One post, one idea.
+
+---
+
+## Platform Playbook
+
+### Instagram
+
+**What it rewards:** Visual consistency, Reels reach, strong hooks in the first frame.
+
+**Format rules:**
+- Reels get 3–5x the organic reach of static posts — lead with video when possible
+- Hook must land in the **first 1–2 seconds** (on screen text or action, not a logo)
+- Captions: front-load the value in line 1 before the "more" fold (125 characters)
+- Carousels: slide 1 is the hook, slide 2 delivers enough value that they swipe, last slide is a soft CTA or memorable closer
+- Stories: more casual, more frequent, more conversational — use for behind-the-scenes and direct audience interaction
+- Hashtags: 3–5 targeted, not 30 generic — reach is driven by content signals now, not hashtag stuffing
+
+**For brand awareness specifically:**
+- Show what life looks like with/around the brand — not features, sensations
+- Use the same visual treatment (color, typography, framing) across posts to build recognizability
+- Audio matters: trending audio on Reels extends reach, but branded audio builds identity
+
+---
+
+### TikTok
+
+**What it rewards:** Native-feeling content, strong verbal or visual hooks, watch time and rewatches.
+
+**Format rules:**
+- **Hook in the first 2 seconds** — spoken or on-screen. The algorithm decides within 3 seconds whether to show it further
+- Optimal length for brand awareness: 15–30 seconds (gets rewatched, rewatches signal quality)
+- Speak directly to camera in the opening — "here's why...", "this changed how we...", "nobody talks about..."
+- Captions are largely decorative on TikTok — the video must carry the message
+- Post natively, not as a repurposed Reel (TikTok suppresses watermarked content)
+- Comments are reach fuel — reply to every early comment, pin a strong one
+
+**Hook formulas that work:**
+- **The Reframe:** "Everyone thinks X. Here's what's actually happening."
+- **The Specific Claim:** "We grew from 0 to [number] doing one thing."
+- **The Contrast:** "Before [brand] vs. after [brand]" — show don't tell
+- **The Relatable Problem:** Open on the exact moment your ICP feels the pain
+
+**For brand awareness:**
+- Authenticity > production value. A shaky founder video with a strong hook outperforms polished content with a weak one.
+- Series content builds returning viewers — "part 2", recurring formats, ongoing stories
+
+---
+
+### LinkedIn
+
+**What it rewards:** Text-heavy native posts, personal POV, comments and conversation.
+
+**Format rules:**
+- **First line is everything** — it shows before "see more." It must create enough tension or curiosity to make clicking feel necessary
+- Native text posts outperform links — if sharing a link, put it in the first comment, not the post
+- Optimal length: 800–1,500 characters for engagement. Short posts feel thin. Very long posts lose readers.
+- Line breaks matter — single-sentence lines, white space between them. Walls of text get scrolled past.
+- End with a question or a strong declarative statement, not a CTA to buy something
+- Images: single-image posts perform better than carousels on LinkedIn; carousels work for step-by-step content only
+
+**LinkedIn-specific voice:**
+- First person, opinionated, conversational — not a press release
+- "I" outperforms "We" — even for brands, a founder voice beats a company voice
+- Stories with a lesson outperform lists with no narrative
+- Controversy (respectful) and contrarian takes drive comments
+
+**Hook formulas:**
+- "I used to [wrong belief]. Then [thing happened]. Here's what I learned."
+- "Hot take: [unexpected opinion about your industry]."
+- "[Number] years of [experience] taught me one thing about [relevant topic]."
+- "Most [role] get [common thing] wrong. Here's what they miss."
+
+**For brand awareness:**
+- LinkedIn builds credibility, not virality. Play the long game.
+- Consistency (3x/week) matters more than any single post
+- Engage on others' posts before your own — LinkedIn rewards givers
+
+---
+
+### Facebook
+
+**What it rewards:** Community interaction, shared content, groups, video watch time.
+
+**Format rules:**
+- Organic reach on Facebook Pages is very low (~2–5% of followers) — lean into Groups and shares rather than Page posts alone
+- Video (especially Facebook-native uploads) gets the most reach
+- Posts with questions get more comments; comments signal the algorithm to push further
+- Keep copy shorter than LinkedIn — 40–80 words for feed posts, more in Groups
+- Link posts suppress reach — same rule as LinkedIn: link in comments if possible
+- Facebook Live still gets significant organic boost vs. recorded video
+
+**For brand awareness:**
+- Build or participate in a niche Facebook Group — that's where organic reach still lives
+- Share content that people want to forward to a specific friend ("tag someone who needs this")
+- User-generated content and resharing customer stories performs well
+
+---
+
+## Writing a Post: Step-by-Step
+
+When writing any organic post:
+
+1. **Identify the pillar** — which of the brand's 4 content pillars does this serve?
+2. **Choose the platform format** — don't write generically and repurpose; write for the platform
+3. **Write the hook first** — don't touch the body until the hook is strong
+4. **Apply voice from product-marketing.md** — tone, persona, vocabulary
+5. **Check the contract** — is this giving value before asking anything? If not, revise
+6. **Write a soft CTA or closer** — curiosity, question, or memorable line. Never a hard sell on organic.
+
+---
+
+## Batch Content Planning
+
+When the user asks to plan content (weekly, monthly):
+
+1. Map posts to pillars — balanced across the 4 pillars, no consecutive posts from the same pillar
+2. Anchor to moments — product milestones, cultural moments, seasonal relevance
+3. Stagger formats — vary between video, static, text, story/carousel
+4. Flag repurposable pieces — one strong Reel can become a LinkedIn post can become a carousel
+
+Output a simple grid: Date | Platform | Pillar | Format | Hook / Topic
+
+---
+
+## What NOT to Do
+
+- Do not write captions that start with the brand name
+- Do not lead with "Excited to announce" on any platform
+- Do not use the same copy across all platforms — adapt for each
+- Do not post and ghost — engagement in the first 30 minutes after posting drives algorithmic reach
+- Do not treat organic as a dumping ground for ad creative that didn't get budget