@growthub/cli 0.3.55 → 0.3.57

package/assets/worker-kits/growthub-zernio-social-v1/docs/postiz-ui-shell-integration.md

@@ -0,0 +1,166 @@
+# Postiz UI Shell + Zernio Engine — Integration Recipe
+
+This document is the canonical recipe for running `growthub-zernio-social-v1` as the engine layer underneath the stable `growthub-postiz-social-v1` kit's UI shell.
+
+**Read order:** `../runtime-assumptions.md` → `./zernio-api-integration.md` → this file.
+
+---
+
+## Architectural split
+
+| Layer | Owned by | What it does |
+|---|---|---|
+| Presentation | `growthub-postiz-social-v1` (Postiz UI) | Calendar, compose, analytics shell, team workspace |
+| Engine | `growthub-zernio-social-v1` (this kit) | Posts, queues, media, inbox, analytics transport against Zernio REST API |
+
+**Core principle:** Postiz stays the UI. Zernio replaces Postiz's native provider/posting engine. Nothing in Postiz's own database schema, Redis queue runner, React app, or auth/team/workspace system changes. The diff surface is the provider + publish-bridge layers only.
+
+---
+
+## The 7 Module Integration Map
+
+### Module 1 — Provider Override (Zernio as the transport)
+
+Postiz's provider system is where per-platform OAuth and posting normally live. Replace it with a single `ZernioProvider`:
+
+- `baseUrl` → `https://zernio.com/api/v1`
+- `authHeader` → `Authorization: Bearer ${ZERNIO_API_KEY}`
+- All 14 platforms route through this one provider — no per-platform OAuth apps on the Postiz side
+- Postiz's "Connect Account" UI validates `ZERNIO_API_KEY` instead of OAuth dancing — Zernio handles all OAuth upstream
+
+The config for this provider mirrors exactly `buildZernioSocialConfig()` in `cli/src/kits/core/index.ts`:
+
+```ts
+{
+  providerId: "zernio",
+  providerName: "Zernio (hosted)",
+  providerBaseUrl: "https://zernio.com/api/v1",
+  providerAuthField: "Authorization",
+  apiKeyEnvVar: "ZERNIO_API_KEY",
+  additionalRequiredEnvVars: ["ZERNIO_API_URL"],
+}
+```
+
+### Module 2 — Post Submission Bridge
+
+The Zernio operator already produces manifests shaped as valid `POST /api/v1/posts` bodies. The bridge:
+
+1. Intercepts Postiz's internal `publishPost()` call
+2. Transforms the Postiz post into a Zernio manifest entry (see `./posts-and-queues-layer.md`)
+3. Fires `POST ${ZERNIO_API_URL}/posts` with `Authorization: Bearer ${ZERNIO_API_KEY}` and `Idempotency-Key: <clientPostId>`
+4. Feeds Zernio's response back into Postiz's job tracker
+
+`clientPostId` format stays `<client-slug>-<YYYYMMDD>-<sequence>`. Re-submitting the same manifest under the same key is safe.
+
+### Module 3 — Queue Sync Layer
+
+Postiz's queue concept maps 1:1 onto Zernio queues (`POST /api/v1/queues`):
+
+- Postiz queue scheduler → Zernio `queues` endpoint (create) / `queues/<queueId>` (update)
+- `Idempotency-Key: queue-<name>` prevents double-fire on retry
+- Posts attached to a queue omit `scheduledFor` and include `queueId`
+- The 10-step `zernio-social-operator` workflow becomes the execution contract for each queue job
+
+### Module 4 — AI Caption Layer Surface
+
+The agent-side `/zernio` command surface replaces Postiz's native AI composer:
+
+- Postiz compose textarea → `/zernio captions` (or `/zernio campaign` for full scope)
+- Caption drafts come from the A/B/C variant rules in `./ai-caption-layer.md`
+- Claude Code runs as a background operator session; Postiz compose UI is the front-end trigger
+- The 10 `/zernio` subcommands wire into Postiz's compose surface as slash-quick-actions
+
+### Module 5 — Platform Coverage Config
+
+`./platform-coverage.md` is the source of truth for Postiz channel configuration:
+
+- Disable native Postiz channel handlers
+- Register 14 channels pointing to the Zernio transport from Module 1
+- The per-platform format spec (char limits, aspect ratios, post types, carousel eligibility, thread support, cadence) drives Postiz's per-channel validation + preview rendering
+- `skills.md` per-platform tone rules feed the compose UI's voice hints
+
+### Module 6 — ENV + Secret Surface
+
+Direct alignment — the cleanest module:
+
+| Kit env var | Postiz field |
+|---|---|
+| `ZERNIO_API_KEY` | provider credentials field (replaces all per-platform OAuth tokens) |
+| `ZERNIO_API_URL` | provider baseUrl override (regional/proxy deployments only) |
+| `ZERNIO_PROFILE_ID` | default profile scope for all write requests |
+| `ZERNIO_TIMEZONE` | default posting timezone when the profile's timezone isn't used |
+
+`setup/verify-env.mjs` and `setup/check-deps.sh` run as Postiz's pre-start health checks. The secret-hygiene scan (`sk_` + 64-hex leak detection from the kit test suite) is the canonical gate on any output or log line.
+
+### Module 7 — Workspace CLI Entry Point
+
+`@growthub/cli >= 0.3.57` is the operator terminal that sits beside Postiz:
+
+- `growthub kit download growthub-zernio-social-v1` — materialize the kit
+- `growthub kit path growthub-zernio-social-v1` — print the working-directory path
+- Point a Claude Code session at that folder; the operator handles the full 10-step workflow
+- Postiz UI reflects the output — scheduled posts, queue runs, generated captions, analytics
+- The 7 artifacts declared by `buildZernioSocialConfig()` (brief, calendar, publishing plan, caption deck, scheduling manifest, analytics brief, client proposal) are the canonical source of truth for what the UI shows
+
+---
+
+## Integration Sequence (request path)
+
+```
+Postiz UI (compose / schedule)
+        ↓
+Module 2 — Post Submission Bridge
+        ↓
+Module 1 — ZernioProvider (Authorization: Bearer ZERNIO_API_KEY)
+        ↓
+Zernio API  →  POST /api/v1/posts
+            +  POST /api/v1/queues
+            +  POST /api/v1/media
+            +  GET  /api/v1/inbox
+            +  GET  /api/v1/analytics/*
+        ↑
+Module 3 — Queue Sync reads back status
+        ↑
+Postiz Calendar / Analytics shell renders state
+```
+
+Claude Code + the `/zernio` surface sits **laterally** — it feeds the compose box in Postiz before submission, not inside the request path. This keeps the agent lane non-blocking for end-user UI latency.
+
+---
+
+## What Stays Untouched in Postiz
+
+| Layer | Status |
+|---|---|
+| Postgres schema | Unchanged |
+| Redis queue runner | Unchanged (different job payloads, same runner) |
+| React frontend | Unchanged (except the compose AI hook in Module 4) |
+| Auth / team / workspace | Unchanged |
+| Existing Postiz kit payload (`growthub-postiz-social-v1`) | Unchanged — it remains valid for self-hosted-only operators |
+
+This keeps the diff surface minimal and keeps `growthub-zernio-social-v1` fully isolated as the engine layer.
+
+---
+
+## Operator Setup Order (when paired with Postiz UI shell)
+
+1. Stand up Postiz via its own kit (`growthub kit download growthub-postiz-social-v1`) — optional if only the UI layer is desired
+2. Download this kit: `growthub kit download growthub-zernio-social-v1`
+3. Fill `.env` — `ZERNIO_API_KEY`, `ZERNIO_API_URL`, `ZERNIO_PROFILE_ID`
+4. Run `node setup/verify-env.mjs` (kit-level) and the Postiz pre-start checks
+5. Apply Modules 1–3 inside the Postiz fork (provider override, publish bridge, queue sync). Everything else stays default.
+6. Open Claude Code at the Zernio kit's exported folder for the `/zernio` surface
+
+Standalone (without Postiz UI): everything still works — the kit is self-contained, and Modules 1–3 are optional.
+
+---
+
+## Validation Before Go-Live
+
+- [ ] Zernio API key scope is `read-write`
+- [ ] `GET /api/v1/accounts?profileId=...` returns at least one connected platform
+- [ ] A dry-run manifest round-trips through Module 2 with a successful 2xx from `POST /api/v1/posts`
+- [ ] A queue definition round-trips through Module 3 with a returned `queueId`
+- [ ] Postiz channel list surfaces all 14 Zernio platform slugs from `./platform-coverage.md`
+- [ ] Compose surface calls into `/zernio captions` and renders A/B/C variants
+- [ ] Kit secret-hygiene scan on the Postiz fork's logs is clean

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