@growthub/cli 0.3.53 → 0.3.54

package/assets/worker-kits/growthub-postiz-social-v1/.env.example

@@ -0,0 +1,18 @@
+# Growthub Postiz Social Studio — Environment Config
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# Optional override for your local Postiz fork path.
+# Default used by scripts is ~/postiz-app.
+# POSTIZ_FORK_PATH=/path/to/your/postiz-app
+
+# Base URL for the local Postiz API.
+POSTIZ_API_URL=http://localhost:3000
+
+# Required for scheduling manifest submission.
+# Find this in Postiz Settings > Workspace.
+POSTIZ_WORKSPACE_ID=your_postiz_workspace_id_here
+
+# Optional for AI-enhanced caption generation in agent/hybrid mode.
+# Get one at https://console.anthropic.com
+ANTHROPIC_API_KEY=your_anthropic_key_here

package/assets/worker-kits/growthub-postiz-social-v1/QUICKSTART.md

@@ -0,0 +1,136 @@
+# Growthub Postiz Social Media Studio — Quickstart
+
+**Kit:** `growthub-postiz-social-v1`
+**Worker:** `postiz-social-operator`
+**Platform:** [Postiz](https://github.com/gitroomhq/postiz-app)
+
+---
+
+## What This Kit Does
+
+The Growthub Postiz Social Media Studio is a self-contained AI agent environment for planning, drafting, scheduling, and analyzing social media campaigns using the Postiz open-source platform. It wraps the self-hosted Postiz workspace to produce:
+
+- Social campaign briefs (objective, platforms, audience, KPIs)
+- 30/60/90-day content calendars with theme pillars
+- Platform publishing plans for 28+ social networks
+- Caption copy decks with A/B/C variants per post
+- BullMQ-compatible scheduling manifests for Postiz API
+- Analytics briefings (engagement, reach, growth signals)
+- Client-ready proposals with platform mix and ROI projections
+
+Supported platforms include: Instagram, LinkedIn, TikTok, X/Twitter, YouTube, Pinterest, Reddit, Bluesky, Facebook, Mastodon, Slack, Telegram, and 16+ more. See `docs/platform-coverage.md` for the full list.
+
+---
+
+## Setup — 6 Steps
+
+### Step 1 — Point Your Working Directory
+
+Export this kit to a local folder and point Claude Code's Working Directory at the kit root. All paths in the kit are relative to the kit root.
+
+### Step 2 — Copy the Environment File
+
+```bash
+cp .env.example .env
+```
+
+Fill in your Postiz workspace credentials and API endpoint. No platform OAuth tokens are stored in this kit — those live inside the Postiz admin UI.
+
+### Step 3 — Verify the Environment
+
+```bash
+node setup/verify-env.mjs
+```
+
+This checks:
+- Whether the Postiz fork is cloned at `POSTIZ_FORK_PATH` (default: `~/postiz-app`)
+- Whether the Postiz API is reachable on port 3000
+- Whether `ANTHROPIC_API_KEY` is valid format (if set for AI caption enhancement)
+- No OAuth tokens are validated here — those are managed inside Postiz
+
+### Step 4 — Check Dependencies
+
+```bash
+bash setup/check-deps.sh
+```
+
+Verifies that `node`, `docker`, `docker compose`, and `git` are available. Checks Node.js version (18+ required). Checks Docker engine is running.
+
+### Step 5 — Clone and Start the Postiz Workspace (Local-Fork Mode Only)
+
+```bash
+bash setup/clone-fork.sh
+```
+
+This clones `postiz-app` to `~/postiz-app` (or `POSTIZ_FORK_PATH` if set), runs `docker compose up -d` to start Redis, PostgreSQL, and the Postiz API, and waits for the API healthcheck to pass.
+
+Skip this step if you are using **agent-only mode** — the operator can plan campaigns, draft captions, and produce content calendars without a running Postiz instance.
+
+### Step 6 — Start a Session
+
+Open Claude Code, set the Working Directory to this kit root, and start your session. The operator will guide you through the 10-step workflow.
+
+---
+
+## Execution Modes
+
+| Mode | Requirements | Use When |
+|---|---|---|
+| `local-fork` | Node 18+, Docker, Postiz running | You want to schedule posts via the Postiz API and use multi-workspace features |
+| `agent-only` | Nothing — Claude handles everything | You need campaign planning, content calendars, and caption drafts without a running instance |
+| `hybrid` | ANTHROPIC_API_KEY + Postiz running | Best of both — agent reasoning with live Postiz API scheduling |
+
+---
+
+## First Run
+
+1. Tell the operator: **"Plan a 30-day Instagram + LinkedIn campaign for [your brand]"**
+2. The operator will ask 4 clarifying questions (client, platforms, objective, cadence)
+3. The operator runs the 10-step workflow and produces all campaign artifacts
+4. Output is saved to `output/<client-slug>/<project-slug>/`
+
+---
+
+## New Client Setup
+
+See `brands/NEW-CLIENT.md` for instructions on adding a new client brand kit.
+
+Quick version:
+```bash
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+# Then fill in the fields in the new file
+```
+
+---
+
+## Available Commands
+
+Tell the operator which you need:
+
+| Command | What It Does |
+|---|---|
+| `/postiz campaign` | Full campaign brief + content calendar + publishing plan |
+| `/postiz calendar` | Content calendar only — existing brief provided |
+| `/postiz captions` | Caption copy deck for a specific platform or batch |
+| `/postiz schedule` | Generate BullMQ-compatible scheduling manifest |
+| `/postiz analytics` | Analytics briefing from Postiz API data or provided metrics |
+| `/postiz proposal` | Client-ready proposal with platform mix and ROI projection |
+| `/postiz platforms` | Platform coverage report for a specific client context |
+| `/postiz quick` | 30-second campaign snapshot for a domain or brand |
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `workers/postiz-social-operator/CLAUDE.md` | Agent operating instructions (start here) |
+| `skills.md` | Full methodology — read at every session |
+| `brands/_template/brand-kit.md` | Blank brand kit template |
+| `brands/growthub/brand-kit.md` | Growthub reference example |
+| `output/README.md` | Output directory structure and naming |
+| `docs/postiz-fork-integration.md` | How this kit integrates with Postiz |
+| `docs/platform-coverage.md` | All 28+ supported platforms with format specs |
+| `docs/ai-caption-layer.md` | AI caption generation methodology |
+| `docs/bullmq-queue-layer.md` | Scheduling manifest format for Postiz API |
+| `validation-checklist.md` | Pre-session checklist |

package/assets/worker-kits/growthub-postiz-social-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,67 @@
+# Adding a New Client
+
+This guide explains how to create a brand kit for a new client in the Postiz Social Media Studio.
+
+---
+
+## Steps
+
+### 1. Copy the Template
+
+```bash
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+```
+
+Replace `<client-slug>` with a lowercase, hyphenated version of the client name. Examples:
+- "Urban Cycle" → `urban-cycle`
+- "Acme SaaS Corp" → `acme-saas`
+- "The Bloom Studio" → `bloom-studio`
+
+### 2. Fill in the Brand Kit
+
+Open the new file and fill in every section:
+- **Client Identity** — name, slug, industry, website
+- **Social Media Presence** — existing accounts, follower counts, current activity level
+- **Target Audience** — primary and secondary audience profiles
+- **Campaign Objectives** — metrics, targets, and timelines
+- **Brand Voice** — tone, personality, approved/blocked words, emoji usage
+- **Content Theme Pillars** — 3–5 recurring themes with platform assignments
+- **Competitor Reference Accounts** — 2–3 accounts to reference for format benchmarking
+- **Agency Context** — engagement stage, retainer, reporting cadence
+
+### 3. Verify the Brand Kit
+
+Before using the brand kit in a session, confirm:
+- [ ] `client-slug` in the filename matches the `Client Slug` field in the kit
+- [ ] At least one platform is listed in `Social Media Presence`
+- [ ] At least one campaign objective has a measurable target
+- [ ] Brand voice section is complete — no empty `[fill in]` placeholders
+- [ ] At least 3 content theme pillars are defined
+
+### 4. Tell the Operator
+
+Start your Claude Code session and say:
+> "Load the brand kit for [client-name] and begin a [campaign objective] campaign."
+
+The operator will read the brand kit and ask the 4-question gate before producing any output.
+
+---
+
+## Brand Kit Naming Rules
+
+| Rule | Correct | Incorrect |
+|---|---|---|
+| Directory name is lowercase kebab-case | `brands/urban-cycle/` | `brands/UrbanCycle/` |
+| Filename is always `brand-kit.md` | `brands/urban-cycle/brand-kit.md` | `brands/urban-cycle/UrbanCycle.md` |
+| Slug contains no spaces | `acme-saas` | `acme saas` |
+| Slug contains no special chars | `bloom-studio` | `bloom/studio` |
+
+---
+
+## Note on Public Brand Kits
+
+Brand kits are **not included in kit exports by default**. The only brand kits included in exports are:
+- `brands/_template/brand-kit.md` — the blank template
+- `brands/growthub/brand-kit.md` — the public reference example
+
+Client brand kits you create live in your local kit installation only. They are not bundled into the export zip or submitted to any external service.

package/assets/worker-kits/growthub-postiz-social-v1/brands/_template/brand-kit.md

@@ -0,0 +1,120 @@
+# Brand Kit — [Client Name]
+
+<!-- Replace [Client Name] with the actual client name and rename this file to brands/<client-slug>/brand-kit.md -->
+
+---
+
+## Client Identity
+
+| Field | Value |
+|---|---|
+| Client Name | [Client Name] |
+| Client Slug | [client-slug] |
+| Industry | [e.g., SaaS / E-commerce / Hospitality / Fintech] |
+| Website | [https://...] |
+| Primary Contact | [Name, email] |
+
+---
+
+## Social Media Presence
+
+| Platform | Handle | Followers | Current Status |
+|---|---|---|---|
+| Instagram | [@handle] | [N] | [Active / Inactive / New] |
+| LinkedIn | [company page URL] | [N followers] | [Active / Inactive] |
+| TikTok | [@handle] | [N] | [Active / Inactive] |
+| X/Twitter | [@handle] | [N] | [Active / Inactive] |
+| [Other] | [handle] | [N] | [Active / Inactive] |
+
+---
+
+## Target Audience
+
+### Primary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | [e.g., 25–40] |
+| Gender | [e.g., 55% female, 45% male] |
+| Location | [e.g., North America, English-speaking markets] |
+| Interests | [e.g., entrepreneurship, productivity, design] |
+| Pain Points | [e.g., too many disconnected tools, manual social media posting] |
+| Content Preferences | [e.g., educational how-tos, success stories, data-driven insights] |
+
+### Secondary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | [e.g., 18–25] |
+| Interests | [e.g., tech, side projects] |
+| Platform | [e.g., TikTok, Reddit] |
+
+---
+
+## Campaign Objectives
+
+| Objective | Metric | Target | Timeline |
+|---|---|---|---|
+| [Brand awareness] | [Impressions] | [50,000/month] | [Q2 2026] |
+| [Lead generation] | [Link clicks] | [200/month] | [Q2 2026] |
+| [Community growth] | [Follower growth] | [+500] | [Q2 2026] |
+
+---
+
+## Brand Voice
+
+| Attribute | Spec |
+|---|---|
+| Tone | [e.g., Professional but approachable. Data-driven without being dry. Never salesy.] |
+| Personality | [e.g., Smart, helpful, occasionally witty] |
+| Words to Use | [e.g., "build", "grow", "automate", "team", "results"] |
+| Words to Avoid | [e.g., "hack", "guru", "crush it", "cheap", "amazing"] |
+| Emoji Usage | [e.g., Minimal on LinkedIn; moderate on Instagram; more on TikTok] |
+| CTA Style | [e.g., Direct action verbs: "Start today", "Learn more", "Join the team"] |
+
+---
+
+## Content Theme Pillars
+
+| Pillar | Description | Platforms | % of Calendar |
+|---|---|---|---|
+| [Industry Insights] | [What we know that others don't — data, trends, analysis] | [All] | [40%] |
+| [Product Value] | [Feature spotlights, use cases, ROI stories] | [LinkedIn, Instagram] | [30%] |
+| [Social Proof] | [Customer testimonials, case studies, results] | [All] | [20%] |
+| [Community] | [Q&A, behind the scenes, team moments] | [Instagram, TikTok] | [10%] |
+
+---
+
+## Competitor Reference Accounts
+
+| Platform | Account | Why Reference |
+|---|---|---|
+| [Instagram] | [@competitor] | [Strong visual brand, good engagement format] |
+| [LinkedIn] | [competitor company page] | [Industry leader, consistent posting cadence] |
+
+---
+
+## Agency Context
+
+| Field | Value |
+|---|---|
+| Engagement Stage | [Prospect / Onboarding / Retained] |
+| Monthly Retainer | [e.g., $X,XXX/month or "not established"] |
+| Campaign Budget | [e.g., $X,XXX / campaign or "TBD"] |
+| Reporting Cadence | [e.g., Monthly analytics brief] |
+
+---
+
+## CRM Notes
+
+<!-- Internal notes for agency context. Not included in client-facing outputs. -->
+
+[Add internal notes here: key contacts, relationship history, upsell opportunities, account health signals]
+
+---
+
+## DELIVERABLES LOG
+
+<!-- Append a line for each completed deliverable. -->
+
+<!-- - YYYY-MM-DD | Social Media Campaign Package v1 — [Project Name] | output/<client-slug>/<project-slug>/ -->

package/assets/worker-kits/growthub-postiz-social-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,117 @@
+# Brand Kit — Growthub
+
+<!-- Reference example for the Postiz Social Media Studio. Use this to understand the expected format and detail level. -->
+
+---
+
+## Client Identity
+
+| Field | Value |
+|---|---|
+| Client Name | Growthub |
+| Client Slug | `growthub` |
+| Industry | Developer tools / AI agent infrastructure / SaaS |
+| Website | https://growthub.ai |
+| Primary Contact | Internal — Growthub marketing team |
+
+---
+
+## Social Media Presence
+
+| Platform | Handle | Followers | Current Status |
+|---|---|---|---|
+| X/Twitter | @growthubai | 3,200 | Active |
+| LinkedIn | Growthub (company page) | 1,800 | Active |
+| Bluesky | @growthub.ai | 400 | Growing |
+| GitHub | github.com/Growthub-ai | 2,100 stars | Active (open source) |
+
+---
+
+## Target Audience
+
+### Primary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | 25–45 |
+| Gender | 60% male, 40% female |
+| Location | North America, Europe, English-speaking global |
+| Interests | AI agents, developer tools, automation, indie hacking, SaaS growth |
+| Pain Points | Complex agent orchestration, lack of open-source local-first alternatives, AI tool fatigue |
+| Content Preferences | Technical tutorials, tool comparisons, workflow examples, behind-the-scenes product builds |
+
+### Secondary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | 18–25 |
+| Interests | Open source, hackathons, learning AI development |
+| Platform | GitHub, X/Twitter, Bluesky |
+
+---
+
+## Campaign Objectives
+
+| Objective | Metric | Target | Timeline |
+|---|---|---|---|
+| Developer awareness | GitHub stars | +500/quarter | Q2 2026 |
+| Community growth | Twitter/X followers | +200/month | Ongoing |
+| Thought leadership | LinkedIn impressions | 20,000/month | Q2 2026 |
+| Open-source adoption | CLI downloads | +1,000/month | Q2 2026 |
+
+---
+
+## Brand Voice
+
+| Attribute | Spec |
+|---|---|
+| Tone | Direct, technically credible, approachable. We explain without condescending. We ship without bragging. |
+| Personality | Builder-first. We're in the trenches using the tools we build. |
+| Words to Use | "build", "ship", "run", "local", "open", "agent", "workflow", "kit", "workspace" |
+| Words to Avoid | "disruptive", "AI-powered" (use "agent-native" instead), "revolutionary", "hack" |
+| Emoji Usage | Minimal — 0–1 on LinkedIn; 0–2 on X; 2–4 on Instagram |
+| CTA Style | Action verbs with immediate value: "Try it now", "Clone and run", "Read the docs", "Star on GitHub" |
+
+---
+
+## Content Theme Pillars
+
+| Pillar | Description | Platforms | % of Calendar |
+|---|---|---|---|
+| Product Builds | Behind-the-scenes of building Growthub features — architecture, decisions, tradeoffs | X, LinkedIn, GitHub | 35% |
+| Developer Tutorials | How to use Growthub kits, commands, and workflows in real workflows | X, LinkedIn, Bluesky | 30% |
+| Open Source | Open-source culture, contributions, partner project spotlights | X, Bluesky, GitHub | 20% |
+| Community | User projects, shoutouts, Q&A, polls | X, LinkedIn | 15% |
+
+---
+
+## Competitor Reference Accounts
+
+| Platform | Account | Why Reference |
+|---|---|---|
+| X/Twitter | @langchain | Strong developer community engagement, technical thread format |
+| LinkedIn | Anthropic company page | Consistent educational posting, thought leadership |
+| X/Twitter | @cursor_ai | Product-led content strategy, community responsiveness |
+
+---
+
+## Agency Context
+
+| Field | Value |
+|---|---|
+| Engagement Stage | Internal — first-party reference kit |
+| Monthly Retainer | N/A (internal) |
+| Campaign Budget | N/A |
+| Reporting Cadence | Monthly analytics brief to marketing team |
+
+---
+
+## CRM Notes
+
+Internal reference account. Used to demonstrate the kit's brand kit format and example output quality. Not a live client account.
+
+---
+
+## DELIVERABLES LOG
+
+<!-- - YYYY-MM-DD | Social Media Campaign Package v1 — Growthub Q2 2026 Launch | output/growthub/q2-2026-launch/ -->

package/assets/worker-kits/growthub-postiz-social-v1/bundles/growthub-postiz-social-v1.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-postiz-social-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-postiz-social-v1",
+    "workerId": "postiz-social-operator"
+  },
+  "briefType": "postiz-social-media-campaign",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/postiz-social-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/clone-fork.sh",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/social-campaign-brief.md",
+    "templates/content-calendar.md",
+    "templates/platform-publishing-plan.md",
+    "templates/caption-copy-deck.md",
+    "templates/analytics-brief.md",
+    "templates/scheduling-manifest.md",
+    "templates/client-proposal.md",
+    "examples/social-campaign-sample.md",
+    "examples/content-calendar-sample.md",
+    "examples/analytics-brief-sample.md",
+    "examples/client-proposal-sample.md",
+    "docs/postiz-fork-integration.md",
+    "docs/platform-coverage.md",
+    "docs/ai-caption-layer.md",
+    "docs/bullmq-queue-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-postiz-social-v1",
+    "zipFileName": "growthub-agent-worker-kit-postiz-social-v1.zip"
+  },
+  "activationModes": ["export"]
+}

