opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/small-business/skills/small-business-canva-creator/reference/examples/boutique-brief-campaign.md

@@ -0,0 +1,181 @@
+# Worked Example: Retail Boutique Brief → Campaign
+
+**Business:** Bloom & Thread — women's clothing boutique, Charleston SC  
+**Canva tier:** Teams (no Enterprise)  
+**HubSpot tier:** Marketing Hub Professional  
+**Brief source:** content-strategy skill output (approved by owner)
+
+---
+
+## Input: Approved brief (summary)
+
+```
+Push hard: Linen summer dresses (top seller, trending +22% MoM)
+Hold steady: Accessories
+Seasonal opportunity: Back-to-school transition (Aug 15 pivot)
+Offer: Buy 2 dresses, get 1 accessory free (runs June 1–July 31)
+Channels: Instagram feed, Instagram story, Facebook feed
+Cadence: 3× per week, Mon/Wed/Fri, 10 AM ET
+Voice: Warm, conversational, light humor. No corporate copy.
+```
+
+---
+
+## Stage 1: Posting calendar (presented for approval)
+
+| Date | Channel | Theme | Asset type | Caption angle |
+|------|---------|-------|------------|---------------|
+| Jun 2 | Instagram feed | Linen dresses launch | Square post | Product intro — "finally, a dress you can wear to both places" |
+| Jun 4 | Facebook feed | Linen dresses | Landscape post | Social proof — "our most-reached-for item this spring" |
+| Jun 6 | Instagram story | Buy 2 get 1 offer | Story (16:9) | Offer urgency — swipe up |
+| Jun 9 | Instagram feed | Linen styling tip | Square post | Education — "3 ways to style the linen midi" |
+| Jun 11 | Facebook feed | Behind the scenes | Landscape post | Brand story — how they're made |
+| Jun 13 | Instagram story | Weekend outfit inspo | Story (16:9) | Lifestyle — "your Saturday, sorted" |
+| … | … | … | … | … |
+
+*Owner approved — "move Jun 11 to Jun 12, I'm posting about the sale that day. Otherwise great."*  
+*(Calendar updated; proceeding to Stage 2.)*
+
+---
+
+## Stage 2: Canva asset generation (Pro/Teams path)
+
+**Template selection exchange:**
+
+```
+Claude: I found 3 square-post templates in your Canva library:
+  1. Boutique Square - Cream  (last edited Apr 2026)
+  2. Summer Promo - Sand      (last edited Mar 2026)
+  3. Product Feature Bold     (last edited Feb 2026)
+  Which should I use for the feed posts?
+
+Owner: The cream one, #1.
+
+Claude: Got it. I'll use "Boutique Square - Cream" for all feed posts.
+        Creating design shells now — I'll give you the links to fill in
+        the product photos and text in Canva, then come back so I can export.
+```
+
+*[Designs created; owner fills in Canva; returns design IDs]*
+
+**Export output:**
+```
+Exporting previews...
+✓ Jun 2 feed post    → https://canva.com/export/abc123.png
+✓ Jun 4 Facebook     → https://canva.com/export/def456.png
+✓ Jun 6 story        → https://canva.com/export/ghi789.png
+[…]
+```
+
+*Owner: "These look great. Go ahead."*
+
+---
+
+## Stage 3: Caption drafts
+
+**Jun 2 — Instagram feed (linen dresses launch)**
+```
+Finally, a dress you can wear to the farmer's market *and* to dinner. 🌿
+
+Our linen midi just landed and it's already our most-requested piece this
+summer. Breathable, effortless, and yes — it has pockets.
+
+Grab yours before the sizes go → link in bio.
+
+#LinenDress #CharlestonStyle #SummerFashion #BloomAndThread
+```
+
+**Jun 4 — Facebook feed (social proof)**
+```
+"I've worn it four times this week and I'm not even sorry."
+
+That's a real review from a real customer about our linen midi. Between
+you and us, we're not surprised. Shop the collection at the link below.
+```
+
+**Jun 6 — Instagram story (offer)**
+```
+👗 Buy 2 dresses → get 1 accessory FREE
+
+Offer runs June 1–July 31. Don't sleep on it.
+
+Swipe up to shop →
+```
+
+*Owner approved with one change: "Jun 4 caption — add the price at the end. 'USD 88, link below.'"*  
+*Caption updated.*
+
+---
+
+## Stage 4: HubSpot staging
+
+**Campaign created:**
+```
+Campaign: "Bloom & Thread — Summer Linen 2026"
+Start: Jun 2, 2026 | End: Jul 31, 2026
+Campaign ID: 8a72c1f4...
+```
+
+**Scheduled queue (first 3):**
+
+| Scheduled | Channel | Caption preview | Status |
+|-----------|---------|-----------------|--------|
+| Jun 2, 10:00 AM ET | Instagram | "Finally, a dress you can wear…" | SCHEDULED |
+| Jun 4, 10:00 AM ET | Facebook | '"I've worn it four times…"' | SCHEDULED |
+| Jun 6, 10:00 AM ET | Instagram Story | "Buy 2 dresses → get 1 accessory FREE…" | SCHEDULED |
+
+**Final message to owner:**
+```
+Your campaign is staged in HubSpot:
+https://app.hubspot.com/content/12345/social/campaigns/8a72c1f4
+
+Posts will publish automatically on schedule. You can cancel or edit
+any post in HubSpot before it goes out. Anything to change before we're done?
+```
+
+---
+
+## Email content example (text-only — no Canva)
+
+Email rows skip Canva entirely. Claude writes the email subject, preheader,
+and body as plain prose in Stage 3, and the owner copies the content into
+their email tool when they're ready to send.
+
+**Calendar row:**
+
+| Date | Channel | Theme | Asset type | Angle |
+|------|---------|-------|------------|-------|
+| Jun 5 | Email | Summer linen launch | Email (text) | Hero customer benefit + offer |
+
+**Stage 3 output (inline, no Canva involved):**
+
+```
+Subject: Linen that actually breathes
+Preheader: New summer styles in — plus a small gift if you grab two.
+
+The first batch of linen midis just hit the floor. They're the kind of
+dress you can wear to brunch, to a wedding, or to the school pickup line
+without feeling like you've made a wardrobe decision.
+
+A few things worth knowing:
+  • Sizes XS–XL, four colorways
+  • Pockets (real ones)
+  • Buy 2 dresses through July 31 and we'll throw in a free accessory
+
+Stop by 412 King Street this weekend, or shop online below.
+
+Shop the linen collection →
+
+— Maya
+Bloom & Thread
+```
+
+**Stage 4 handoff:**
+
+```
+Your social posts are scheduled in HubSpot: [link]
+
+Email content for June 5 is drafted above — copy it into your email tool
+when you're ready to send. We don't stage emails directly; that lets you
+preview the formatting in your sending platform first.
+```

