@growthub/cli 0.3.53 → 0.3.54

package/assets/worker-kits/growthub-postiz-social-v1/docs/bullmq-queue-layer.md

@@ -0,0 +1,157 @@
+# BullMQ Queue Layer
+
+**Scheduling manifest format and queue architecture for Postiz API submission.**
+
+---
+
+## Overview
+
+Postiz uses BullMQ (backed by Redis) as its job queue for scheduled post publishing. When this kit generates a scheduling manifest, it produces a JSON file that can be submitted to the Postiz API's bulk scheduling endpoint. The API enqueues each post with a delay calculated from `scheduledAt - now()`.
+
+---
+
+## Scheduling Manifest Format
+
+The full JSON format for the scheduling manifest:
+
+```json
+{
+  "postizSchedulingManifest": {
+    "version": "1.0",
+    "workspaceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "generatedAt": "2026-04-15T10:00:00-05:00",
+    "dryRun": false,
+    "posts": [
+      {
+        "postId": "urbancycle-20260420-instagram-001",
+        "platform": "instagram",
+        "scheduledAt": "2026-04-20T09:00:00-05:00",
+        "content": "Building for the long game means planting seeds you won't harvest for years. At Urban Cycle, we're still running routes we mapped in 2021. Where are you building today that you won't see pay off until 2028? Share in the comments — we read every one. #urbanmobility #sustainableliving #cycling",
+        "mediaAssets": [
+          {
+            "type": "image",
+            "path": "assets/2026-04-20-instagram-001.jpg",
+            "altText": "Urban Cycle team on a community cycling route, morning light"
+          }
+        ],
+        "tags": ["#urbanmobility", "#sustainableliving", "#cycling"],
+        "status": "pending"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `version` | string | Yes | Manifest version — always `"1.0"` for this kit |
+| `workspaceId` | string (UUID) | Yes | Postiz workspace UUID from Settings → Workspace |
+| `generatedAt` | string (ISO 8601) | Yes | Manifest generation timestamp |
+| `dryRun` | boolean | Yes | `true` for agent-only mode (no API submission); `false` for live submission |
+| `posts[].postId` | string | Yes | Unique post identifier — see naming convention below |
+| `posts[].platform` | string | Yes | Postiz platform integration ID (from `docs/platform-coverage.md`) |
+| `posts[].scheduledAt` | string (ISO 8601) | Yes | Target publish timestamp with timezone offset |
+| `posts[].content` | string | Yes | Full caption text (selected A/B/C variant) |
+| `posts[].mediaAssets` | array | No | Media asset references (empty array if text-only post) |
+| `posts[].mediaAssets[].type` | string | Yes | `"image"` \| `"video"` \| `"carousel"` |
+| `posts[].mediaAssets[].path` | string | Yes | Relative path to asset file |
+| `posts[].mediaAssets[].altText` | string | No | Accessibility alt text for images |
+| `posts[].tags` | array | No | Hashtag strings (with `#` prefix) |
+| `posts[].status` | string | Yes | Always `"pending"` in generated manifest |
+
+---
+
+## Post ID Naming Convention
+
+```
+<client-slug>-<YYYYMMDD>-<platform>-<sequence>
+```
+
+| Part | Rule | Example |
+|---|---|---|
+| client-slug | Lowercase, hyphenated, no special chars | `urban-cycle` |
+| YYYYMMDD | Scheduled post date | `20260420` |
+| platform | Postiz platform ID | `instagram` |
+| sequence | 3-digit zero-padded sequence | `001`, `002`, `003` |
+
+**Example:** `urban-cycle-20260420-instagram-001`
+
+---
+
+## Timestamp Format
+
+All `scheduledAt` values must use ISO 8601 format with explicit timezone offset:
+
+```
+YYYY-MM-DDTHH:MM:SS±HH:MM
+```
+
+**Examples:**
+- `2026-04-20T09:00:00-05:00` — 9am CDT
+- `2026-04-20T09:00:00-04:00` — 9am EDT
+- `2026-04-20T14:00:00Z` — 2pm UTC
+
+Never use `Z` for local time unless the workspace timezone is explicitly UTC.
+
+---
+
+## Submission to Postiz API
+
+```bash
+# Submit the scheduling manifest to Postiz bulk scheduling endpoint
+curl -X POST "${POSTIZ_API_URL}/api/v1/posts/bulk" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <jwt-token>" \
+  -d @scheduling-manifest.json
+
+# Verify queue health after submission
+curl "${POSTIZ_API_URL}/api/v1/queue/health" \
+  -H "Authorization: Bearer <jwt-token>"
+```
+
+Obtain the JWT token from Postiz admin UI → Settings → API Keys, or via `POST /api/v1/auth/login`.
+
+---
+
+## Queue Monitoring
+
+After submitting the manifest, monitor the BullMQ queue:
+
+1. **Postiz admin UI** → Queue Management: shows pending, active, completed, and failed jobs
+2. **API endpoint**: `GET /api/v1/queue/health` — returns queue stats
+3. **Redis CLI** (advanced): `redis-cli monitor` — raw job events
+
+### Job States
+
+| State | Meaning |
+|---|---|
+| `waiting` | Job is queued, delay has not expired |
+| `active` | Job is currently being processed (publishing now) |
+| `completed` | Post was published successfully |
+| `failed` | Post failed to publish — check error in admin UI |
+| `delayed` | Job is waiting for `scheduledAt` time |
+
+### Retry Logic
+
+Postiz retries failed publish jobs 3 times with exponential backoff by default:
+- Attempt 1: immediately after failure
+- Attempt 2: 5 seconds after first retry
+- Attempt 3: 30 seconds after second retry
+
+Failed jobs after 3 attempts are moved to the dead letter queue and visible in the admin UI → Failed Jobs.
+
+---
+
+## Dry-Run Mode
+
+When `dryRun: true` in the manifest header:
+- The manifest is produced as a JSON file but is **not submitted to the Postiz API**
+- All `status` fields remain `"pending"`
+- The manifest can be reviewed and submitted manually
+- Use `dryRun: true` in all agent-only mode sessions
+
+The agent must set `dryRun: true` automatically when the Postiz API is not reachable or when execution mode is `agent-only`.

