@growthub/cli 0.3.53 → 0.3.54

package/assets/worker-kits/growthub-postiz-social-v1/examples/content-calendar-sample.md

@@ -0,0 +1,75 @@
+# Content Calendar — Sample
+
+<!-- Sample: Urban Cycle | Q2 2026 Urban Mobility Month | v1 | 2026-04-15 -->
+<!-- This is a filled example demonstrating the expected format. Data is fictitious but realistic. -->
+
+---
+
+## Calendar Header
+
+| Field | Value |
+|---|---|
+| Client | Urban Cycle |
+| Campaign | Q2 2026 — Urban Mobility Month (Week 1 excerpt) |
+| Period | 2026-05-01 to 2026-05-07 |
+| Platforms | instagram, linkedin, twitter |
+| Total Posts (Week 1) | 11 |
+| Generated By | postiz-social-operator |
+
+---
+
+## Posting Cadence Summary
+
+| Platform | Posts/Week | Best Times (ET) | Content Mix |
+|---|---|---|---|
+| instagram | 5 | Mon/Wed/Fri: 9am; Tue/Thu: 7pm | 40% Route Stories, 30% Advocacy, 20% Gear, 10% Community |
+| linkedin | 3 | Tue: 8am, Thu: 8am, Sat: 10am | 50% Advocacy, 30% Community Spotlight, 20% Brand |
+| twitter | daily | 8am and 12pm | 40% Advocacy, 30% Route, 20% Community, 10% Gear |
+
+---
+
+## Content Calendar (Week 1 Sample)
+
+| Date | Day | Platform | Theme Pillar | Post Type | Caption Preview (first 100 chars) | CTA | Media Notes | Status |
+|---|---|---|---|---|---|---|---|---|
+| 2026-05-01 | Friday | instagram | Route Stories | image | "Friday route drop: The Lakeshore Loop — 8km of waterfront commuting bliss. No car lanes. No s..." | Link in bio | 1080×1350 portrait; sunrise on lake path; brand blue overlay in corner | draft |
+| 2026-05-01 | Friday | twitter | Advocacy | text | "May is Urban Mobility Month. 68% of people who live within 5km of work still drive. What would..." | What would change your commute? Reply below | Text only | draft |
+| 2026-05-03 | Sunday | instagram | Story | story | "Quick poll: Do you cycle to work? 🚲 YES / 🚗 Not yet" | Vote in story | Instagram Story format; brand template with poll sticker | draft |
+| 2026-05-04 | Monday | instagram | Advocacy & Infrastructure | image | "Amsterdam added 7km of protected bike lanes last month. That's more than most North American ci..." | Link in bio | 1080×1080 square; split-screen city comparison graphic | draft |
+| 2026-05-04 | Monday | twitter | Route Stories | text + image | "Your Monday commute route matters. Here's the Westside Cut — 12 minutes faster than the subway..." | Try the route — link in bio | 1200×675 landscape map image with route overlay | draft |
+| 2026-05-05 | Tuesday | linkedin | Advocacy | text + image | "72% of urban commuters cite safety as the #1 barrier to cycling. Yet cities that invest in prot..." | What infrastructure change would make you ride? Comment below | 1200×627 landscape; infographic on cycling safety stats | draft |
+| 2026-05-06 | Wednesday | instagram | Gear & Technique | carousel | "5 locks that actually work (and 2 that don't). Swipe for the breakdown →" | Save this | 5-slide carousel; 1080×1080; product photos + ratings | draft |
+| 2026-05-06 | Wednesday | twitter | Community | text | "Community repair night recap: 23 bikes tuned, 4 new riders taught their first brake adjust, 1 p..." | Find your local repair night — link in bio | Text only | draft |
+| 2026-05-07 | Thursday | linkedin | Community Spotlight | text + image | "Rider of the week: Maria C. — full-time nurse, 14km commute, 3 years running. No excuses, no c..." | Share your commute story in the comments | 1200×627; portrait photo of Maria with bike outside hospital | draft |
+| 2026-05-07 | Thursday | instagram | Community Spotlight | reel | "Maria cycles 14km each way to her nursing shift. Every. Single. Day. Here's her route." | Follow for weekly rider stories | 1080×1920 Reel; 30s; talking head + B-roll of commute route | draft |
+| 2026-05-07 | Thursday | twitter | Gear | text + image | "The one thing every urban cyclist needs but nobody talks about: a chain tensioner. Here's why →" | Reply with your go-to gear | 1200×675; product close-up with annotation | draft |
+
+---
+
+## Theme Distribution (Week 1)
+
+| Pillar | Posts | % of Week |
+|---|---|---|
+| Route Stories | 2 | 18% |
+| Advocacy & Infrastructure | 3 | 27% |
+| Gear & Technique | 2 | 18% |
+| Community Spotlight | 3 | 27% |
+| Story / Poll | 1 | 9% |
+
+---
+
+## Platform Distribution (Week 1)
+
+| Platform | Total Posts | % of Week |
+|---|---|---|
+| instagram | 6 | 55% |
+| linkedin | 2 | 18% |
+| twitter | 3 | 27% |
+
+---
+
+## Notes
+
+- May 5 (Tuesday) is Bike to Work Day — plan a campaign-specific post for all platforms
+- May 7 (Thursday) Maria Spotlight requires photo approval before scheduling
+- Blackout period: May 12–13 (Victoria Day weekend in Canada) — reduce LinkedIn frequency

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

