@growthub/cli 0.3.56 → 0.3.58

package/assets/worker-kits/growthub-zernio-social-v1/docs/posts-and-queues-layer.md

@@ -0,0 +1,208 @@
+# Posts + Queues Layer
+
+This document specifies the JSON shapes the operator must produce. Every shape is a valid request body for the corresponding Zernio REST endpoint, so manifests can be piped directly into `curl` or the Zernio SDKs with no re-shaping.
+
+---
+
+## Scheduling Manifest
+
+The scheduling manifest is the machine-readable record the operator writes to `output/<client-slug>/<project-slug>/scheduling-manifest.json` whenever scheduling is requested.
+
+### Top-level shape
+
+```json
+{
+  "zernioSchedulingManifest": {
+    "version": "1.0",
+    "profileId": "<ZERNIO_PROFILE_ID>",
+    "timezone": "America/New_York",
+    "dryRun": false,
+    "generatedAt": "2026-04-15T14:30:00-04:00",
+    "notes": "<free-form operator notes — kept with the manifest>",
+    "posts": [ /* post entries */ ]
+  }
+}
+```
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `version` | Yes | string | Manifest schema version. Current: `"1.0"`. |
+| `profileId` | Yes | string | Must be a real Zernio profile id in api-live mode. In agent-only mode may be `"placeholder"` provided `dryRun: true`. |
+| `timezone` | Yes | string | IANA name. Default: value of `ZERNIO_TIMEZONE` or the profile's default. |
+| `dryRun` | Yes | boolean | `true` in agent-only mode. `false` in api-live and hybrid modes. |
+| `generatedAt` | Yes | string | ISO 8601 with tz offset. |
+| `notes` | No | string | Free-form notes — kept with the manifest for audit. |
+| `posts` | Yes | array | 1..N entries. |
+
+### Per-post entry shape
+
+Each entry is a direct body for `POST /api/v1/posts`, with two additional fields the operator uses for bookkeeping (`clientPostId`, `status`).
+
+```json
+{
+  "clientPostId": "urban-cycle-20260501-001",
+  "content": "Launch day — shipping our spring gravel lineup. Ride it today →",
+  "scheduledFor": "2026-05-01T09:00:00-04:00",
+  "timezone": "America/New_York",
+  "media": [{ "mediaId": "med_HERO_01" }],
+  "platforms": [
+    { "platform": "instagram", "accountId": "acc_ig_UrbanCycle" },
+    { "platform": "twitter",   "accountId": "acc_x_UrbanCycle" }
+  ],
+  "status": "pending"
+}
+```
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `clientPostId` | Yes | string | Operator-generated id. Format: `<client-slug>-<YYYYMMDD>-<sequence>`. Used as the `Idempotency-Key` when submitting to Zernio. Not sent in the body. |
+| `content` | Yes | string | The selected caption variant. |
+| `scheduledFor` | Conditional | string | ISO 8601 with tz offset. Required unless the post is attached to a queue via `queueId`. |
+| `timezone` | Yes | string | IANA name. |
+| `media` | No | array | Array of `{ "mediaId": "<id>" }`. In api-live mode must reference real Zernio `mediaId` values obtained from `POST /api/v1/media`. |
+| `platforms` | Yes | array | 1..N `{ platform, accountId }`. Every `platform` must exist in `docs/platform-coverage.md`. |
+| `queueId` | Conditional | string | Only when the post is attached to a queue. Mutually exclusive with `scheduledFor`. |
+| `status` | Yes | string | Operator bookkeeping. Always starts at `"pending"` and transitions to `"scheduled"` / `"published"` / `"failed"` once Zernio confirms. |
+
+### Submitting a manifest
+
+Each entry becomes one Zernio POST:
+
+```bash
+curl -sS -X POST \
+  "${ZERNIO_API_URL:-https://zernio.com/api/v1}/posts" \
+  -H "Authorization: Bearer ${ZERNIO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: <clientPostId>" \
+  --data-binary @- <<'JSON'
+{
+  "profileId": "prof_abc123",
+  "content": "...",
+  "scheduledFor": "2026-05-01T09:00:00-04:00",
+  "timezone": "America/New_York",
+  "media": [{ "mediaId": "med_HERO_01" }],
+  "platforms": [{ "platform": "twitter", "accountId": "acc_x_111" }]
+}
+JSON
+```
+
+The operator is responsible for issuing one request per `posts[]` entry and for retrying on 429/5xx with the same `Idempotency-Key`.
+
+---
+
+## Recurring Queue Definition
+
+Queues define a repeating schedule on a profile. Posts attached to a queue auto-schedule into the next available slot.
+
+### Queue shape
+
+Body of `POST /api/v1/queues` and `PUT /api/v1/queues/<queueId>`:
+
+```json
+{
+  "profileId": "prof_abc123",
+  "name": "weekly-evergreen",
+  "timezone": "America/New_York",
+  "slots": [
+    { "day": "mon", "time": "09:00", "platforms": ["twitter", "linkedin"] },
+    { "day": "wed", "time": "12:30", "platforms": ["instagram"] },
+    { "day": "fri", "time": "17:00", "platforms": ["bluesky", "threads"] }
+  ]
+}
+```
+
+| Field | Required | Type | Notes |
+|---|---|---|---|
+| `profileId` | Yes | string | Zernio profile owning the queue. |
+| `name` | Yes | string | Lowercase kebab-case recommended. |
+| `timezone` | Yes | string | IANA name. |
+| `slots` | Yes | array | 1..N slots. |
+| `slots[].day` | Yes | string | One of `mon|tue|wed|thu|fri|sat|sun`. |
+| `slots[].time` | Yes | string | `HH:MM` 24-hour. |
+| `slots[].platforms` | Yes | array | Platforms enabled for this slot. |
+
+### Post attached to a queue
+
+```json
+{
+  "profileId": "prof_abc123",
+  "queueId": "que_xyz789",
+  "content": "Weekend builder log: three wins, one lesson.",
+  "platforms": [{ "platform": "twitter", "accountId": "acc_x_111" }]
+}
+```
+
+The request is still `POST /api/v1/posts` but with `queueId` instead of `scheduledFor`. Zernio returns the computed `scheduledFor` in the response.
+
+### Queue deliverable in the kit
+
+The operator writes a queue definition alongside the scheduling manifest as:
+
+```
+output/<client-slug>/<project-slug>/queue-<queue-name>.json
+```
+
+The file contains one JSON object — the `zernioQueue` wrapper below — so that it reads as documentation plus a ready-to-submit request body.
+
+```json
+{
+  "zernioQueue": {
+    "version": "1.0",
+    "profileId": "<ZERNIO_PROFILE_ID>",
+    "dryRun": false,
+    "queue": {
+      "profileId": "<ZERNIO_PROFILE_ID>",
+      "name": "weekly-evergreen",
+      "timezone": "America/New_York",
+      "slots": [
+        { "day": "mon", "time": "09:00", "platforms": ["twitter", "linkedin"] }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Media Upload
+
+Every image or video referenced by a post must be uploaded first.
+
+```bash
+curl -sS -X POST \
+  "${ZERNIO_API_URL:-https://zernio.com/api/v1}/media" \
+  -H "Authorization: Bearer ${ZERNIO_API_KEY}" \
+  -H "Idempotency-Key: media-urban-cycle-20260501-hero-01" \
+  -F "file=@./media/urban-cycle/hero-01.png" \
+  -F "profileId=prof_abc123"
+```
+
+The response includes `mediaId`. That id is what the scheduling manifest references.
+
+In `agent-only` mode the operator emits placeholder `mediaId` values prefixed with `placeholder_` and documents the required asset in the Caption Copy Deck's "Media Notes" column. The user uploads the real media and replaces placeholders before submitting.
+
+---
+
+## Idempotency Contract
+
+| Endpoint | Idempotency key source |
+|---|---|
+| `POST /api/v1/posts` | `clientPostId` from the manifest entry |
+| `POST /api/v1/queues` | `queue.name` prefixed with `queue-` |
+| `POST /api/v1/media` | `media-<client-slug>-<YYYYMMDD>-<asset-slug>` |
+
+The operator must NEVER send different bodies under the same `Idempotency-Key`. If content changes, increment the manifest version and use a new key.
+
+---
+
+## Validation Rules (pre-submission)
+
+Before any submission, re-run through `validation-checklist.md`. Specifically:
+
+- Every `posts[].platforms[].platform` exists in `docs/platform-coverage.md`
+- Every `clientPostId` matches the filename conventions in `output-standards.md`
+- `scheduledFor` timestamps all fall inside the campaign window from the Social Campaign Brief
+- `dryRun` matches the declared execution mode
+- No post entry exceeds per-platform character limits from `docs/ai-caption-layer.md`
+
+Failure on any of these is a blocker — fix the manifest before submitting.

package/assets/worker-kits/growthub-zernio-social-v1/docs/zernio-api-integration.md

@@ -0,0 +1,265 @@
+# Zernio API Integration
+
+This document is the reference contract between the `growthub-zernio-social-v1` kit and the [Zernio](https://zernio.com) REST API. It is frozen at kit creation and should be updated when the upstream API contract changes.
+
+> Source of truth upstream: [docs.zernio.com](https://docs.zernio.com). When this document conflicts with live Zernio docs, the live docs win; update this file and the kit version.
+
+---
+
+## Base Contract
+
+| Field | Value |
+|---|---|
+| Base URL | `https://zernio.com/api/v1` |
+| Env var | `ZERNIO_API_URL` (override only for regional / proxy deployments) |
+| Transport | HTTPS only |
+| Request content type | `application/json` (JSON endpoints) · `multipart/form-data` (`/media` upload) |
+| Response content type | `application/json` |
+| Character encoding | UTF-8 |
+
+---
+
+## Authentication
+
+Every request carries a single bearer header:
+
+```
+Authorization: Bearer ${ZERNIO_API_KEY}
+```
+
+### Key format
+
+- Prefix: `sk_`
+- Body: 64 hex characters
+- Total length: 67 characters
+
+Regex: `^sk_[0-9a-fA-F]{64}$`
+
+### Key scopes
+
+| Scope | Purpose |
+|---|---|
+| `read` | Read-only endpoints only (profiles, accounts, analytics, inbox listing) |
+| `read-write` | Everything in `read` plus create/update posts, queues, media, and inbox replies |
+
+### Key scope filter
+
+An individual key may be scoped `full` (any profile on the account) or `profiles-specific` (restricted to a list of profile IDs).
+
+### Idempotency
+
+Attach an `Idempotency-Key` header to every write request. The operator uses the `clientPostId` from the scheduling manifest as the idempotency key so the manifest can be re-submitted safely.
+
+---
+
+## Core Resource Model
+
+Zernio models social publishing around five primary resources:
+
+| Resource | Endpoint root | Role |
+|---|---|---|
+| Profiles | `/api/v1/profiles` | A container that groups social accounts. Every request is implicitly scoped to one profile for scheduling. |
+| Accounts | `/api/v1/accounts` | A connected social account that belongs to a profile. Identified by `accountId`. |
+| Posts | `/api/v1/posts` | Schedulable content. One post can fan out to many `{ platform, accountId }` pairs. |
+| Queues | `/api/v1/queues` | Recurring time-slot schedule attached to a profile. Posts added to a queue auto-schedule into the next open slot. |
+| Media | `/api/v1/media` | Image, video, and document assets uploaded once and referenced by `mediaId` from a post body. |
+
+Two secondary resources:
+
+| Resource | Endpoint root | Role |
+|---|---|---|
+| Inbox | `/api/v1/inbox` | Unified DM, comment, and review conversations aggregated per profile. |
+| Analytics | `/api/v1/analytics` | Per-post and per-account metrics. |
+
+Supporting endpoints:
+
+| Endpoint | Role |
+|---|---|
+| `/api/v1/api-keys` | Create, list, rotate, and revoke API keys |
+| `/api/v1/connect/<platform>` | Begin platform OAuth / credential flow for a new account on a profile |
+| `/api/v1/platforms` | Live list of supported platforms and their per-platform capability flags |
+
+Extended capability surface (confirmed in `zernio-cli`, may be plan-gated):
+
+| Resource | Endpoint root | Role |
+|---|---|---|
+| Contacts | `/api/v1/contacts` | CRUD + bulk create + custom fields |
+| Broadcasts | `/api/v1/broadcasts` | Create / schedule / send / cancel + recipient management |
+| Sequences | `/api/v1/sequences` | Create / activate / pause + enrollment management |
+| Automations | `/api/v1/automations` | Create / run / inspect execution logs |
+| Webhooks | `/api/v1/webhooks` | Settings (create/update) + logs + signature verification; events include `account.connected`, `post.recycled` |
+
+The zernio-social-operator uses these endpoints only when the user explicitly asks for CRM-shaped work (contacts / broadcasts / sequences) or wants an automation wired into a campaign. Default campaign flow stays scoped to posts + queues + media + inbox + analytics.
+
+---
+
+## Endpoints Used By This Kit
+
+### Profiles
+
+- `GET /api/v1/profiles` — list profiles on the account
+- `GET /api/v1/profiles/<profileId>` — fetch a single profile, including the default timezone
+
+### Accounts
+
+- `GET /api/v1/accounts?profileId=<id>` — list connected accounts on a profile (platform + handle + accountId)
+
+### Media upload
+
+- `POST /api/v1/media` — multipart upload; response includes `mediaId`
+- `GET /api/v1/media/<mediaId>` — fetch metadata of an uploaded asset
+
+### Posts
+
+- `POST /api/v1/posts` — schedule one post with fan-out targets
+- `GET /api/v1/posts?profileId=<id>&status=scheduled` — list scheduled posts
+- `GET /api/v1/posts/<postId>` — fetch a single post
+- `DELETE /api/v1/posts/<postId>` — unschedule a post (only while `status=scheduled`)
+
+Minimal `POST /api/v1/posts` body:
+
+```json
+{
+  "profileId": "prof_abc123",
+  "content": "Launch day — shipping our new kit. →",
+  "scheduledFor": "2026-05-01T09:00:00-04:00",
+  "timezone": "America/New_York",
+  "media": [{ "mediaId": "med_imgA" }],
+  "platforms": [
+    { "platform": "twitter",  "accountId": "acc_x_111" },
+    { "platform": "linkedin", "accountId": "acc_li_222" }
+  ]
+}
+```
+
+### Queues (recurring schedules)
+
+- `POST /api/v1/queues` — create a recurring queue
+- `GET /api/v1/queues?profileId=<id>` — list queues on a profile
+- `PUT /api/v1/queues/<queueId>` — replace queue configuration
+- `DELETE /api/v1/queues/<queueId>` — remove queue (future slots stop; already-scheduled posts remain)
+
+Minimal queue body:
+
+```json
+{
+  "profileId": "prof_abc123",
+  "name": "weekly-evergreen",
+  "timezone": "America/New_York",
+  "slots": [
+    { "day": "mon", "time": "09:00", "platforms": ["twitter", "linkedin"] },
+    { "day": "wed", "time": "12:30", "platforms": ["instagram"] },
+    { "day": "fri", "time": "17:00", "platforms": ["bluesky", "threads"] }
+  ]
+}
+```
+
+Posts attached to a queue omit `scheduledFor` and include `queueId` instead:
+
+```json
+{
+  "profileId": "prof_abc123",
+  "queueId": "que_xyz789",
+  "content": "Weekend builder log: three wins, one lesson.",
+  "platforms": [{ "platform": "twitter", "accountId": "acc_x_111" }]
+}
+```
+
+### Inbox (DMs, comments, reviews)
+
+- `GET /api/v1/inbox?profileId=<id>` — unified conversation list
+- `GET /api/v1/inbox/<conversationId>` — conversation thread
+- `POST /api/v1/inbox/<conversationId>/reply` — reply to a conversation
+
+### Analytics
+
+- `GET /api/v1/analytics/posts?profileId=<id>&from=<date>&to=<date>` — per-post metrics
+- `GET /api/v1/analytics/accounts?profileId=<id>&from=<date>&to=<date>` — per-account summary
+
+### API keys
+
+- `POST /api/v1/api-keys` — create a new key with `scope` and `permission`
+- `GET /api/v1/api-keys` — list existing keys
+- `DELETE /api/v1/api-keys/<keyId>` — revoke a key
+
+---
+
+## Error Model
+
+All non-2xx responses return:
+
+```json
+{
+  "error": {
+    "code": "<machine_readable_code>",
+    "message": "<human readable>",
+    "requestId": "<uuid>"
+  }
+}
+```
+
+Well-known codes the operator handles:
+
+| HTTP | Zernio code | Behavior |
+|---|---|---|
+| 401 | `auth_invalid` | Key missing / malformed / revoked — surface to user, fall back to agent-only |
+| 403 | `permission_denied` | Key lacks `read-write` scope — surface with rotate-instructions |
+| 404 | `profile_not_found` / `account_not_found` | Correct the id or fall back to dry-run |
+| 409 | `conflict` | Typically an idempotency collision; safe to treat as success |
+| 422 | `validation_failed` | Manifest shape bug — fix and retry |
+| 429 | `rate_limited` | Back off using `Retry-After` header |
+| 5xx | `internal_error` | Retry with exponential backoff up to 3 attempts |
+
+---
+
+## Plans and Quotas (as-of kit freeze)
+
+| Plan | Monthly | Annual (per mo) | Profiles | Posts / month | Notes |
+|---|---|---|---|---|---|
+| Free | $0 | $0 | 2 | 20 | Full REST API access; useful for prototypes |
+| Build | $19 | $16 | 10 | 120 | First paid tier |
+| Accelerate | $49 | $41 | 50 | unlimited | Recommended for agencies + multi-client operators |
+| Unlimited | $999 | $833 | unlimited | unlimited | Enterprise; includes higher support SLA |
+
+All plans ship the same REST contract (posts, queues, accounts, profiles, media, inbox, analytics, contacts, broadcasts, sequences, automations, webhooks, api-keys, connect, platforms). The post-count gate is the main throttle across tiers. Rate limit is 60 requests/minute per API key at every tier.
+
+The operator must degrade gracefully when a quota is hit: surface the Zernio error code (`rate_limited`, `quota_exhausted`) to the user, offer to switch the session into `agent-only` mode, and never silently drop scheduled posts.
+
+## Rate Limit Handling
+
+Default plan: 60 requests/minute per API key. The operator batches reads during account inspection and never issues more than one write per post per second.
+
+When a 429 is returned:
+
+1. Read `Retry-After` header (seconds)
+2. Sleep for the returned value plus 500ms jitter
+3. Retry the same request with the same `Idempotency-Key`
+4. On third failure, stop and report to the user
+
+---
+
+## SDK + Harness Options (informational)
+
+Zernio ships official SDKs for Node.js, Python, Go, Ruby, Java, PHP, .NET, and Rust. Source repos live under [github.com/zernio-dev](https://github.com/zernio-dev).
+
+Two primitives are directly relevant to local AI coding environments:
+
+| Primitive | Distribution | Use from | Install |
+|---|---|---|---|
+| Official MCP server | bundled inside `zernio-python` | Claude Desktop, Claude Code, Cursor, any MCP-compatible IDE | `pip install zernio-sdk[mcp]` |
+| Zernio API Claude Code skill | `zernio-api` repo | Claude Code only | `npx clawhub@latest install zernio-api` |
+
+This kit intentionally uses the **raw REST contract** via Node's built-in `fetch()` so the operator behaves identically regardless of which local IDE the user has installed. If the user additionally plugs in Zernio's MCP server or the Claude Code skill, that is strictly complementary — the kit does not depend on either.
+
+See `docs/local-adapters.md` for the per-IDE setup matrix and `setup/install-mcp.mjs` for the copy-paste MCP config JSON blocks.
+
+Kit files never install or require any Zernio SDK. If the user wants to install one locally for their own tooling, that is their choice and does not affect kit behavior.
+
+---
+
+## Security
+
+- `ZERNIO_API_KEY` lives only in `.env` (ignored by git) and the runtime environment
+- Outputs never include the raw key, request headers, or response payloads that contain keys
+- `scheduling-manifest.json` contains only `clientPostId`, content, timestamps, and Zernio resource IDs — no secrets
+- Any snippet of curl help in documentation uses `${ZERNIO_API_KEY}` as an expanded env var reference, never a literal

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

@@ -0,0 +1,97 @@
+# Analytics Brief — Growthub · Q2 2026 Agent-Native CLI Launch
+
+**Kit:** `growthub-zernio-social-v1`
+**Generated:** 2026-06-02
+**Mode:** api-live
+**Version:** `v1`
+
+---
+
+## Period Summary
+
+| Field | Value |
+|---|---|
+| Period | 2026-05-01 → 2026-05-30 |
+| Total posts published | 82 |
+| Platforms in scope | `twitter`, `linkedin`, `bluesky`, `youtube` |
+| Data source | Zernio `GET /api/v1/analytics/posts` + `GET /api/v1/analytics/accounts` |
+| Zernio profile id | prof_GRO_primary |
+
+---
+
+## Per-Platform Performance
+
+| Platform | Posts | Impressions | Reach | Engagement rate | Follower growth | Link clicks |
+|---|---|---|---|---|---|---|
+| `twitter` | 30 | 184,000 | 92,300 | 4.1% | +438 | 1,240 |
+| `linkedin` | 12 | 31,200 | 18,400 | 5.6% | +126 | 614 |
+| `bluesky` | 13 | 22,800 | 14,100 | 6.9% | +215 | 310 |
+| `youtube` | 9 videos (6 shorts, 3 long) | 64,500 | — | 7.2% (likes+comments / views) | +71 | — |
+
+Engagement rate = (likes + comments + shares) / impressions × 100, normalized per platform.
+
+---
+
+## Top 3 Posts
+
+| clientPostId | Platform | Date | Engagement rate | Why it worked |
+|---|---|---|---|---|
+| `growthub-20260514-022` | `twitter` | 2026-05-14 | 9.4% | Step-by-step thread on shipping a full campaign end-to-end landed on Hacker News; reply chain drove 60% of the engagement |
+| `growthub-20260501-001` | `twitter` | 2026-05-01 | 8.2% | Launch-day thread — `Agent Harness production-ready` framing matched developer Twitter's appetite for concrete builds |
+| `growthub-20260512-019` | `linkedin` | 2026-05-12 | 7.8% | Open-source maturity ladder carousel; carousel format on LinkedIn consistently beats plain text for diagram-driven content |
+
+---
+
+## Bottom 3 Posts
+
+| clientPostId | Platform | Date | Engagement rate | Hypothesis |
+|---|---|---|---|---|
+| `growthub-20260509-018` | `twitter` | 2026-05-09 | 0.9% | Weekend "what are you building" prompt — low re-share fuel, generic CTA. Replace with a pinned answer-question format next cycle. |
+| `growthub-20260517-026` | `bluesky` | 2026-05-17 | 1.6% | Sunday OSS spotlight posted after 20:00 local — Bluesky's text feed benefits from morning placement; re-slot to 10:00. |
+| `growthub-20260523-032` | `linkedin` | 2026-05-23 | 1.8% | Long-form text without visual on Saturday; LinkedIn engagement dips on weekends. Move weekend posts to X only. |
+
+---
+
+## Inbox Activity
+
+| Metric | Value |
+|---|---|
+| Open conversations (period start) | 6 |
+| Open conversations (period end) | 9 |
+| Avg first-response time | 38 minutes |
+| Replies sent | 64 |
+| Unresolved threads > 48h | 2 |
+
+Pulled via `GET /api/v1/inbox?profileId=prof_GRO_primary`.
+
+---
+
+## Recommendations
+
+1. **X/Twitter — double down on step-by-step threads.** Posts 22 and 01 each cleared 8% engagement. Schedule one full walkthrough thread per week anchored to a CLI command; target Thursday 12:00 local.
+2. **LinkedIn — move to carousel-first.** Carousel posts outperformed plain text by ~2.4× in this period. Convert the next three planned LinkedIn text posts into 5-slide carousels sized 1080×1080.
+3. **Bluesky — shift OSS spotlight to Sunday 10:00.** Data shows ≥2× engagement lift for morning placement versus evening on this audience.
+4. **Weekend cadence — concentrate on X only.** LinkedIn and Bluesky weekend posts underperform. Free that capacity for 1 extra X post per weekend instead.
+5. **YouTube Shorts — add captions-on by default.** Shorts with burned-in captions hit 7.9% engagement; shorts without hit 4.3%. Standardize captions-on in the platform publishing plan.
+
+---
+
+## Benchmark Comparison
+
+| Platform | Our engagement rate | Benchmark (developer-tool peers) | Delta |
+|---|---|---|---|
+| `twitter` | 4.1% | 3.2% | +0.9 pts |
+| `linkedin` | 5.6% | 4.0% | +1.6 pts |
+| `bluesky` | 6.9% | 5.5% | +1.4 pts |
+
+Benchmarks sourced from the brand kit's benchmark table.
+
+---
+
+## Source Queries
+
+```
+GET /api/v1/analytics/posts?profileId=prof_GRO_primary&from=2026-05-01&to=2026-05-30
+GET /api/v1/analytics/accounts?profileId=prof_GRO_primary&from=2026-05-01&to=2026-05-30
+GET /api/v1/inbox?profileId=prof_GRO_primary
+```

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

@@ -0,0 +1,106 @@
+# Client Proposal — Growthub · Q2 2026 Agent-Native CLI Launch
+
+**Kit:** `growthub-zernio-social-v1`
+**Generated:** 2026-04-15
+**Mode:** api-live
+**Version:** `v1`
+
+> Internal reference proposal for the Growthub flagship campaign. Demonstrates the expected format and grounding depth for a real client proposal.
+
+---
+
+## Campaign Overview
+
+| Field | Value |
+|---|---|
+| Client | Growthub |
+| Campaign | Q2 2026 Agent-Native CLI Launch |
+| Window | 2026-05-01 → 2026-05-30 |
+| Primary objective | Community growth (secondary: lead generation via CLI downloads) |
+| Platforms in scope | `twitter`, `linkedin`, `bluesky`, `youtube` |
+
+---
+
+## Platform Mix Rationale
+
+| Platform | Role in this campaign | Why selected |
+|---|---|---|
+| `twitter` | Anchor — daily technical commentary | Developer community is concentrated here; 280-char format fits our voice |
+| `linkedin` | B2B thought leadership + hiring signal | Partners and enterprise prospects live here; carousel format amplifies architectural content |
+| `bluesky` | Early-adopter tech audience | Strong overlap with the agent-tooling audience; text-first matches Growthub's style |
+| `youtube` | Long-form + shorts | Weekly long-form drives durable discovery; shorts feed the algorithm with CLI walkthroughs |
+
+Instagram is deferred until team capacity supports a sustained visual pipeline.
+
+---
+
+## Content Strategy
+
+- **Theme pillars:** Product Builds (35%), Developer Tutorials (30%), Open Source (20%), Community (15%)
+- **Format mix:** Threads on X, carousels on LinkedIn, long-form + shorts on YouTube, text on Bluesky
+- **Cadence:** X daily, LinkedIn 3×/week, Bluesky 3×/week, YouTube 1 long + 1 short/week
+- **Caption approach:** A/B/C variants per post — Variant A direct, B narrative, C question-hook. Selected variant is shipped; all three are logged for client review
+
+---
+
+## Deliverables Scope
+
+| Deliverable | Included | Notes |
+|---|---|---|
+| Social Campaign Brief | Yes | One-time at campaign start |
+| Content Calendar | Yes | 30-day plan, refreshed monthly |
+| Platform Publishing Plan | Yes | Per-platform format + time window |
+| Caption Copy Deck | Yes | A/B/C variants for every scheduled post |
+| Scheduling Manifest | Yes | Zernio-shaped JSON + submission to `POST /api/v1/posts` |
+| Recurring Queue | Yes | `weekly-build-log` for weekend community posts |
+| Analytics Brief | Monthly | Pulled from `GET /api/v1/analytics/*` |
+| Inbox reply coverage | Yes | Unified DMs/comments via `GET /api/v1/inbox` |
+
+---
+
+## Pricing Tiers
+
+| Tier | Scope | Monthly |
+|---|---|---|
+| Starter | 2 platforms, 3 posts/week, monthly analytics | $2,800 |
+| Growth | 4 platforms, daily posts, biweekly analytics, inbox coverage | $5,400 |
+| Scale | 6+ platforms, daily posts with queues, weekly analytics, priority inbox | $9,800 |
+
+Growthub's Q2 campaign fits **Growth** (4 platforms, daily posts, biweekly analytics, inbox coverage). Tier may move to Scale in Q3 if Instagram and Threads are added.
+
+---
+
+## ROI Projection
+
+Based on the brand-kit benchmarks and May 2026 forecast (extrapolated from April 2026 baseline):
+
+| KPI | Growth-tier target | Scale-tier upside |
+|---|---|---|
+| Impressions / month | 300,000 | 520,000 |
+| Engagement rate | 4.5% | 5.2% |
+| Follower growth | +750 | +1,200 |
+| Link clicks | 1,800 | 3,100 |
+| CLI downloads attributable to social | +1,000 | +1,800 |
+
+Assumptions: median developer-tool engagement rate ~3.2%; Growthub's recent baseline on X is 3.8%; incremental lift comes from disciplined A/B/C variant shipping and carousel-first on LinkedIn.
+
+---
+
+## Onboarding Plan
+
+1. Connect X, LinkedIn, Bluesky, YouTube inside Zernio (`/api/v1/connect/<platform>`)
+2. Confirm `ZERNIO_PROFILE_ID=prof_GRO_primary` and create a read-write API key scoped to it
+3. Review and approve Content Theme Pillars in the Social Campaign Brief
+4. Approve the Platform Publishing Plan and posting cadence
+5. Approve the Caption Copy Deck A/B/C variants (1–2 revision cycles expected)
+6. Submit the Scheduling Manifest with `Idempotency-Key = clientPostId`
+7. Cadence review at week 4 alongside the first Analytics Brief
+
+---
+
+## Terms
+
+- Content ownership stays with Growthub
+- `ZERNIO_API_KEY`, `ANTHROPIC_API_KEY`, and any per-platform OAuth tokens stay inside Growthub's Zernio account and local `.env` — never included in deliverables
+- Cancellation: 30-day written notice
+- Revisions: two full revision cycles per deliverable included in each tier