package/assets/worker-kits/growthub-postiz-social-v1/docs/platform-coverage.md

@@ -0,0 +1,97 @@
+# Platform Coverage
+
+**Supported Postiz integration IDs, format specs, and character limits.**
+
+**Frozen at kit creation: 2026-04-15. Update when Postiz adds new platform integrations.**
+
+---
+
+## Platform Reference Table
+
+| Platform | Postiz ID | Auth Method | Post Types | Char Limit | Image Spec | Video Spec |
+|---|---|---|---|---|---|---|
+| Instagram | `instagram` | Meta OAuth | image, video, reel, story, carousel | 2,200 | 1080×1080 (square), 1080×1350 (portrait) | 1080×1920 (reels), MP4, ≤90s |
+| LinkedIn | `linkedin` | LinkedIn OAuth | text, image, video, document/carousel | 3,000 | 1200×627, PNG/JPG | MP4, ≤10 min |
+| TikTok | `tiktok` | TikTok OAuth | video only | 2,200 | — | 1080×1920, MP4/MOV, 15s–10min |
+| X (Twitter) | `twitter` | Twitter OAuth 2.0 | text, image, video, thread | 280 | 1200×675, ≤5MB | MP4/MOV, ≤2min 20s |
+| YouTube | `youtube` | Google OAuth | video (long-form), shorts | N/A | Thumbnail: 1280×720 | MP4, any length; Shorts ≤60s, 1080×1920 |
+| Pinterest | `pinterest` | Pinterest OAuth | image, video, idea pin | 500 | 1000×1500 (2:3 ratio) | MP4, 4s–15min |
+| Reddit | `reddit` | Reddit OAuth | text, image, video, link | — subreddit rules | Varies by subreddit | MP4, ≤15min |
+| Facebook | `facebook` | Meta OAuth | text, image, video, reel, story, carousel | 63,206 | 1200×628, PNG/JPG | MP4, ≤240min |
+| Bluesky | `bluesky` | AT Protocol credentials | text, image, video | 300 | Up to 4 images, 1×1 to 3×4 | MP4, ≤60s |
+| Mastodon | `mastodon` | OAuth (instance-specific) | text, image, video, poll | 500 (instance-configurable) | PNG/JPG/GIF/WebP | MP4/WebM/MOV |
+| Slack | `slack` | Slack OAuth | text, image, file | — | PNG/JPG/GIF | MP4 |
+| Telegram | `telegram` | Telegram Bot API token | text, image, video, document | 4,096 | JPEG, ≤10MB | MP4, ≤50MB |
+| Discord | `discord` | Discord Bot token | text, image, video, embed | 2,000 | PNG/JPG/GIF, ≤8MB | MP4, ≤8MB |
+| Threads | `threads` | Meta OAuth | text, image, video | 500 | 1:1 square; 4:5 portrait | MP4, ≤5min |
+| Dribbble | `dribbble` | Dribbble OAuth | image, video | — | PNG/JPG/GIF, ≤30MB | — |
+| Tumblr | `tumblr` | Tumblr OAuth | text, image, video, audio | — | PNG/JPG/GIF | MP4 |
+| Medium | `medium` | Medium OAuth | article (long-form markdown) | — | Embedded images | — |
+| DEV.to | `devto` | DEV API key | article (markdown) | — | Embedded images | — |
+| Hashnode | `hashnode` | Hashnode API key | article (markdown) | — | Embedded images | — |
+| Lemmy | `lemmy` | Lemmy credentials | text, image, link | — | PNG/JPG | — |
+| Nostr | `nostr` | Nostr keypair | text, image | — | URLs (no direct upload) | — |
+
+---
+
+## Platform Selection Guidance
+
+### Audience Demographics (2026 data — update when brand kit specifies more precise data)
+
+| Platform | Primary Demographic | Dominant Use Case |
+|---|---|---|
+| Instagram | 18–34 (55% female) | Visual branding, lifestyle, product showcase |
+| LinkedIn | 25–55 (professional) | B2B, thought leadership, hiring |
+| TikTok | 18–34 | Short-form entertainment, product discovery |
+| X/Twitter | 18–49 (male-skewed) | News, opinion, live commentary |
+| YouTube | All ages (18–49 core) | Education, reviews, entertainment |
+| Pinterest | 25–44 (female-skewed 70%) | Discovery, DIY, home, fashion, recipes |
+| Reddit | 18–49 (male-skewed) | Community discussion, niche interests |
+| Facebook | 35–65 | Community groups, local business, events |
+| Bluesky | 18–40 (tech-forward) | Open protocol social, tech and media |
+| Mastodon | 25–45 (tech-forward) | Open source, decentralized, privacy-aware |
+| LinkedIn | — | — |
+
+---
+
+## Post Type Compatibility Matrix
+
+| Post Type | instagram | linkedin | tiktok | twitter | youtube | pinterest | reddit | facebook | bluesky |
+|---|---|---|---|---|---|---|---|---|---|
+| Static Image | ✓ | ✓ | ✗ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ |
+| Video | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Carousel / Slides | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ | ✗ |
+| Text Only | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ |
+| Story | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ |
+| Reel / Short | ✓ | ✗ | ✓ | ✗ | ✓ (Shorts) | ✗ | ✗ | ✓ | ✗ |
+| Long-form Article | ✗ | ✓ (newsletter) | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ |
+
+---
+
+## Hashtag Best Practices by Platform
+
+| Platform | Recommended Count | Strategy |
+|---|---|---|
+| Instagram | 3–5 | Mix niche + medium-volume (avoid over-tagging) |
+| LinkedIn | 3–5 | Professional and industry-specific |
+| TikTok | 3–6 | Mix trending sounds + niche tags |
+| X/Twitter | 1–2 | In-text placement, campaign hashtags |
+| Pinterest | 2–3 | Keyword-based for discoverability |
+| Bluesky | 0–2 | Contextual only, rarely used |
+| Mastodon | 2–4 | CamelCase for accessibility |
+| Reddit | 0 | Subreddit flair instead |
+
+---
+
+## Posting Time Recommendations
+
+*Based on general industry data. Override with client's own analytics if available.*
+
+| Platform | Weekday Best Times (ET) | Weekend |
+|---|---|---|
+| Instagram | Mon–Fri: 9–11am, 6–8pm | Sat: 10am–12pm |
+| LinkedIn | Tue–Thu: 8–10am, 12pm | Minimal weekend activity |
+| TikTok | Mon–Fri: 7–9am, 7–9pm | Sat–Sun: 11am–1pm |
+| X/Twitter | Mon–Fri: 8–10am, 12–2pm | Limited |
+| Facebook | Tue–Thu: 9am–12pm | Sat: 12–1pm |
+| Pinterest | Sat–Sun: 2–4pm, 8–11pm | All day |

