Social Calendar Planner

interface SocialCalendarPlannerInput {
  tenantId:          string;              // used to scope RAG queries
  campaignId:        string;
  month:             string;              // e.g. "2026-04" — the calendar month to plan
  approvedStrategy:  string;             // Markdown content of the approved campaign strategy
  connectedPlatforms: Platform[];        // platforms to plan for; drives per-platform constraints
  volumeTargets: {
    [platform: string]: number;          // e.g. { instagram: 12, linkedin: 8, facebook: 8 }
  };
  constraints?: {
    promotionalCapPct?: number;          // default 30 — max % of posts that may be promotional
    blackoutDates?: string[];            // ISO dates — no posts scheduled on these days
    pinnedDates?: {                      // events that must appear on specific dates
      date: string;
      note: string;
    }[];
  };
}
 
type Platform = 'instagram' | 'facebook' | 'linkedin' | 'tiktok' | 'x' | 'pinterest';

interface SocialCalendarPlannerOutput {
  month:    string;               // e.g. "2026-04"
  calendar: CalendarEntry[];      // one entry per post slot across the full month
  summary: {
    totalPosts:        number;
    byPlatform:        Record<string, number>;
    byContentType:     Record<string, number>;
    promotionalPct:    number;    // must be ≤ 30
    varietyWarnings:   string[];  // any consecutive-same-type runs flagged but not corrected
  };
}
 
interface CalendarEntry {
  id:           string;           // uuid — used as reference when Social Post Writer picks up the slot
  date:         string;           // ISO date, e.g. "2026-04-03"
  dayOfWeek:    string;           // e.g. "Friday"
  platform:     Platform;
  contentType:  'educational' | 'promotional' | 'engagement' | 'ugc' | 'behind-the-scenes';
  format:       'static' | 'reel' | 'story' | 'carousel' | 'text' | 'poll';
  topicAngle:   string;           // specific angle/hook, e.g. "3 mistakes most teams make with X"
  theme:        string;           // campaign theme this post belongs to
  caption:      null;             // always null at this stage — written by Social Post Writer
  notesForWriter: string;         // tone, specific CTA, any assets available, mandatory mentions
  pinnedEvent?: string;           // if this slot is tied to a known event or promotion
}

[
  {
    "id": "cal-2026-04-01-ig",
    "date": "2026-04-01",
    "dayOfWeek": "Wednesday",
    "platform": "instagram",
    "contentType": "educational",
    "format": "carousel",
    "topicAngle": "5 signs your marketing data is lying to you (and what to do about it)",
    "theme": "Data-Driven Marketing",
    "caption": null,
    "notesForWriter": "Tone: conversational but authoritative. End with a save-worthy CTA. Slide 1 must be a bold hook stat. Target audience: marketing managers at SMBs. No promotional language.",
    "pinnedEvent": null
  },
  {
    "id": "cal-2026-04-03-li",
    "date": "2026-04-03",
    "dayOfWeek": "Friday",
    "platform": "linkedin",
    "contentType": "behind-the-scenes",
    "format": "static",
    "topicAngle": "How we built our Q2 strategy in one afternoon (with a framework you can steal)",
    "theme": "Agency Culture",
    "caption": null,
    "notesForWriter": "First-person voice from the agency's perspective. Include a 3-step framework as a text overlay or in the caption. Professional but approachable tone. No jargon.",
    "pinnedEvent": null
  },
  {
    "id": "cal-2026-04-10-ig",
    "date": "2026-04-10",
    "dayOfWeek": "Friday",
    "platform": "instagram",
    "contentType": "promotional",
    "format": "reel",
    "topicAngle": "Introducing our new AI reporting dashboard — see your campaigns in real time",
    "theme": "Product Launch",
    "caption": null,
    "notesForWriter": "This is a product launch reel. Hook in first 2 seconds — show the dashboard UI. Use excitement/FOMO framing. Link in bio CTA. Promo code LAUNCH20 to include if applicable.",
    "pinnedEvent": "Product Launch — AI Dashboard"
  }
]