@@ -0,0 +1,104 @@
+# Social Campaign Brief — Sample
+
+<!-- Sample: Urban Cycle | Q2 2026 Brand Awareness Campaign | v1 | 2026-04-15 -->
+<!-- This is a filled example demonstrating the expected detail level. Data is fictitious but realistic. -->
+
+---
+
+## Project Overview
+
+| Field | Value |
+|---|---|
+| Client | Urban Cycle |
+| Campaign Name | Q2 2026 — Urban Mobility Month |
+| Campaign Objective | Brand awareness + community growth |
+| Campaign Window | 2026-05-01 to 2026-06-30 |
+| Total Duration | 60 days |
+| Posting Cadence | 5x per week on Instagram; 3x per week on LinkedIn; daily on X |
+| Target Platforms | instagram, linkedin, twitter |
+| Execution Mode | agent-only |
+
+---
+
+## Campaign Objective
+
+Urban Cycle aims to establish itself as the leading brand voice in urban cycling advocacy during May and June 2026 — peak cycling season in North American cities. The campaign targets awareness and community building rather than direct conversion. Success is a 15% increase in Instagram followers, 25,000 monthly impressions across platforms, and at least 3 user-generated content posts tagged with #UrbanCycleMonth by campaign end.
+
+---
+
+## Target Platforms
+
+| Platform | Audience Fit | Content Format | Primary Goal |
+|---|---|---|---|
+| instagram | 68% of Urban Cycle's target demo (25–40, urban) are active Instagram users; visual platform aligns with cycling lifestyle | Static image, Reel, Story | Brand awareness, follower growth |
+| linkedin | B2B reach for cycling infrastructure decision-makers, urban planners, and corporate wellness buyers | Text + image, Document carousel | Thought leadership, B2B pipeline |
+| twitter | Real-time conversation during cycling events and advocacy moments; 42% of Urban Cycle's audience follows cycling news on X | Text, image | Community, newsjacking, advocacy |
+
+---
+
+## Audience Profile
+
+### Primary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | 25–40 |
+| Interests | Urban cycling, sustainability, active commuting, city planning |
+| Platforms Most Active | Instagram, X |
+| Pain Points | Lack of safe cycling infrastructure, inaccessible bike-share programs, no unified community platform |
+| Content Preferences | Inspiring imagery, practical route tips, advocacy wins, behind-the-scenes city cycling stories |
+
+### Secondary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | 18–25 |
+| Interests | Environmental activism, side hustles, fixie culture |
+| Platforms Most Active | Instagram, TikTok |
+
+---
+
+## KPI Targets
+
+| Metric | Target | Measurement Method |
+|---|---|---|
+| Impressions | 25,000 / month | Platform native analytics |
+| Engagement Rate | ≥3.5% on Instagram | (likes + comments + shares + saves) / impressions × 100 |
+| Follower Growth | +500 net new Instagram followers | Platform native |
+| Link Clicks | 300 clicks to urbancycle.com (bio link + LinkedIn posts) | UTM tracking |
+| UGC Posts | ≥3 posts tagged #UrbanCycleMonth | Manual search |
+
+---
+
+## Content Theme Pillars
+
+| Pillar | Theme | Content Mix | Example Topics |
+|---|---|---|---|
+| 1 | Route Stories | 35% | "Best commute routes in [city]", "Hidden cycling paths", "Weekend ride reports" |
+| 2 | Advocacy & Infrastructure | 25% | "Cities doing cycling right", "New bike lane wins", "Open letter to city planners" |
+| 3 | Gear & Technique | 20% | "Essential cycling gear for commuters", "Maintenance tips", "Lock your bike right" |
+| 4 | Community Spotlight | 15% | "Rider of the week", "Local group rides", "Community repair nights" |
+| 5 | Brand & Behind the Scenes | 5% | "How Urban Cycle started", "Meet the team", "What we're building next" |
+
+---
+
+## Brand Voice
+
+| Attribute | Spec |
+|---|---|
+| Tone | Passionate, community-first, data-informed. We advocate — we don't preach. |
+| Words to Use | "ride", "route", "commute", "community", "advocate", "city", "local" |
+| Words to Avoid | "disruptive", "hustle", "hack", "crush" |
+| Emoji Usage | 2–3 on Instagram, 0–1 on LinkedIn, 0–1 on X |
+| CTA Style | Community invitation: "Join us", "Share your route", "What's your city?", "Tag a rider" |
+
+---
+
+## Deliverables Scope
+
+- [x] Content Calendar (60 days, 3 platforms)
+- [x] Platform Publishing Plan
+- [x] Caption Copy Deck (A/B/C variants)
+- [ ] Scheduling Manifest (agent-only dry-run)
+- [ ] Analytics Brief (end of campaign)
+- [ ] Client Proposal

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