package/assets/worker-kits/growthub-postiz-social-v1/docs/ai-caption-layer.md

@@ -0,0 +1,118 @@
+# AI Caption Layer
+
+**Methodology for AI-assisted caption generation in the Postiz Social Media Operator.**
+
+---
+
+## Overview
+
+The AI caption layer produces A/B/C caption variants for every post in the content calendar. This document defines the tone profiles, variant construction rules, and quality bar applied to every caption draft.
+
+The agent generates captions using:
+1. The brand kit's voice guidelines (`brands/<client-slug>/brand-kit.md`)
+2. The platform tone profiles defined in this document
+3. The theme pillar context from the Social Campaign Brief
+4. The character limits and hashtag rules from `docs/platform-coverage.md`
+
+---
+
+## Platform Tone Profiles
+
+| Platform | Tone | Voice | Avoid |
+|---|---|---|---|
+| Instagram | Visual-first, aspirational, authentic | First-person POV, sensory language, short punchy sentences | Corporate jargon, excessive hashtags, stock-photo clichés |
+| LinkedIn | Professional, insight-driven, confident | Data-backed claims, industry terminology, no jargon | Salesy language, superlatives without proof, informal slang |
+| TikTok | Casual, trend-aware, energetic, hook-first | Gen Z cadence, pattern interrupt, hook in first 2 words | Formal tone, long sentences, no emoji, corporate speak |
+| X/Twitter | Concise, punchy, opinionated | Declarative sentences, take-first, thread-opening hooks | Wishy-washy hedging, long-winded intros, excessive hashtags |
+| Pinterest | Aspirational, instructional, keyword-rich | Descriptive, actionable verbs, lifestyle context | Vague descriptions, missing context, non-searchable language |
+| Facebook | Conversational, community-first, warm | Inclusive "we/our", questions, local/personal context | Overly promotional, algorithm-bait language |
+| Bluesky | Direct, open-web-aware, intellectual | Concise, tech-savvy, first-principles reasoning | Overly polished PR-speak, platform-specific references |
+| Mastodon | Community-focused, inclusive, decentralization-aware | Plain language, CamelCase hashtags for accessibility | Algorithmic optimization language, commercial urgency |
+| Reddit | Authentic, community-native, contribution-first | Reddit idioms where appropriate, value-first, no self-promotion optics | Obvious promotional tone, link dumps without context |
+
+---
+
+## Variant Construction Rules
+
+### Variant A — Direct / Factual
+
+- Lead with the core fact, data point, or product statement
+- Second sentence: supporting evidence or context
+- Third sentence (if length allows): CTA
+- Tone: confident, no hedging language
+- Use numbers when available: "78% of marketers say..." outperforms "many marketers say..."
+
+**Structure template:**
+```
+[Core claim or insight.] [Evidence or context.] [CTA verb phrase.]
+```
+
+### Variant B — Storytelling / Narrative
+
+- Open with a scene, scenario, or relatable before-state
+- Middle: transition to the insight or product context
+- Close: resolution or CTA
+- Tone: warm, specific, first-person or second-person
+
+**Structure template:**
+```
+[Scene/scenario that the audience recognizes.] [Transition: "That's when we realized..." / "Here's what changed..."] [Insight or product context.] [CTA.]
+```
+
+### Variant C — Question / Engagement Hook
+
+- Open with a direct question or provocative statement
+- The question must be genuinely answerable in comments
+- Follow with 1–2 supporting sentences before the CTA
+- Tone: curious, conversational, invites participation
+
+**Structure template:**
+```
+[Question the audience wants to answer?] [Context that makes the question worth answering.] [CTA that directs to comment or click.]
+```
+
+---
+
+## Character Limit Compliance
+
+Every caption variant must be checked against the platform character limit before being considered complete. The agent must note the character count in the Caption Copy Deck entry.
+
+| Platform | Hard Limit | Target Range | Notes |
+|---|---|---|---|
+| Instagram | 2,200 | ≤150 (above fold) / up to 500 for educational | First 125 chars are critical — fold cuts here on mobile |
+| LinkedIn | 3,000 | 150–300 for opening hook | Algorithm may suppress posts with very short captions on company pages |
+| TikTok | 2,200 | ≤150 | First 150 chars visible before "more" |
+| X/Twitter | 280 | ≤240 | Leave 40 chars for RT space |
+| Pinterest | 500 | 100–300 | Keyword density matters for discovery |
+| Bluesky | 300 | ≤280 | Hard limit — truncation destroys message |
+| Mastodon | 500 | ≤400 | Instance limits may vary |
+| Reddit | Variable | Long-form (300–1000 words) for text posts | Subreddit rules override; check before drafting |
+
+---
+
+## Emoji Usage Guidelines
+
+| Platform | Usage Level | Notes |
+|---|---|---|
+| Instagram | Moderate (2–5 per caption) | Use as visual separators and tone enhancers |
+| LinkedIn | Minimal (0–2 per post) | Bullets acceptable on company pages; personal posts: 0–1 |
+| TikTok | Liberal (5–10) | Emoji-first hooks are platform-native |
+| X/Twitter | Minimal (0–2) | One emoji at start of tweet is acceptable; more feels crowded |
+| Pinterest | None to minimal (0–2) | Focuses on keyword discoverability |
+| Facebook | Moderate (2–4) | Consistent with casual community tone |
+| Bluesky | Minimal (0–2) | Text-first culture |
+| Mastodon | None to minimal | Accessibility-first: screen readers read emoji alt-text |
+
+---
+
+## AI Caption Quality Bar
+
+A complete caption variant must:
+
+1. **Stay within character limits** — hard requirement, not optional
+2. **Have an explicit CTA** — at minimum: "Learn more", "Link in bio", "Comment below", "Drop your thoughts"
+3. **Match platform tone** — LinkedIn caption must not read like a TikTok caption
+4. **Reference the content** — caption must connect to the media asset or post topic
+5. **Not open with "I"** — Instagram algorithm and general best practice: lead with the hook, not the subject
+6. **Avoid placeholder language** — no "[INSERT BRAND NAME]" fragments in the final copy deck
+7. **Be meaningfully different across A/B/C** — changing one word does not constitute a variant