package/assets/worker-kits/growthub-postiz-social-v1/docs/postiz-fork-integration.md

@@ -0,0 +1,143 @@
+# Postiz Fork Integration
+
+**How this kit integrates with the Postiz open-source social media platform.**
+
+---
+
+## What Postiz Is
+
+[Postiz](https://github.com/gitroomhq/postiz-app) is an open-source, self-hosted social media scheduling and automation platform built on NestJS + Next.js. It supports 28+ social media platforms and ships with a BullMQ job queue, multi-workspace management, AI caption generation, media upload, and a public REST API.
+
+GitHub: https://github.com/gitroomhq/postiz-app
+License: MIT
+Stars: ~28,000+ (as of kit creation)
+
+---
+
+## Integration Architecture
+
+```
+growthub-postiz-social-v1 (this kit)
+  │
+  ├── workers/postiz-social-operator/CLAUDE.md
+  │     Agent operating law — drives campaign planning, caption drafts,
+  │     scheduling manifest generation, and analytics briefing
+  │
+  ├── setup/clone-fork.sh
+  │     Clones gitroomhq/postiz-app → ~/postiz-app
+  │     Runs docker compose up -d (starts Postiz + Redis + PostgreSQL)
+  │     Waits for API healthcheck at http://localhost:3000/api/healthcheck
+  │
+  ├── setup/verify-env.mjs
+  │     Checks fork existence, API reachability, POSTIZ_WORKSPACE_ID, ANTHROPIC_API_KEY
+  │
+  └── templates/scheduling-manifest.md
+        BullMQ-compatible JSON manifest format for bulk post scheduling
+        via POST /api/v1/posts/bulk
+```
+
+---
+
+## Service Topology
+
+When running in local-fork mode, Postiz operates as a Docker Compose stack:
+
+```
+postiz-app container (port 3000)
+  ├── NestJS API (apps/backend/)         ← REST API, BullMQ job scheduler
+  └── Next.js Frontend (apps/frontend/)  ← Admin UI, calendar view, analytics
+
+postiz-redis container (port 6379)
+  └── Redis                              ← BullMQ queue backend, session cache
+
+postiz-postgres container (port 5432)
+  └── PostgreSQL                         ← Posts, workspaces, platform credentials, analytics
+```
+
+All services are defined in `docker-compose.yml` at the fork root.
+
+---
+
+## Postiz API — Key Endpoints Used By This Kit
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/api/healthcheck` | GET | Verify Postiz is running |
+| `/api/v1/workspace` | GET | Retrieve workspace ID and metadata |
+| `/api/v1/posts/bulk` | POST | Submit scheduling manifest |
+| `/api/v1/posts/{id}` | GET | Verify a scheduled post |
+| `/api/v1/analytics` | GET | Retrieve engagement analytics |
+| `/api/v1/queue/health` | GET | Check BullMQ queue health |
+| `/api/v1/posts/ai/generate` | POST | AI caption generation (Postiz-side) |
+
+Authentication is via JWT bearer token. Obtain from Postiz admin UI → Settings → API Keys.
+
+---
+
+## Platform Integration Layer
+
+Platform integrations live under `libraries/nestjs-libraries/src/integrations/` in the Postiz repo. Each integration file:
+- Defines the OAuth flow for connecting the platform account
+- Implements `post()` for publishing content
+- Implements `analytics()` for pulling engagement data
+- Declares the integration ID (used as the `platform` field in scheduling manifests)
+
+When this kit generates a scheduling manifest, platform IDs must match the integration IDs in the running Postiz instance. See `docs/platform-coverage.md` for the full list.
+
+---
+
+## AI Caption Generation
+
+Postiz has its own AI caption generation endpoint (`/api/v1/posts/ai/generate`), activated when `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` is set in the Postiz `.env`. This is **separate** from the agent-side caption drafting in this kit.
+
+**This kit's caption workflow:**
+- The `postiz-social-operator` agent drafts A/B/C caption variants using its own reasoning and the AI caption methodology in `docs/ai-caption-layer.md`
+- Postiz's own AI caption feature is available to the user independently in the admin UI
+- The kit does not call the Postiz AI endpoint — it produces its own caption drafts
+
+---
+
+## BullMQ Queue Behavior
+
+When a post is submitted to Postiz via `POST /api/v1/posts/bulk`:
+
+1. Postiz validates the payload against the workspace's connected platforms
+2. Each post is enqueued in BullMQ with a delay calculated from `scheduledAt - now()`
+3. When the delay expires, BullMQ triggers the `publish-post` job
+4. The job calls the platform integration's `post()` method
+5. On success: post marked as `published` in PostgreSQL
+6. On failure: retried up to 3 times (configurable), then moved to dead letter queue
+
+Monitor the queue via Postiz admin UI → Queue Management, or via `GET /api/v1/queue/health`.
+
+---
+
+## Workspace Isolation
+
+Postiz supports multiple workspaces. Each workspace has:
+- Its own set of connected platform accounts
+- Its own posting queue
+- Its own analytics data
+- A UUID (`workspaceId`) required in all API calls
+
+The `POSTIZ_WORKSPACE_ID` in this kit's `.env` must match the workspace configured in the Postiz admin UI. Get it from Settings → Workspace in the admin UI, or from `GET /api/v1/workspace`.
+
+---
+
+## Inspecting the Fork Before Planning
+
+Before generating any campaign or scheduling manifest, inspect the running Postiz instance:
+
+```bash
+# Verify all containers are running
+docker compose ps
+
+# Check API health
+curl http://localhost:3000/api/healthcheck
+
+# List connected platform integrations (requires auth)
+curl http://localhost:3000/api/v1/integrations \
+  -H "Authorization: Bearer <jwt-token>"
+```
+
+Do not generate scheduling manifests for platforms that are not connected and authorized in the Postiz admin UI. Unconnected platform posts will fail at publish time.

package/assets/worker-kits/growthub-postiz-social-v1/examples/analytics-brief-sample.md

@@ -0,0 +1,125 @@
+# Analytics Brief — Sample
+
+<!-- Sample: Urban Cycle | Q2 2026 Urban Mobility Month | May 2026 | v1 | 2026-06-01 -->
+<!-- This is a filled example demonstrating the expected format. All metrics are fictitious but realistic. -->
+
+---
+
+## Period Summary
+
+| Field | Value |
+|---|---|
+| Client | Urban Cycle |
+| Campaign | Q2 2026 — Urban Mobility Month |
+| Period | 2026-05-01 to 2026-05-31 |
+| Platforms Analyzed | instagram, linkedin, twitter |
+| Total Posts Published | 52 |
+| Data Source | Client-provided platform export (Instagram Insights, LinkedIn Analytics, X Analytics) |
+
+---
+
+## Per-Platform Performance
+
+| Platform | Impressions | Reach | Engagement Rate | Follower Growth | Link Clicks | Posts Published |
+|---|---|---|---|---|---|---|
+| instagram | 28,450 | 14,200 | 4.1% | +612 | 487 (bio link) | 22 |
+| linkedin | 9,800 | 6,300 | 2.8% | +94 | 312 (post links) | 12 |
+| twitter | 11,200 | 8,700 | 1.9% | +128 | 156 | 18 |
+| **Totals** | **49,450** | **29,200** | **avg 2.9%** | **+834** | **955** | **52** |
+
+*Engagement Rate = (likes + comments + shares + saves) / impressions × 100*
+
+---
+
+## Top 3 Performing Posts
+
+### #1 Best Performing
+
+| Attribute | Value |
+|---|---|
+| Post Date | 2026-05-07 |
+| Platform | instagram |
+| Theme Pillar | Community Spotlight |
+| Post Type | Reel |
+| Impressions | 4,230 |
+| Engagement Rate | 8.7% |
+| Caption Preview | "Maria cycles 14km each way to her nursing shift. Every. Single. Day. Here's her route." |
+| Why It Worked | Community Spotlight Reels consistently outperform static images by 2–3x for this account. Maria's human story resonated — 127 saves, 43 comments. Reel format received Explore page placement. |
+
+---
+
+### #2 Best Performing
+
+| Attribute | Value |
+|---|---|
+| Post Date | 2026-05-05 |
+| Platform | linkedin |
+| Theme Pillar | Advocacy & Infrastructure |
+| Post Type | Text + image (infographic) |
+| Impressions | 2,800 |
+| Engagement Rate | 5.2% |
+| Caption Preview | "72% of urban commuters cite safety as the #1 barrier to cycling. Yet cities that invest in prot..." |
+| Why It Worked | Bike to Work Day (May 5) created organic interest in cycling safety data. The infographic format drove 47 saves. 12 comments from city planners and transportation professionals — organic reach into LinkedIn's professional niche. |
+
+---
+
+### #3 Best Performing
+
+| Attribute | Value |
+|---|---|
+| Post Date | 2026-05-14 |
+| Platform | instagram |
+| Theme Pillar | Gear & Technique |
+| Post Type | Carousel |
+| Impressions | 3,140 |
+| Engagement Rate | 6.1% |
+| Caption Preview | "5 locks that actually work (and 2 that don't). Swipe for the breakdown →" |
+| Why It Worked | Carousel format drove 89 saves — highest save count of the month. "Save this" CTA explicitly requests save behavior. Educational format with opinionated recommendations outperforms generic product posts. |
+
+---
+
+## Bottom 3 Performing Posts
+
+| Post Date | Platform | Theme | Engagement Rate | Failure Hypothesis |
+|---|---|---|---|---|
+| 2026-05-20 | twitter | Brand & Behind the Scenes | 0.6% | Brand origin story content underperforms on X — audience wants real-time commentary and opinions, not retrospective narrative. Recommend moving brand storytelling to Instagram only. |
+| 2026-05-13 | instagram | Route Stories | 1.2% | Posted on Victoria Day holiday weekend (May 13) — audience not active. Should have used this slot for a lighter community post or pushed the Route Story to the following Tuesday. |
+| 2026-05-18 | linkedin | Gear & Technique | 0.8% | Gear recommendations are not relevant to LinkedIn's Urban Cycle audience (B2B decision-makers, urban planners). Gear content should stay on Instagram and X. Platform-content mismatch. |
+
+---
+
+## KPI vs. Target Comparison
+
+| KPI | Target | Actual | Status |
+|---|---|---|---|
+| Impressions | 25,000 / month | 49,450 | Exceeded (+98%) |
+| Avg Engagement Rate | ≥3.5% Instagram | 4.1% Instagram | Met |
+| Follower Growth | +500 Instagram | +612 Instagram | Exceeded (+22%) |
+| Link Clicks | 300 (bio + LinkedIn) | 955 | Exceeded (+218%) |
+| UGC Posts #UrbanCycleMonth | ≥3 | 7 | Exceeded (+133%) |
+
+---
+
+## Recommendations for Next Period (June)
+
+1. **Increase Reel frequency on Instagram from 1x/week to 3x/week:** Reels account for 38% of total impressions on only 14% of posts. Shifting 2 static image slots to Reels should push Instagram impressions 40–60% higher with the same posting volume.
+
+2. **Shift X/Twitter posting time from 8am to 7:30am ET on weekdays:** Top-performing X posts came at 7:30am on days when the captions were tied to commute timing. Early morning commuter context drove 2.3× more replies than midday posts.
+
+3. **Remove Gear content from LinkedIn:** The two lowest-performing LinkedIn posts were gear recommendations. Replace with Advocacy & Infrastructure content (strongest LinkedIn performer) and bring LinkedIn gear coverage to 0% in June.
+
+4. **Launch a UGC challenge for June:** With 7 UGC posts in May (vs. 3 target), there's clear community enthusiasm. A branded June challenge (#RideWithUrbanCycle) with a weekly rider spotlight will compound community content without increasing production cost.
+
+5. **Test Variant C (question hook) on Instagram Thursday posts:** May analysis shows engagement rate 1.8× higher on posts that opened with a direct question. Currently only 30% of Instagram captions use Variant C. Shift Thursday posts to question-hook format for 4-week A/B test.
+
+---
+
+## Benchmark Comparison
+
+| Metric | Urban Cycle Result | Industry Benchmark | Source |
+|---|---|---|---|
+| Instagram engagement rate | 4.1% | 0.83%–1.22% (general); 3.0% for lifestyle/outdoor | Rival IQ 2026 Social Media Benchmark Report |
+| LinkedIn engagement rate | 2.8% | 0.35%–0.50% (company pages) | LinkedIn internal benchmark 2025 |
+| X/Twitter engagement rate | 1.9% | 0.05%–0.09% (general) | Rival IQ 2026 |
+
+*Urban Cycle is performing significantly above industry benchmarks across all three platforms. Above-average performance is driven by high-quality visual content, strong community focus, and consistent posting cadence.*

package/assets/worker-kits/growthub-postiz-social-v1/examples/client-proposal-sample.md

@@ -0,0 +1,127 @@
+# Social Media Campaign Proposal — Sample
+
+<!-- Sample: Urban Cycle | Q3 2026 Growth Campaign | v1 | 2026-06-01 -->
+<!-- This is a filled example demonstrating the expected format. Data is fictitious but realistic. -->
+
+---
+
+## Executive Summary
+
+Urban Cycle's May 2026 campaign exceeded all KPIs — 4.1% Instagram engagement rate (vs. 1.2% industry average), 49,450 total impressions (vs. 25,000 target), and 955 link clicks. The Q3 2026 proposal expands to 4 platforms (adding TikTok), increases Reel production to 3x/week, and introduces a monthly rider spotlight series that drove Urban Cycle's highest-performing post in May (8.7% engagement rate). Projected outcome: 120,000 monthly impressions and +1,500 followers by end of Q3.
+
+---
+
+## Campaign Overview
+
+| Field | Value |
+|---|---|
+| Proposed Campaign Name | Q3 2026 — Ride Every City |
+| Campaign Objective | Community growth + brand awareness + product launch (new route planner app) |
+| Recommended Platforms | instagram, tiktok, linkedin, twitter |
+| Campaign Duration | 90 days (July 1 – September 30, 2026) |
+| Total Posts | 270 posts across 4 platforms |
+| Start Date | 2026-07-01 (proposed) |
+
+---
+
+## Why These Platforms
+
+| Platform | Audience Fit | Primary Role in Campaign |
+|---|---|---|
+| instagram | 68% of Urban Cycle's target audience (urban cyclists, 25–40) is active on Instagram. Q2 data confirms 4.1% engagement — highest of any platform tested. | Brand awareness hub — Reels, carousels, community spotlights |
+| tiktok | Urban Cycle's 18–28 secondary audience segment is 3× more active on TikTok than Instagram. Short-form cycling route videos align with TikTok's discovery algorithm. New platform for Urban Cycle — expect 60-day ramp before organic growth signals emerge. | Audience growth, route content, app launch reach |
+| linkedin | B2B pipeline for corporate wellness programs and urban planning partnerships. May LinkedIn posts drove 312 link clicks to the route planner landing page — highest per-platform click rate. | Thought leadership, infrastructure advocacy, B2B pipeline |
+| twitter | Real-time community engagement during commute hours. Urban Cycle's X presence drove 7 UGC posts in May tied to live commute commentary. | Community engagement, newsjacking, advocacy moments |
+
+---
+
+## Content Strategy
+
+### Theme Pillars
+
+| Pillar | Description | % of Calendar | Key Formats |
+|---|---|---|---|
+| Route Stories | Real routes, real riders — city-specific commute coverage | 30% | Reels (Instagram + TikTok), route maps on X |
+| App Launch | Route Planner app features, onboarding, user stories | 25% | Carousels (Instagram + LinkedIn), demo videos (TikTok) |
+| Advocacy & Infrastructure | Cycling infrastructure wins and gaps — data-backed | 20% | LinkedIn long-form, Instagram infographics |
+| Rider Spotlight | Weekly spotlight — one real rider per week across all platforms | 15% | Reel (Instagram), short video (TikTok), text post (LinkedIn) |
+| Community & UGC | #RideWithUrbanCycle challenge, poll, community repair night coverage | 10% | Instagram Story, X text, LinkedIn community post |
+
+### Caption Strategy
+
+All captions will use A/B/C variant framework. Selection criteria:
+- Route Stories and App Launch → Variant A (direct, factual, product-specific)
+- Rider Spotlight → Variant B (narrative-first)
+- Community and Advocacy → Variant C (question hook for comments)
+
+---
+
+## Deliverables
+
+| Deliverable | Format | Cadence |
+|---|---|---|
+| Social Campaign Brief | Markdown | Once (at campaign start) |
+| Content Calendar | Markdown | Monthly refresh (3 deliveries) |
+| Platform Publishing Plan | Markdown | Once (at campaign start) |
+| Caption Copy Deck | Markdown | Monthly (A/B/C per post) |
+| Scheduling Manifest | JSON | Monthly (submitted on approval) |
+| Analytics Brief | Markdown | Monthly (3 deliveries) |
+| Q3 Campaign Wrap Report | Markdown | Once (at campaign end) |
+
+---
+
+## Engagement Tiers
+
+### Tier 1 — Campaign Starter
+
+**Scope:** 2 platforms (Instagram + LinkedIn), 3 posts/week each, 30-day calendar per month
+
+**Includes:** Campaign Brief, 30-day Content Calendar, Caption Copy Deck (A/B variants), Monthly Analytics Brief
+
+**Pricing:** $2,500/month
+
+**Best for:** Urban Cycle maintaining current Instagram + LinkedIn presence without TikTok expansion.
+
+---
+
+### Tier 2 — Multi-Platform Growth *(Recommended)*
+
+**Scope:** 4 platforms (Instagram + TikTok + LinkedIn + X), 5 posts/week Instagram and TikTok, 3x/week LinkedIn, daily X
+
+**Includes:** Full Campaign Brief, 90-day Content Calendar, Platform Publishing Plan, Caption Copy Deck (A/B/C), Scheduling Manifest (Postiz API), 3× Monthly Analytics Briefs
+
+**Pricing:** $6,500/month
+
+**Best for:** Urban Cycle's Q3 app launch requiring full platform saturation and Reel-first content strategy.
+
+---
+
+### Tier 3 — Full Social Media Operator
+
+**Scope:** 5 platforms including Pinterest (Q4 add), Reels 5x/week, weekly UGC challenge management, Postiz multi-workspace scheduling
+
+**Includes:** All Tier 2 deliverables + weekly analytics check-in, quarterly strategy review, Pinterest campaign, Postiz Scheduling API management
+
+**Pricing:** $11,000/month
+
+**Best for:** Urban Cycle treating social media as a primary growth channel with a dedicated content team producing assets.
+
+---
+
+## ROI Projection
+
+| Scenario | Baseline Assumptions | Projected Outcome by Sep 30 | Source |
+|---|---|---|---|
+| Conservative (Tier 1) | 2 platforms, 3 posts/week each, avg 2.5% engagement | 60,000 impressions/month; +400 followers/month | Q2 actual data + Rival IQ 2026 benchmark |
+| Mid (Tier 2 — Recommended) | 4 platforms, full cadence, Reel-first Instagram, TikTok launch | 120,000 impressions/month; +1,500 followers/month; 200 app downloads/month attributed to social | Q2 actuals + TikTok Reel discovery coefficient 3.2× |
+| Aggressive (Tier 3) | 5 platforms, daily Reels, UGC challenge, Postiz automation | 200,000 impressions/month; +2,500 followers/month; 500+ app installs attributed | Comparable brand case (Moov cycling app, Q1 2026) |
+
+---
+
+## Next Steps
+
+1. Select engagement tier (Tier 2 recommended based on Q3 app launch goals)
+2. Approve Q3 Campaign Brief (draft to be shared within 3 business days)
+3. Complete TikTok brand kit section (currently empty in brand kit)
+4. Connect Instagram, TikTok, LinkedIn, and X in Postiz admin UI
+5. Set campaign start date — earliest available: 2026-07-01