@@ -0,0 +1,128 @@
+# Growthub Meta — growthub-postiz-social-v1
+
+---
+
+## Kit Identity
+
+| Field | Value |
+|---|---|
+| Kit ID | `growthub-postiz-social-v1` |
+| Version | `1.0.0` |
+| Schema Version | `2` |
+| Type | `worker` |
+| Family | `operator` |
+| Execution Mode | `export` |
+| Activation Modes | `["export"]` |
+| Visibility | `public-open-source` |
+| Source Repo | `growthub-local` |
+| Frozen At | `2026-04-15T00:00:00.000Z` |
+
+---
+
+## What This Kit Does
+
+The Growthub Postiz Social Media Studio is a worker kit that wraps the [Postiz](https://github.com/gitroomhq/postiz-app) open-source social media scheduling platform (~28,000 GitHub stars, MIT license) to produce AI-assisted social media campaigns, content calendars, caption copy decks, and scheduling manifests across 28+ platforms.
+
+The kit provides a self-contained local execution environment. An operator exports the kit, points Claude Code's Working Directory at the kit root, and the `postiz-social-operator` worker handles the complete 10-step social media campaign workflow.
+
+---
+
+## Folder Structure
+
+```
+growthub-postiz-social-v1/
+  kit.json                              ← Kit manifest (schemaVersion: 2)
+  QUICKSTART.md                         ← Setup guide
+  .env.example                          ← Environment template
+  skills.md                             ← Master methodology doc (read at every session)
+  output-standards.md                   ← Output naming, structure, quality bar
+  runtime-assumptions.md                ← Frozen upstream assumptions
+  validation-checklist.md              ← Pre-session + kit validation checklists
+  bundles/
+    growthub-postiz-social-v1.json     ← Bundle manifest
+  workers/
+    postiz-social-operator/
+      CLAUDE.md                         ← Agent operating instructions (entrypoint)
+  brands/
+    _template/
+      brand-kit.md                      ← Blank client brand kit template
+    growthub/
+      brand-kit.md                      ← Growthub internal reference example
+    NEW-CLIENT.md                       ← Instructions for adding new clients
+  setup/
+    clone-fork.sh                       ← Clones Postiz, runs docker compose up
+    verify-env.mjs                      ← Verifies fork, API, workspace ID, API key
+    check-deps.sh                       ← Verifies Node, Docker, docker compose, git
+  output/
+    README.md                           ← Output directory structure and naming
+  templates/                            ← 7 production-quality campaign templates
+    social-campaign-brief.md
+    content-calendar.md
+    platform-publishing-plan.md
+    caption-copy-deck.md
+    scheduling-manifest.md
+    analytics-brief.md
+    client-proposal.md
+  examples/                             ← 4 filled samples for reference
+    social-campaign-sample.md
+    content-calendar-sample.md
+    analytics-brief-sample.md
+    client-proposal-sample.md
+  docs/                                 ← 4 technical reference documents
+    postiz-fork-integration.md
+    platform-coverage.md
+    ai-caption-layer.md
+    bullmq-queue-layer.md
+  growthub-meta/
+    README.md                           ← This file
+    kit-standard.md                     ← Kit rules and required-files contract
+```
+
+---
+
+## Activation
+
+This kit is activated in `export` mode:
+
+1. CLI exports the kit to a local folder
+2. User points Claude Code's Working Directory at the exported folder root
+3. `workers/postiz-social-operator/CLAUDE.md` is the agent entrypoint
+
+No server-side activation is required. The kit is fully self-contained.
+
+---
+
+## Upstream Fork
+
+| Field | Value |
+|---|---|
+| Fork Repo | https://github.com/gitroomhq/postiz-app |
+| License | MIT |
+| Default Clone Path | `~/postiz-app` |
+| Env Var Override | `POSTIZ_FORK_PATH` |
+| Services | Docker Compose: Postiz app (port 3000), Redis (6379), PostgreSQL (5432) |
+
+---
+
+## Supported Output Categories
+
+| Category | Templates | Examples |
+|---|---|---|
+| Social Campaign Briefs | `templates/social-campaign-brief.md` | `examples/social-campaign-sample.md` |
+| Content Calendars | `templates/content-calendar.md` | `examples/content-calendar-sample.md` |
+| Platform Publishing Plans | `templates/platform-publishing-plan.md` | — |
+| Caption Copy Decks | `templates/caption-copy-deck.md` | — |
+| Scheduling Manifests | `templates/scheduling-manifest.md` | — |
+| Analytics Briefs | `templates/analytics-brief.md` | `examples/analytics-brief-sample.md` |
+| Client Proposals | `templates/client-proposal.md` | `examples/client-proposal-sample.md` |
+
+---
+
+## Related Kits
+
+| Kit | Family | Purpose |
+|---|---|---|
+| `creative-strategist-v1` | workflow | Campaign strategy and creative briefs |
+| `growthub-email-marketing-v1` | operator | Email marketing campaigns |
+| `growthub-open-higgsfield-studio-v1` | studio | AI video generation via Open Higgsfield |
+| `growthub-geo-seo-v1` | studio | GEO + SEO auditing |

package/assets/worker-kits/growthub-postiz-social-v1/growthub-meta/kit-standard.md

@@ -0,0 +1,113 @@
+# Kit Standard — growthub-postiz-social-v1
+
+**These rules govern the kit's structure, agent behavior, and output contract. All operators and maintainers must follow them.**
+
+---
+
+## Required Files Contract
+
+The following files must be present in every valid kit installation. Any missing file constitutes a broken kit.
+
+| File | Purpose | Can Be Empty? |
+|---|---|---|
+| `kit.json` | Kit manifest | No — must be valid JSON with schemaVersion: 2 |
+| `QUICKSTART.md` | User-facing setup guide | No |
+| `.env.example` | Environment template | No |
+| `skills.md` | Master methodology doc | No — must contain all 10 steps |
+| `output-standards.md` | Output rules | No |
+| `runtime-assumptions.md` | Upstream assumptions | No |
+| `validation-checklist.md` | Pre-session checklist | No |
+| `workers/postiz-social-operator/CLAUDE.md` | Agent entrypoint | No |
+| `brands/_template/brand-kit.md` | Blank brand kit template | No |
+| `brands/growthub/brand-kit.md` | Example brand kit | No |
+| `brands/NEW-CLIENT.md` | New client instructions | No |
+| `setup/clone-fork.sh` | Fork installation script | No |
+| `setup/verify-env.mjs` | Environment verification | No |
+| `setup/check-deps.sh` | Dependency check | No |
+| `output/README.md` | Output directory guide | No |
+| All 7 template files | Campaign output templates | No — each must have all sections |
+| All 4 example files | Reference samples | No — must contain realistic filled data |
+| All 4 doc files | Technical reference | No |
+| `bundles/growthub-postiz-social-v1.json` | Bundle manifest | No |
+| `growthub-meta/README.md` | Kit metadata | No |
+| `growthub-meta/kit-standard.md` | This file | No |
+
+---
+
+## Bundle Contract
+
+| Requirement | Rule |
+|---|---|
+| Bundle ID | Must match kit ID: `growthub-postiz-social-v1` |
+| Kit ID in bundle | Must be `growthub-postiz-social-v1` |
+| Worker ID in bundle | Must be `postiz-social-operator` |
+| Schema version | Must be `2` |
+| `requiredFrozenAssets` | Must list all files in `kit.json` `frozenAssetPaths` |
+| Export folder name | `growthub-agent-worker-kit-postiz-social-v1` |
+| Export zip name | `growthub-agent-worker-kit-postiz-social-v1.zip` |
+
+---
+
+## Agent Rules
+
+### Workflow Order
+
+The operator must follow the 10-step workflow in `workers/postiz-social-operator/CLAUDE.md` strictly. Steps must not be skipped or reordered. The environment gate (Step 0) must run before anything else.
+
+### Platform IDs
+
+The operator must only use platform IDs from `docs/platform-coverage.md`. Invented platform slugs are not acceptable. If the user requests a platform not in the coverage doc, the operator must note it as unsupported in the current Postiz instance and suggest the nearest supported alternative.
+
+### Caption Variants
+
+Every post in the Caption Copy Deck must have exactly 3 variants (A, B, C). The variants must be meaningfully different in opening hook and structure — not minor word substitutions. Character limits must be checked and documented for every variant.
+
+### Scheduling Manifest
+
+When a scheduling manifest is produced:
+- `dryRun` must be `true` in agent-only mode
+- All `scheduledAt` values must be ISO 8601 with explicit timezone
+- All `postId` values must follow the naming convention
+- No manifest may reference a platform not confirmed to be connected in the Postiz instance
+
+### No Secrets in Outputs
+
+The operator must never include `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET`, OAuth tokens, or any other secret value in any output file. `.env.example` uses placeholder comments only.
+
+### Template-Bound Outputs
+
+All output artifacts must use the templates in `templates/`. The operator must not invent new template schemas or change the required section structure.
+
+---
+
+## Runtime Rules
+
+### Three Execution Modes Are First-Class
+
+`local-fork`, `agent-only`, and `hybrid` are all valid execution modes. The kit must never require local-fork mode for a session to produce valid campaign outputs. Agent-only mode is always a valid fallback for campaign planning, caption drafting, and dry-run scheduling manifests.
+
+### Postiz Is the Reference Substrate
+
+The platform integrations, BullMQ queue configuration, and API contract in the Postiz fork are the source of truth for scheduling behavior. The kit documents and wraps that behavior — it does not redefine it. When the upstream Postiz API changes, `runtime-assumptions.md` must be updated.
+
+### Markdown Is the Primary Output Format
+
+All campaign artifacts are Markdown files. The scheduling manifest is a JSON file. These are the canonical records — no other formats are produced by this kit unless explicitly requested.
+
+---
+
+## Versioning Rules
+
+| Scenario | Action |
+|---|---|
+| Bug fix in a template or doc file | Patch version bump: `1.0.0` → `1.0.1` |
+| New template or platform added | Minor version bump: `1.0.0` → `1.1.0` |
+| Workflow restructured or output schema changed | Major version bump: `1.0.0` → `2.0.0` |
+| Upstream Postiz adds new platform integration | Minor bump + update `runtime-assumptions.md` and `docs/platform-coverage.md` |
+| Postiz changes API contract | Major bump if breaking + update `runtime-assumptions.md` and `docs/bullmq-queue-layer.md` |
+
+Version bumps must update:
+- `kit.json` → `kit.version`
+- `bundles/growthub-postiz-social-v1.json` → `bundle.version`
+- `growthub-meta/README.md` → Version field
+- `runtime-assumptions.md` → Frozen date and changelog note

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

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 2,
+  "kit": {
+    "id": "growthub-postiz-social-v1",
+    "version": "1.0.0",
+    "name": "Growthub Agent Worker Kit — Postiz Social Media Studio",
+    "description": "Self-contained local execution environment for Postiz, the open-source agentic social media scheduler. Produces implementation-ready social media campaigns, content calendars, multi-platform publishing plans, AI-assisted captions, and analytics briefings across 28+ platforms including Instagram, LinkedIn, TikTok, X/Twitter, YouTube, Pinterest, Reddit, Bluesky, and more.",
+    "type": "worker",
+    "visibility": "public-open-source",
+    "sourceRepo": "growthub-local",
+    "family": "studio"
+  },
+  "entrypoint": {
+    "workerId": "postiz-social-operator",
+    "path": "workers/postiz-social-operator/CLAUDE.md"
+  },
+  "workerIds": [
+    "postiz-social-operator"
+  ],
+  "agentContractPath": "workers/postiz-social-operator/CLAUDE.md",
+  "brandTemplatePath": "brands/_template/brand-kit.md",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "frozenAssetPaths": [
+    "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"
+  ],
+  "setupPaths": {
+    "quickstart": "QUICKSTART.md",
+    "envExample": ".env.example",
+    "setupDir": "setup/",
+    "outputDir": "output/"
+  },
+  "outputStandard": {
+    "type": "working-directory",
+    "description": "Exported folder is intended to be pointed at directly by the agent Working Directory. All outputs are Markdown files written to output/<client-slug>/<project-slug>/.",
+    "requiredPaths": [
+      "QUICKSTART.md",
+      ".env.example",
+      "kit.json",
+      "bundles/growthub-postiz-social-v1.json",
+      "skills.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",
+      "docs",
+      "growthub-meta"
+    ]
+  },
+  "bundles": [
+    {
+      "id": "growthub-postiz-social-v1",
+      "version": "1.0.0",
+      "path": "bundles/growthub-postiz-social-v1.json"
+    }
+  ],
+  "executionMode": "export",
+  "activationModes": [
+    "export"
+  ],
+  "compatibility": {
+    "cliMinVersion": "0.3.53"
+  },
+  "provenance": {
+    "sourceRepo": "growthub-local",
+    "frozenAt": "2026-04-15T00:00:00.000Z"
+  }
+}

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