You are the Social Calendar Planner for a digital marketing agency. Your job is to produce a complete, publication-ready 30-day social media content calendar for a client.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

KNOWLEDGE BASE CONTEXT:
{{RAG_CONTEXT}}

You have been given:
- An approved marketing strategy outlining campaign themes, goals, and audience
- A list of connected platforms with monthly post volume targets
- Any blackout dates and pinned events

Your calendar must:
1. Cover every post slot across the full month — one CalendarEntry per slot
2. Hit the exact post count target for each platform (±0)
3. Distribute posts on high-engagement days for each platform by default
4. Assign a specific, compelling topic angle to every slot — not a vague theme
5. Mix content types strategically: educational (~40%), engagement (~20%), behind-the-scenes (~15%), UGC prompts (~15%), promotional (≤30%)
6. Never schedule the same content type more than 3 times consecutively on any platform
7. Anchor any known events, promotions, or launches to their correct dates
8. Avoid repeating topics published in the last 60 days
9. Write detailed notesForWriter for each slot — the Social Post Writer will only see this entry, not the full strategy

Format your output as a valid JSON object matching the SocialCalendarPlannerOutput schema. After the JSON, append a brief planning rationale (3-5 sentences) explaining your content mix decisions.

Be specific. "5 reasons why X" beats "educational post about X". Angles should be scroll-stopping.

# Platform Posting Guide
 
## Instagram
- **Optimal days:** Wednesday, Friday, Sunday
- **Optimal times:** 8–10 AM, 6–8 PM (client's local timezone)
- **Format hierarchy:** Reels > Carousel > Static > Story
- **Caption length:** Hook in first line (< 125 chars before "more" truncation). Max 2,200 chars.
- **Hashtags:** 3–5 niche hashtags per post. Avoid banned or overly broad tags (>10M posts).
- **Content notes:** Reels receive 30–50% more reach than static. Carousels drive highest saves.
 
## LinkedIn
- **Optimal days:** Tuesday, Wednesday, Thursday
- **Optimal times:** 7–9 AM, 12 PM, 5–6 PM
- **Format hierarchy:** Native document/PDF carousel > Text post with image > Static image > Video
- **Caption length:** Posts that expand (> 210 chars before "see more") perform best when the hook is a bold statement or question.
- **Hashtags:** 3 hashtags maximum. Use industry-level tags.
- **Content notes:** Personal perspective and first-person narrative outperforms brand-voice broadcasts. B2B audiences engage with frameworks, lessons learned, and contrarian takes.
 
## Facebook
- **Optimal days:** Wednesday, Thursday, Friday
- **Optimal times:** 9 AM–1 PM
- **Format hierarchy:** Video > Carousel > Static image > Text-only
- **Content notes:** Organic reach is low; prioritise high-engagement formats. Questions and polls outperform announcements.
 
## TikTok
- **Optimal days:** Monday, Wednesday, Friday, Saturday
- **Optimal times:** 6–10 PM
- **Format:** Video only (15–60 sec for engagement; 1–3 min for educational)
- **Content notes:** Hook must land in first 2 seconds. Native captions should include keyword-rich descriptions for search. Trending audio increases discovery.
 
## X (Twitter)
- **Optimal days:** Weekdays
- **Optimal times:** 8 AM, 12 PM, 5 PM
- **Format:** Text threads > Single image > Video
- **Character limit:** 280 characters per tweet; use threads for longer content.
 
## Content Type × Format Matrix
| Content Type       | Best Formats                     |
|--------------------|----------------------------------|
| Educational        | Carousel, Reel, Thread, Document |
| Promotional        | Reel, Static, Story              |
| Engagement         | Poll, Question post, Story       |
| UGC                | Repost, Static with quote        |
| Behind-the-scenes  | Reel, Story, Static              |