package/content/small-business/skills/small-business-canva-creator/reference/gotchas.md

@@ -0,0 +1,380 @@
+# Gotchas
+
+Common failure modes for the canva-creator skill.
+
+---
+
+## Gotcha: Generating ANY Canva design for an email row
+
+**Why it matters:** Canva is out of scope for the email path entirely.
+Canva email-template autofill produces placeholder graphics (stock
+landscapes, blank rectangles) in service-grid tiles, and variation
+thumbnails fail to render in chat. Emails are text-only
+from this skill, period. Generating a Canva email design — even one —
+breaks that rule.
+
+### ✗ Bad
+
+```
+Calendar has 6 social rows + 2 email rows.
+→ Stage 2 generates 6 social designs + 2 email designs.
+→ Email designs ship with placeholder service tiles.
+```
+
+Or any variation: "I'll generate the email template just to give you a
+visual reference," "I found an email template that might work, want to
+preview it?", "Here's a Canva design for the Jun 5 email…" — all
+forbidden.
+
+### ✓ Good
+
+```
+Stage 1: Calendar built with Path column.
+  - 6 rows tagged Canva (social)
+  - 2 rows tagged Text-only (no Canva)
+Stage 2: Generates exactly 6 Canva designs. Email rows are not passed
+         to any Canva endpoint.
+Stage 3: Drafts 6 social captions + 2 full emails (subject + preheader +
+         body) as plain text.
+Stage 4: Stages 6 social posts in HubSpot. Surfaces 2 emails inline for
+         owner to copy into their email tool.
+```
+
+If the owner explicitly asks for a Canva email design ("can you make me
+a Canva version of the Jun 5 email?"), redirect: "This skill keeps emails
+as text-only because the Canva email path produces placeholder graphics.
+If you want a Canva-designed email, build it directly in Canva and I can
+help you write the copy here."
+
+---
+
+## Gotcha: Generating without a budget plan
+
+**Why it matters:** Canva caps API usage at 100 requests/minute per token,
+and each design costs ~5 calls (autofill + export + polling). A 10-row
+campaign with 4 candidates per row generates 40 designs and ~200 API
+calls — and the math gets worse with parallelism. Without a pre-flight
+budget, the owner hits quota mid-campaign with no clear recovery path
+and four already-generated posts sitting unused.
+
+### ✗ Bad
+
+```
+Calendar approved → immediately fire 4 candidates × 8 rows in parallel
+→ ~160 API calls in 90 seconds → RATE_LIMIT_EXCEEDED on post 5 → loop
+on retry → owner blocked.
+```
+
+### ✓ Good
+
+```
+Pre-flight: "8 Canva rows × 3 candidates = 24 designs, ~120 API calls.
+Proceed at default 3 candidates per row?"
+
+Stage 3: row 1's 3 candidates fire in parallel → 30s pause → row 2 →
+30s pause → row 3 → … finishes at ~12 designs/minute, well under the
+quota.
+
+If quota does hit anyway: stop, surface progress, ask the owner
+whether to drop to single candidates, pause an hour, or move to
+captions with what's done.
+```
+
+---
+
+## Gotcha: Skipping Checkpoint 1 (calendar approval) before generating assets
+
+**Why it matters:** Generating 10+ Canva designs takes API calls, time, and
+user attention. If the calendar has the wrong dates, wrong channels, or the
+owner changes their mind about a theme, all that work is discarded. The
+calendar checkpoint is the cheapest place to catch misalignment.
+
+### ✗ Bad
+
+Receive the brief → immediately start calling `POST /autofills` for all 12
+posts → present designs before the owner has agreed on the schedule.
+
+Owner: "Oh wait, I didn't want any posts the week of the 15th, I'm traveling."
+
+### ✓ Good
+
+Present the calendar table first. Wait for explicit "looks good" before opening
+a single Canva API call.
+
+---
+
+## Gotcha: Template has more image slots than the brief provides photos for
+
+**Why it matters:** Multi-image social templates (Instagram carousels,
+product grids) can have 3+ image slots. When the brief gives you 1 photo
+and the template demands 3, the unfilled slots silently render Canva's
+stock landscape graphic — generic clouds and green hills where product
+photos should be. The design looks "complete" until the owner opens it.
+
+(Note: email rows skip Canva entirely in this skill — see SKILL.md Stage 3.
+This gotcha applies only to social templates with multiple image slots.)
+
+### ✗ Bad
+
+Build manifest with one row per design ("Carousel — needs Hero_Image").
+Upload the one photo. Generate. Carousel ships with slide 1 populated
+and slides 2-3 both showing identical generic landscapes.
+
+### ✓ Good
+
+Build manifest slot-by-slot. Surface the gap explicitly:
+
+```
+The "3-product carousel" template has 3 image slots. The brief gave me
+1 photo. How should I fill the other 2?
+
+1. Reuse the same photo across all 3 slots
+2. I'll send you 2 more photos
+3. Pick a single-image template
+```
+
+Wait for the owner's choice before generating. Don't let placeholder
+graphics ship.
+
+---
+
+## Gotcha: Trusting `status: success` without exporting and visually verifying
+
+**Why it matters:** A successful autofill job means Canva accepted the
+request and produced a design — not that the design contains the right
+images. If an `asset_id` was empty, stale, or wrong-typed, the job still
+returns `status: success` and the design renders with default placeholder
+graphics. The only way to know is to look at the rendered output.
+
+### ✗ Bad
+
+```
+Job status: success ✓
+result.design.id: present ✓
+→ Present to owner
+```
+
+Result: owner opens the carousel and sees stock landscape graphics in 3 of
+4 designs.
+
+### ✓ Good
+
+After the job succeeds, export each design to a permanent PNG via
+`POST /exports` (or `export-design` MCP). Look at each PNG and confirm it
+contains real assets — not Canva's default landscape, not gray rectangles,
+not lorem-ipsum text. Only present to the owner after visual verification
+passes.
+
+---
+
+## Gotcha: One design in a batch fails to render
+
+**Why it matters:** When 1 of 4 designs in a batch fails (job error, expired
+preview URL, placeholder rendered) and you present the partial carousel
+anyway, the owner sees three real designs and one "Show Image" gray
+rectangle. They lose trust in the rest of the carousel even though it's
+fine.
+
+### ✗ Bad
+
+```
+Week 1 designs are ready:
+[Option A — real preview]
+[Option B — real preview]
+[Option C — real preview]
+[Option D — Show Image placeholder]
+Which one should I use?
+```
+
+### ✓ Good
+
+When you detect the broken design at Step 6 verification, regenerate just
+that one design with the correct asset_id. Re-export, re-verify. Only
+present once all four designs in the batch have permanent, verified
+previews. If the second attempt also fails, ask the owner whether to skip,
+swap template, or try a different photo.
+
+---
+
+## Gotcha: Generating assets without confirming all autofill fields have values
+
+**Why it matters:** Canva autofill silently renders empty placeholders when a
+field value is missing or the referenced `asset_id` doesn't exist. The result
+is a professional-looking template with blank white rectangles where the
+product photo and headline should be.
+
+### ✗ Bad
+
+Build calendar → immediately fire all `POST /autofills` in parallel → half
+the designs come back with empty image placeholders because product photos
+weren't uploaded first.
+
+### ✓ Good
+
+Build calendar → inventory every autofill field slot-by-slot → upload missing
+product images → confirm all field values with owner → then generate designs
+in parallel, with every field pre-populated.
+
+---
+
+## Gotcha: Passing invalid values to image autofill fields
+
+**Why it matters:** When an autofill image field receives an empty string, a
+file path, a URL, or a stale/invalid `asset_id`, Canva does not error — it
+silently renders the template's default placeholder graphic (e.g., a generic
+landscape with clouds and hills). The design looks "finished" but the hero
+image is stock art, not the owner's product photo.
+
+### ✗ Bad
+
+Upload product photo → don't wait for the upload job to complete → pass the
+`job_id` (not the `asset.id`) into the autofill data → design renders with
+a placeholder landscape instead of the product photo.
+
+### ✓ Good
+
+Upload product photo via `POST /v1/asset-uploads` → poll
+`GET /v1/asset-uploads/{job_id}` until `status == "success"` → extract
+`asset.id` from the response → pass that exact ID into the autofill image
+field. Verify every image field has a confirmed `asset.id` before calling
+`POST /autofills`.
+
+---
+
+## Gotcha: Embedding Canva CDN thumbnail URLs in markdown
+
+**Why it matters:** Canva's autofill response returns short-lived,
+authenticated CDN URLs from `design.canva.ai`. These expire within minutes.
+If Claude embeds them as markdown images (`![](design.canva.ai/...)`), they
+render as broken "Show Image" placeholders by the time the message is shown.
+
+### ✗ Bad
+
+Generate 8 designs → manually embed each CDN thumbnail URL in the response
+as `![Hero 1](https://design.canva.ai/xxx)` → all images show as broken
+gray placeholders because the URLs expired before render.
+
+### ✓ Good
+
+Either let the native Cowork carousel render the tool result automatically,
+or export each design via `POST /exports` and embed the **permanent** export
+URL. As a final fallback, link to the design's permanent edit URL
+(`https://www.canva.com/d/{design_id}`). Never re-embed `design.canva.ai`
+URLs.
+
+---
+
+## Gotcha: Listing designs one-by-one as individual image blocks
+
+**Why it matters:** When Claude lists each design as a separate block
+("Hero 1 / [image] / Hero 2 / [image]"), the images render as broken
+gray "Show Image" placeholders. Presenting all designs together in a
+single grouped batch triggers Cowork's side-by-side carousel, which
+renders correctly.
+
+### ✗ Bad
+
+```
+Hero 1 — Multi-property portfolio
+[Show Image]
+View in Canva: https://canva.com/d/xxx
+
+Hero 2 — Coastal market case study
+[Show Image]
+View in Canva: https://canva.com/d/yyy
+```
+
+### ✓ Good
+
+Present all designs in one grouped response so they render as a
+side-by-side carousel. Below the carousel, add a single prompt:
+
+```
+Here are 4 hero designs for Week 1. Scroll through the carousel
+above and let me know which one to keep.
+```
+
+---
+
+## Gotcha: Generating designs sequentially instead of in parallel
+
+**Why it matters:** Generating designs one at a time means the owner waits
+through N round trips instead of one. Fire all generation requests within a
+batch at once and present selection after all jobs complete.
+
+### ✗ Bad
+
+Generate design 1 → wait → show it → generate design 2 → wait → show it →
+… × 8 designs. Owner watches a slow drip for 10 minutes.
+
+### ✓ Good
+
+Fire all designs in the current batch at once → poll all jobs concurrently →
+once all complete, export each → verify visually → then present.
+
+---
+
+## Gotcha: Auto-selecting a brand template for Pro/Teams users
+
+**Why it matters:** Pro/Teams users have no brand-template API access. If
+Claude guesses a template by name and generates with the wrong one, the owner
+gets designs in the wrong colors/fonts and has to redo the work in Canva
+manually.
+
+### ✗ Bad
+
+```
+Found template "Square Post - Blue". Using this for all feed posts.
+```
+…followed by 8 designs in blue when the brand is green.
+
+### ✓ Good
+
+```
+I found 3 templates in your Canva library that could work for feed posts:
+1. Square Post - Blue  (last edited March 2026)
+2. Summer Promo - Green  (last edited April 2026)
+3. Product Feature Card  (last edited Jan 2026)
+
+Which one should I use?
+```
+
+---
+
+## Gotcha: Caption voice drift across a long calendar
+
+**Why it matters:** When drafting 12–20 captions in one pass, the tone tends
+to drift — early captions follow the brief's voice markers, later ones slip
+into generic marketing copy. Owners notice immediately.
+
+### ✗ Bad
+
+Post 1: "Our handmade candles are the perfect summer gift 🌿" (matches brief: "warm, conversational")  
+Post 10: "Elevate your ambiance with our artisanal fragrance collection." (corporate drift)
+
+### ✓ Good
+
+Before drafting, anchor on 2–3 voice markers from the brief (e.g., "casual,
+friendly, uses light humor"). Re-read the first draft caption before writing
+each new one. If the owner flags a voice mismatch on any caption, re-read that
+caption and flag it as the recalibration point for the remaining drafts.
+
+---
+
+## Gotcha: Staging HubSpot posts without verifying `scheduledAt` is in the future
+
+**Why it matters:** HubSpot rejects posts with `scheduledAt` in the past with
+a validation error. If the calendar was built on an earlier date and the
+owner is only now staging, some dates may have passed.
+
+### ✗ Bad
+
+Build calendar on April 1st for June posts → owner approves May 15th → try to
+stage without checking → post for "April 30th 10:00 AM" returns 400.
+
+### ✓ Good
+
+Before calling `POST /social/posts`, compare each `scheduledAt` against the
+current UTC time. If any post date has passed, surface it: "The post scheduled
+for April 30th has already passed. Should I skip it, or reschedule it to next
+week?"

package/content/small-business/skills/small-business-canva-creator/reference/hubspot-staging.md

@@ -0,0 +1,137 @@
+# HubSpot Campaign Staging Reference
+
+Requires: **HubSpot Marketing Hub Professional** (or higher).  
+Base URL: `https://api.hubapi.com`  
+Auth: Bearer token (OAuth 2.0 or private app token).
+
+---
+
+## Table of contents
+
+1. [Tier check](#tier-check)
+2. [Create a campaign](#create-a-campaign)
+3. [Create a social post](#create-a-social-post)
+4. [Verify the scheduled queue](#verify-the-scheduled-queue)
+5. [CSV fallback (non-Professional users)](#csv-fallback-non-professional-users)
+6. [Field reference](#field-reference)
+
+---
+
+## Tier check
+
+If you're unsure whether the user has Marketing Hub Professional:
+
+```
+GET /crm/v3/objects/companies?limit=1
+```
+
+Check the `subscriptionType` on the account. If the API returns a 403 on
+social endpoints, tell the user: "HubSpot campaign staging requires Marketing
+Hub Professional. Your current plan doesn't include it. I can export a
+scheduling CSV instead — would that work?"
+
+---
+
+## Create a campaign
+
+```
+POST /marketing/v3/campaigns
+{
+  "name": "Summer Sale 2026 — Social",
+  "startDate": "2026-06-01",
+  "endDate":   "2026-06-30",
+  "currencyCode": "<Currency from the Business context block, e.g. AUD>",
+  "utm": {
+    "source": "social",
+    "medium": "owned",
+    "campaign": "summer-sale-2026"
+  }
+}
+```
+
+Response: `{ "id": "<campaign_id>", ... }` — save this for social post association.
+
+---
+
+## Create a social post
+
+One call per calendar row. Stage as `SCHEDULED`, never `PUBLISHED`.
+
+```
+POST /marketing/v3/social/posts
+{
+  "campaignId": "<campaign_id>",
+  "channelId":  "<hubspot_channel_id>",
+  "content": {
+    "body": "<approved caption text>"
+  },
+  "scheduledAt": "2026-06-03T10:00:00Z",
+  "attachments": [
+    {
+      "url": "<canva_export_png_url>"
+    }
+  ],
+  "status": "SCHEDULED"
+}
+```
+
+**`channelId`** — the HubSpot Social account ID (not the platform name).
+Retrieve connected accounts:
+```
+GET /marketing/v3/social/channels
+```
+Match by `type` (`INSTAGRAM`, `FACEBOOK`, `TWITTER`, `LINKEDIN`) and use the `id` field.
+
+**`scheduledAt`** — must be in the future (relative to the time of the API
+call). Use noon local time for the owner's timezone unless they specify
+otherwise.
+
+---
+
+## Verify the scheduled queue
+
+After staging all posts:
+
+```
+GET /marketing/v3/social/posts?status=SCHEDULED&campaignId=<campaign_id>
+```
+
+Surface results in a table: date, channel, first 60 chars of caption, status.
+Provide the direct HubSpot campaign URL:
+`https://app.hubspot.com/content/{portalId}/social/campaigns/{campaign_id}`
+
+Tell the user: "Posts are scheduled and will publish automatically. You can
+cancel or edit any post in HubSpot before the send time."
+
+---
+
+## CSV fallback (non-Professional users)
+
+When HubSpot staging is not available, export a CSV the user can import into
+Buffer, Later, or their scheduler of choice.
+
+Column headers:
+```
+Date,Time,Channel,Caption,ImageURL,Status
+```
+
+Example row:
+```
+2026-06-03,10:00 AM CDT,Instagram,"Summer Sale: 30% off candles ☀️ ...",https://canva.com/export/...,Scheduled
+```
+
+Tell the user: "I've prepared a scheduling CSV since your HubSpot plan doesn't
+include social staging. You can import this into Buffer or Later. [file path]"
+
+---
+
+## Field reference
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `campaignId` | string | UUID from campaign creation |
+| `channelId` | string | From `GET /social/channels` |
+| `content.body` | string | Caption text; max 2,000 chars |
+| `scheduledAt` | ISO 8601 | Must be future time; include timezone offset |
+| `attachments[].url` | string | Public URL (Canva export URL works) |
+| `status` | enum | Always `"SCHEDULED"` — never `"PUBLISHED"` |