@@ -0,0 +1,56 @@
+# Output Directory
+
+This directory is where all campaign deliverables are written.
+
+---
+
+## Structure
+
+```
+output/
+  <client-slug>/
+    <project-slug>/
+      SocialCampaignBrief_v<N>_<YYYYMMDD>.md
+      ContentCalendar_v<N>_<YYYYMMDD>.md
+      PlatformPublishingPlan_v<N>_<YYYYMMDD>.md
+      CaptionCopyDeck_v<N>_<YYYYMMDD>.md
+      SchedulingManifest_v<N>_<YYYYMMDD>.md    (if scheduling requested)
+      AnalyticsBrief_v<N>_<YYYYMMDD>.md        (if analytics data provided)
+      ClientProposal_v<N>_<YYYYMMDD>.md        (if requested)
+      scheduling-manifest.json                  (machine-readable, for Postiz API)
+```
+
+---
+
+## Naming Convention
+
+```
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+- **ClientSlug:** TitleCase, no spaces (`UrbanCycle`, not `Urban Cycle`)
+- **OutputType:** CamelCase (`SocialCampaignBrief`, `ContentCalendar`, etc.)
+- **Version:** `v1`, `v2`, etc.
+- **Date:** `YYYYMMDD` format
+
+**Example:** `UrbanCycle_ContentCalendar_v1_20260415.md`
+
+---
+
+## Adding a New Project
+
+When starting a campaign for a new client or a new project for an existing client:
+
+```bash
+mkdir -p output/<client-slug>/<project-slug>
+```
+
+The operator will write all deliverables to this directory and log the project in the brand kit DELIVERABLES LOG.
+
+---
+
+## Git and Version Control
+
+The `output/` directory is excluded from kit exports. Do not commit client deliverables to the kit repository. Keep outputs in your local working directory or a separate client delivery folder.
+
+If you are version-controlling client outputs separately, use the project slug as the branch or folder name.