arkaos 4.26.0 → 4.28.0

package/departments/marketing/skills/social-strategy/references/carousel-frameworks.md

@@ -0,0 +1,141 @@
+# Carousel Frameworks
+
+Five slide-by-slide narrative architectures for carousels — Instagram carousels and LinkedIn document posts. Each framework is a different *reason to keep swiping*; picking the right one for the content matters more than polishing individual slides.
+
+A carousel is not a blog post chopped into squares. It's a swipe-through with two jobs per slide: deliver one idea, and make the next swipe irresistible. These frameworks encode structures that show up repeatedly in high-performing carousels; treat them as starting structures to adapt, not rigid formulas — and expect to validate against your own analytics.
+
+## Picking a Framework
+
+| Your content is... | Use | Why |
+|---|---|---|
+| A list of resources, tools, or tips | **A: Value-Stack** | Completeness is the promise; the count is the hook |
+| A personal result with a system behind it | **B: Problem-Proof** | Proof opens and closes the loop; the system is the meat |
+| Several named techniques on one theme | **C: Hack List** | Each hack re-earns the swipe independently |
+| A strong opinion about a common practice | **D: Rant Callout** | Conviction is the content; structure keeps it fair |
+| A product or workflow you can show | **E: Demo Walkthrough** | Seeing the steps is more persuasive than describing them |
+
+Two cross-framework rules before the specifics:
+
+- **Slide 1 is the thumbnail.** It competes in the feed alone, before anyone knows a carousel follows. Design and write it as a standalone scroll-stopper.
+- **One visual template per carousel.** Same layout, type scale, and palette on every interior slide. Variety between slides reads as clutter; consistency lets the *content* change while the frame stays still.
+
+---
+
+## Framework A: Value-Stack (4–14 slides)
+
+The "everything you need" carousel. Works because the cover makes a completeness claim — an exact count and an exact deliverable — and every swipe pays it down.
+
+| Slide | Job | Pattern |
+|---|---|---|
+| 1 — Cover | State the exact count + exact deliverable. Specificity proves scale upfront. | "[N] [resource type] for [role/outcome]" |
+| 2 to N−1 — Value delivery | One item or category per slide, 3–6 concrete sub-items each. Same visual template, zero filler slides. | "[Category/item] — [sub-items]" |
+| N — Close | Convert the swipe-through into an action. | "[Action] for [the payoff]" — comment a keyword, follow, link in bio |
+
+**Why the exact count matters:** "27 free tools" outperforms "the best free tools" because a number is a checkable promise — the reader can verify you delivered. Rounding up with padding breaks the trust the count created.
+
+*SaaS example:* "12 ChatGPT prompts for SaaS onboarding emails" → one prompt per slide with the use case → "Comment PROMPTS and I'll send the full doc."
+
+**Failure mode:** filler slides to hit a bigger number. Cut to the real count; a tight 8 beats a padded 14.
+
+---
+
+## Framework B: Problem-Proof (6–10 slides)
+
+The "I did X, here's the system" carousel. The hook is a *result stated as fact*, not advice — and the final slide shows the receipt, closing the loop slide 1 opened.
+
+| Slide | Job | Pattern |
+|---|---|---|
+| 1 — Hook | A specific personal claim with a number. A result, not a tip. | "[I/we did X]. [Specific result, with number]." |
+| 2 — Reframe the problem | Name what's *actually* going wrong so the reader recognizes themselves. | "The real problem — [named issue]" |
+| 3–4 — The mechanism | Show the real system: named tools, named steps. Concrete beats vague. | "The system — [named tools/steps]" |
+| 5 to N−1 — The detail | The literal prompt text, template, or step-by-step. This is the save-worthy part. | "[The literal prompt or process detail]" |
+| N — Proof | The actual output artifact. A screenshot, not a description. | "[Screenshot of output] — the receipt" |
+
+**The open loop is the engine:** slide 1 makes a claim, the last slide proves it, and everything between explains how. Readers swipe to see whether the receipt is real.
+
+*SaaS example:* "We cut churn 22% with one onboarding email." → the real problem (activation, not price) → the sequence structure → the literal email copy → the retention chart.
+
+**Failure mode:** vague mechanism slides ("optimize your workflow") — if the middle slides don't name tools and steps, the proof slide reads as luck, not system.
+
+---
+
+## Framework C: Hack List (6–10 slides)
+
+The "numbered techniques" carousel. A contrarian cover creates status anxiety — most people are doing this wrong — and each numbered hack independently re-earns the swipe.
+
+| Slide | Job | Pattern |
+|---|---|---|
+| 1 — Contrarian hook | A stat or claim implying most people fail at this. | "[Stat implying most people fail at X]" |
+| 2 — The problem | Why the common approach fails, ideally with an analogy. | "The problem — [why it fails]" |
+| 3 to N−1 — Numbered hacks | One named technique per slide. Bad-vs-good contrast makes each hack land instantly. | "Hack #[n] — [named technique]" |
+| N — Synthesis + close | A one-line thesis tying the hacks together, then a save/share/follow CTA. | "[Thesis tying hacks together]" + [CTA] |
+
+**Name every technique.** "The 3-second rule" is shareable and memorable; "keep it short" is neither. Named techniques travel — people repeat them and credit the source.
+
+*SaaS example:* "90% of trial emails never get opened." → why (they read like receipts, not messages) → Hack #1: The founder-from line, Hack #2: The one-question subject, ... → "Trial emails are conversations, not confirmations. Save this for your next sequence."
+
+**Failure mode:** hacks that are restatements of each other. Each slide must survive alone — if two hacks collapse into one idea, merge them and go shorter.
+
+---
+
+## Framework D: Rant Callout (4–8 slides)
+
+The "someone had to say it" carousel. Personality-led and polarizing by design — the structure exists to keep the heat *fair* so it reads as conviction, not bitterness.
+
+| Slide | Job | Pattern |
+|---|---|---|
+| 1 — Provocative claim | An unpopular opinion or direct accusation about a common practice. | "Unpopular opinion — [common practice]" |
+| 2 to N−2 — Escalate the argument | Sensory, specific detail. Show the offense; don't gesture at it abstractly. Each slide raises the stakes. | "[Escalating, specific complaint]" |
+| N−1 — Fairness pivot | "Don't get me wrong…" — clarify what you're *not* attacking. Anti-laziness, not anti-tool; anti-practice, not anti-person. | "The problem isn't [X], it's [Y]" |
+| N — Close | Firm, personality-forward sign-off. Signed rants read as owned opinions; anonymous ones read as potshots. | "[Firm sign-off] — signed [name/persona]" |
+
+**The fairness pivot is what makes it work.** Without it you're yelling; with it you're drawing a precise line, and precise lines get quoted. It also pre-empts the top hostile comment.
+
+*SaaS example:* "Your AI-generated LinkedIn posts are costing you customers." → the specifics (same em-dash cadence, same 'game-changer' vocabulary, zero lived detail) → "Don't get me wrong — I use AI daily. The problem isn't the tool, it's publishing the first draft." → "Write like you talk. — [Name]"
+
+**Failure modes:** skipping the pivot (reads unhinged, invites pile-ons), or ranting about something your own product/content visibly does (the comments will find it).
+
+---
+
+## Framework E: Demo Walkthrough (5–11 slides)
+
+The "watch it work" carousel for product or workflow content. Show the finished result first, then the steps — the outcome earns attention for the process.
+
+| Slide | Job | Pattern |
+|---|---|---|
+| 1 — Product + outcome | Brand/product plus the finished result. Lead with what they get. | "[Product] + [outcome], finished result" |
+| 2 — Problem it solves | The specific frustration this replaces. | "[The specific pain this replaces]" |
+| 3 — Process overview | The numbered step list, shown *before* the detail. Seeing the whole path lowers mid-swipe drop-off — readers commit when they know how long the road is. | "[N] steps to [outcome] in [timeframe]" |
+| 4 to N−1 — Step-by-step | One real UI screenshot per step with a short caption. Real screenshots; mockups read as vaporware. | "Step [n] — [screenshot] — [caption]" |
+| N — Result + positioning | The full-size output plus one brand-philosophy line. | "[Final output] + [positioning line]" |
+
+**Overview-before-detail is the key move** (same reason recipe sites list ingredients before instructions): a reader who's seen "4 steps, 10 minutes" on slide 3 will finish; a reader dropped straight into step 1 with no map bails at step 2.
+
+*SaaS example:* "From CSV to live dashboard in 4 steps" → the pain (weekly manual reporting) → the 4-step overview → one screenshot per step → the finished dashboard + "Built for marketers, not analysts."
+
+**Failure mode:** screenshots with too much UI. Crop to the action, zoom the relevant control, annotate with one arrow — each screenshot should make sense at thumbnail size.
+
+---
+
+## Platform Notes
+
+**Instagram:** 1080×1350 (4:5) slides; up to 20 slides but the frameworks' ranges above reflect where completion rates hold. The caption carries the searchable text — restate the hook and add context, don't just repeat slide 1. First slide doubles as the grid thumbnail.
+
+**LinkedIn (document posts):** Upload as PDF. Square or 4:5. LinkedIn shows a "N pages" badge — Value-Stack's exact-count cover plays especially well here. B2B tolerates denser text per slide than Instagram, but the one-idea-per-slide rule still holds. The post text above the document is a second hook — write it as its own post, not a throwaway "see attached."
+
+**TikTok photo mode:** Same frameworks work; pacing skews faster — trim each framework toward its minimum slide count.
+
+## Production Checklist
+
+- [ ] Slide 1 works as a standalone feed post (test: would it stop the scroll with no carousel behind it?)
+- [ ] One idea per slide — if a slide needs two sentences of setup, split it
+- [ ] Same visual template on every interior slide
+- [ ] Any count promised on the cover is exactly delivered (no filler, no rounding)
+- [ ] Claims and numbers are real and yours — no invented stats or borrowed screenshots
+- [ ] Text is legible at thumbnail size (minimum ~28pt at 1080px wide)
+- [ ] Final slide has one CTA, not three
+- [ ] Caption/post text written as its own hook, not a repeat of slide 1
+
+## Measuring What Worked
+
+Judge carousels on **saves and completion**, not likes — saves signal reference value (the algorithmic win for carousels), and where per-slide analytics exist (Instagram professional insights, LinkedIn document analytics, or third-party tools), drop-off position tells you which slide broke the swipe chain. When a carousel underperforms, the fix is usually slide 1 (didn't stop the scroll) or the framework choice (list content forced into a rant structure), not the middle slides. Track per-framework performance and double down on the two that fit your audience — see [reverse-engineering.md](reverse-engineering.md) for the analysis workflow.

package/departments/marketing/skills/social-strategy/references/listening-sources-template.md

@@ -0,0 +1,123 @@
+# Listening Sources — Template
+
+Copy this file to `.agents/listening-sources.md` in your project (or `.claude/listening-sources.md`) and fill in the brackets. Claude reads it when running the [listening workflow](listening.md).
+
+Delete sections you don't use. Keep this short and current — stale sources are worse than no sources.
+
+---
+
+## What We're Listening For
+
+**Brand / product:** [Your product name]
+**Category:** [e.g., "AI writing assistant", "Postgres GUI"]
+**Goal:** [e.g., "find people switching from Notion", "engage with B2B SaaS founders 50-200 employees"]
+
+## ICP (for scoring)
+
+Used by the [scoring rubric](listening.md#scoring-rubric) to judge ICP fit.
+
+- **Role:** [e.g., "founder, head of marketing, marketing ops lead"]
+- **Company stage:** [e.g., "seed to Series B SaaS, 10-200 employees"]
+- **Industry:** [e.g., "B2B SaaS, infra, devtools"]
+- **Signals they're a fit:** [e.g., "writes about GTM, runs paid ads, recently raised"]
+
+---
+
+## Target Accounts
+
+Engage with **every** post from these accounts when relevant. Keep this list to 20-50 max.
+
+### LinkedIn (browser-driven — use dev-browser to view feed)
+- [Name] — `linkedin.com/in/handle`
+- [Name] — `linkedin.com/in/handle`
+
+### X / Twitter (browser-driven)
+- [@handle]
+- [@handle]
+
+### Reddit
+- u/[username]
+- u/[username]
+
+### Bluesky
+- [handle.bsky.social]
+
+### Blogs / Newsletters (RSS)
+- [Name] — `https://example.com/feed/`
+- [Name] — `https://example.substack.com/feed`
+
+### YouTube channels (RSS)
+- [Name] — channel ID `UCxxxxxxxx`
+
+---
+
+## Keywords (intent signals)
+
+Search across all platforms. Claude runs these through Reddit, HN, Bluesky on the [daily loop](listening.md#the-daily-triage-loop).
+
+### High-intent (someone shopping or switching)
+- `"alternative to [competitor]"`
+- `"looking for a [category] tool"`
+- `"recommend a [category]"`
+- `"switching from [competitor]"`
+- `"frustrated with [competitor]"`
+
+### Problem signals (someone in pain)
+- `"[category] is so [bad/hard/expensive]"`
+- `"why is [category] [problem]"`
+- `"hate [pain point]"`
+
+### Brand mentions
+- `"[your brand]"`
+- `"[your brand misspelling]"`
+- `"[your domain]"`
+
+### Competitor mentions (monitor for switching language)
+- `"[competitor 1]"`
+- `"[competitor 2]"`
+
+---
+
+## Subreddits
+
+Pulled via Reddit JSON API on the daily loop.
+
+- r/SaaS
+- r/Entrepreneur
+- r/[your niche, e.g., "marketing", "devtools"]
+- r/[adjacent community]
+
+---
+
+## Saved Searches (manual / browser-driven)
+
+URLs Claude opens via dev-browser to scan.
+
+### LinkedIn Sales Navigator
+- [Search name] — `https://linkedin.com/sales/search/people?...`
+
+### LinkedIn (regular)
+- Posts hashtag — `https://linkedin.com/feed/hashtag/yourtopic/`
+
+### X advanced search
+- [Search name] — `https://x.com/search?q=...&f=live`
+
+---
+
+## Do Not Engage
+
+Save yourself the regret.
+
+- Accounts known for bad-faith dunking: [@handle], [@handle]
+- Blocked brands / competitors who'll screenshot: [list]
+- Topics to avoid: [politics, [your founder's hot takes], etc.]
+
+---
+
+## Notes for Claude
+
+- When asked for "today's top 10," output in the format defined in [listening.md](listening.md#the-daily-triage-loop)
+- For LinkedIn and X, use dev-browser with the persistent session (user is logged in)
+- For everything else, use the curl recipes in [listening.md](listening.md#sources--light-tooling-curl-recipes)
+- Default lookback: 24h. User can override.
+- Always ask before posting — output drafts, user approves and posts manually

package/departments/marketing/skills/social-strategy/references/listening.md

@@ -0,0 +1,283 @@
+# Social Listening & Engagement Triage
+
+How to surface the right posts to engage with each day — instead of randomly scrolling. The goal is a short, scorable list ("here are your top 10 posts to comment on") rather than an open feed.
+
+## Contents
+- When to use this
+- The daily triage loop
+- Scoring rubric
+- Comment quality tiers
+- Sources & light tooling (curl recipes)
+- Per-platform notes
+- Common workflows
+
+---
+
+## When to Use This
+
+Use listening when the goal is **commenting and relationships**, not posting. Typical asks:
+- "Give me the top 10 posts I should comment on today"
+- "Who's complaining about [competitor] right now?"
+- "Find people asking for a tool like mine"
+- "Surface posts from my 20 target accounts in the last 24h"
+- "What's the conversation around [topic] this week?"
+
+If the user wants to **create** content, use the rest of the social skill. Listening feeds creation (it surfaces angles, language, objections), but the output is different.
+
+---
+
+## The Daily Triage Loop
+
+A repeatable 20-minute loop the user (or you, on their behalf) can run each morning.
+
+1. **Pull** — fetch new posts from defined sources (target accounts, keywords, subreddits, hashtags). See [tooling](#sources--light-tooling-curl-recipes).
+2. **Filter** — drop anything older than 24h, low signal, or off-topic.
+3. **Score** — apply the [rubric](#scoring-rubric). Keep top 10.
+4. **Draft** — for each, draft a comment matched to the post's tier.
+5. **Post** — user reviews, edits, posts. Mark which actually went live.
+6. **Log** — track what you commented on and what got replies. This is your engagement loop dataset.
+
+Output format Claude should produce:
+
+```
+TOP 10 POSTS — 2026-06-05
+
+1. [Score 9/10] @author — LinkedIn — 2h ago
+   "We just rolled out X and the team is loving it…"
+   Why: ICP fit (B2B SaaS, 50–200 employees), buying-intent signal
+   Suggested comment: [draft]
+   Link: https://…
+```
+
+---
+
+## Scoring Rubric
+
+Score each post 1–10 across five dimensions, then sum and rank.
+
+| Dimension | What it measures | Weight |
+|-----------|------------------|--------|
+| **ICP fit** | Is the author your target customer / influencer? | 2x |
+| **Intent signal** | Are they expressing a problem, asking, or shopping? | 2x |
+| **Reach potential** | Is the post getting traction (likes/comments rising)? | 1x |
+| **Comment opportunity** | Can you say something genuinely useful, not generic? | 2x |
+| **Recency** | Posted in last 1–4h (early comments win, especially on LinkedIn) | 1x |
+
+**Intent signal examples (high-value):**
+- "Looking for a tool that does X"
+- "Why is [category] so painful?"
+- "We just switched from [competitor] because…"
+- "Anyone use [competitor] — is it worth it?"
+- A complaint about a known competitor
+
+**Drop if any of these are true:**
+- Author isn't ICP and isn't an influencer
+- Post is >24h old and already has 50+ comments (your comment buries)
+- Generic motivational/AI-slop post
+- Self-promotion thread where comments don't get reach
+- You can't add anything beyond "Great post!"
+
+---
+
+## Comment Quality Tiers
+
+Match the comment to the post. Don't waste a tier-1 draft on a tier-3 opportunity.
+
+**Tier 1 — Relationship builder (target accounts, ICP, high intent)**
+- Add a specific insight or counter-example
+- Reference your own experience with specifics (numbers, names, outcomes)
+- Ask a thoughtful follow-up that invites a reply
+- Length: 2–4 sentences, no link
+
+**Tier 2 — Visibility play (high-reach post, adjacent topic)**
+- Add one sharp insight in one sentence
+- Pattern: "Agreed — and the part most miss is [X]"
+- Length: 1–2 sentences
+
+**Tier 3 — Light touch (relationship maintenance)**
+- Specific reaction, not "Love this"
+- Quote a specific line and react to it
+- Length: 1 sentence
+
+**Never:** "Great post!", emoji-only, "+1", LinkedIn-isms like "This is gold 🔥"
+
+---
+
+## Sources & Light Tooling (curl recipes)
+
+These are public JSON endpoints — no auth needed. Run them from bash, pipe to `jq`, and Claude can parse the output to score and draft comments.
+
+**Requires:** `jq` (most recipes) and `xmllint` (RSS only). Install once:
+```bash
+# macOS
+brew install jq
+# xmllint ships with macOS; on Linux: apt install libxml2-utils
+```
+
+### Reddit (free, scriptable)
+
+**New posts in a subreddit:**
+```bash
+curl -s -A "listening/1.0" \
+  "https://www.reddit.com/r/SaaS/new.json?limit=25" \
+  | jq '.data.children[].data | {title, author, url: ("https://reddit.com"+.permalink), score, num_comments, created_utc, selftext: (.selftext | .[0:300])}'
+```
+
+**Search across Reddit by keyword (last day, sorted new):**
+```bash
+curl -s -A "listening/1.0" \
+  "https://www.reddit.com/search.json?q=KEYWORD&sort=new&t=day&limit=25" \
+  | jq '.data.children[].data | {subreddit, title, url: ("https://reddit.com"+.permalink), author, score, created_utc}'
+```
+
+Swap `KEYWORD` for things like `"alternative to notion"`, `"recommend a crm"`, your competitor names, or your own brand for mentions. Use quotes around multi-word phrases.
+
+### Hacker News (Algolia search)
+
+**Recent stories mentioning a keyword (last 24h):**
+```bash
+SINCE=$(($(date +%s) - 86400))
+curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=story&numericFilters=created_at_i>${SINCE}" \
+  | jq '.hits[] | {title, url, author, points, num_comments, created_at, story_id: .objectID, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
+```
+
+**Recent comments mentioning a keyword:**
+```bash
+curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=comment&numericFilters=created_at_i>${SINCE}" \
+  | jq '.hits[] | {author, comment_text, story_title, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
+```
+
+### Bluesky (free, public API)
+
+**Search posts by keyword:**
+```bash
+curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=KEYWORD&limit=25&sort=latest" \
+  | jq '.posts[] | {author: .author.handle, text: .record.text, likes: .likeCount, replies: .replyCount, url: ("https://bsky.app/profile/"+.author.handle+"/post/"+(.uri | split("/") | last))}'
+```
+
+### RSS for blogs, podcasts, YouTube channels
+
+For target accounts that publish to RSS (most blogs, all YouTube channels):
+```bash
+# YouTube channel feed (replace CHANNEL_ID)
+curl -s "https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID"
+
+# Generic blog feed
+curl -s "https://example.com/feed/" | xmllint --xpath "//item[position()<6]" - 2>/dev/null
+```
+
+### LinkedIn & X — use the browser
+
+LinkedIn and X don't expose useful public APIs, but you can drive a real browser session. **dev-browser** (MCP, already in the global setup) and **Playwright** both maintain persistent state — log in once, the session stays alive, Claude can navigate the authenticated feed.
+
+**dev-browser workflow (preferred — already wired up):**
+1. User logs into LinkedIn / X once in the dev-browser session
+2. Claude navigates to a target URL (feed, profile, saved search, hashtag)
+3. Claude reads the accessibility tree / page text, extracts posts
+4. Claude scores using the [rubric](#scoring-rubric) and drafts comments
+5. User reviews and posts manually (don't auto-post — high-stakes, bot detection risk)
+
+**Useful URLs to feed dev-browser:**
+
+| URL pattern | What it shows |
+|-------------|---------------|
+| `linkedin.com/in/HANDLE/recent-activity/all/` | A target account's recent posts |
+| `linkedin.com/feed/hashtag/TOPIC/` | Hashtag feed |
+| `linkedin.com/feed/` | Your main feed (algorithmic — less useful for triage) |
+| `x.com/HANDLE` | A target account's profile |
+| `x.com/search?q=QUERY&f=live` | Real-time search (use `f=live` for chronological) |
+| `x.com/i/lists/LIST_ID` | A curated list — best for target accounts |
+
+**Tips:**
+- On X, build a private list of target accounts and use the list URL. Far cleaner than the algorithmic feed.
+- LinkedIn's `/recent-activity/all/` URL is the cleanest way to see one person's posts without the algorithm.
+- For both platforms, scroll programmatically (dev-browser supports it) to load more posts before extracting.
+
+**Paid alternatives if you don't want to drive a browser:**
+
+| Platform | Tools |
+|----------|-------|
+| LinkedIn | Sales Navigator (saved searches), Taplio (engagement) |
+| X | TweetDeck/X Pro (saved columns), Typefully, Taplio, Tweet Hunter |
+
+**Still closed (no good path):**
+- Instagram & TikTok — closed APIs, browser automation is detectable and risky. Use native saved searches / hashtag follows.
+
+---
+
+## Per-Platform Notes
+
+### LinkedIn
+- **Browser-driven** (dev-browser with persistent session) — see [LinkedIn & X — use the browser](#linkedin--x--use-the-browser)
+- **First-hour comments matter most** — algorithm weights early engagement heavily. Prioritize posts <2h old from target accounts.
+- Comments with 5+ words get more reach than reactions
+- Replying to other commenters can put you in front of their network
+- Tag the author in your reply only if it adds context
+
+### Twitter/X
+- **Browser-driven** (dev-browser) — build a private list of target accounts and point dev-browser at the list URL
+- Reply within first 30 min for max reach on big accounts
+- Quote-tweet > reply when adding substantial value
+- Threading your reply (multi-tweet) signals effort
+- Don't pile on dunks — relationships > clout
+
+### Reddit
+- Read the subreddit rules before commenting (some ban self-promotion outright)
+- Earn karma in the sub before linking to anything you own
+- Long, specific answers win. AMAs and "help me decide" threads are gold
+- Never lead with your product — answer the question first
+
+### Hacker News
+- Comment quality bar is high; low-effort gets downvoted fast
+- Founders commenting on threads about their product is welcomed if you're transparent
+- Search for past discussions of your category — they're often dormant gold mines
+
+### Bluesky
+- Smaller volume but high engagement-to-follower ratio
+- Tech and indie-hacker communities are active
+- Custom feeds (like Bluesky's "Following" + topic feeds) replace algorithmic search
+
+---
+
+## Common Workflows
+
+### "Give me my top 10 posts to comment on today"
+1. Pull from: target account RSS/saved searches + Reddit (relevant subs) + HN (last 24h)
+2. Score with the [rubric](#scoring-rubric)
+3. Output top 10 with suggested comments
+
+### "Find people complaining about [competitor]"
+1. Reddit search: `"competitor name" -site:competitor.com` sorted by new
+2. HN comment search for competitor name
+3. Bluesky search for competitor handle/name
+4. Score by intent signal (high if switching language: "moving from", "alternatives to", "frustrated with")
+
+### "Surface brand mentions from the last week"
+1. Reddit search for brand name
+2. HN search (stories + comments) for brand name
+3. Bluesky search for brand name + handle
+4. Output as: reply needed (yes/no), tone (positive/negative/neutral), suggested response
+
+### "Find target-account posts I missed"
+1. Maintain a list of target accounts with their RSS / Reddit usernames / Bluesky handles
+2. Fetch each source's recent posts
+3. Filter to last 24h, output sorted by score
+
+---
+
+## Setting Up the Source List
+
+The user should maintain a list of sources somewhere persistent at `.agents/listening-sources.md` (or `.claude/listening-sources.md`). Claude reads it when running the daily loop.
+
+**A ready-to-fill template lives at [listening-sources-template.md](listening-sources-template.md).** Copy it into the project and edit. The source path depends on how the skill was installed:
+
+```bash
+# Plugin / marketplace install (most common):
+cp .agents/skills/social/references/listening-sources-template.md .agents/listening-sources.md
+# .claude/ install:
+cp .claude/skills/social/references/listening-sources-template.md .agents/listening-sources.md
+# Working inside the marketingskills repo:
+cp skills/social/references/listening-sources-template.md .agents/listening-sources.md
+```
+
+The template covers: brand/category, ICP (for scoring), target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list.

package/departments/marketing/skills/social-strategy/references/platform-limits.md

@@ -0,0 +1,110 @@
+# Platform Limits Reference
+
+Quick reference for hashtag limits, character counts, and visible text thresholds on each major social platform.
+
+---
+
+## Instagram
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 5 (official limit) |
+| Recommended hashtags | 3 – 5 |
+| Max caption chars | 2,200 |
+| Visible before "more" | ~125 chars |
+
+---
+
+## Facebook
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | No official limit |
+| Recommended hashtags | 1 – 2 |
+| Max post chars | 63,206 |
+| Ideal for engagement | 40 – 80 chars |
+
+---
+
+## TikTok
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 5 (since August 2025) |
+| Recommended hashtags | 3 – 5 |
+| Max caption chars | 4,000 |
+| Visible before "more" | ~150 chars |
+
+---
+
+## LinkedIn
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | No official limit |
+| Recommended hashtags | 3 – 5 |
+| Max post chars | 3,000 |
+| Visible before "more" | ~210 chars |
+
+---
+
+## Twitter/X
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | No official limit |
+| Recommended hashtags | 1 – 2 |
+| Max tweet chars | 280 (standard) / 25,000 (Premium+) |
+| Visible before "more" | Full tweet (280 standard) |
+
+---
+
+## YouTube
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 15 (exceeding this causes YouTube to ignore ALL hashtags) |
+| Recommended hashtags | 3 – 5 |
+| Max title chars | 100 (visible before truncation: ~70) |
+| Max description chars | 5,000 |
+| Visible before "Show more" | ~100 chars |
+
+> The first 3 hashtags in the description automatically appear above the title as clickable links. For Shorts, use 1 – 5 hashtags.
+
+---
+
+## Pinterest
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 20 per pin |
+| Recommended hashtags | 2 – 5 |
+| Max pin title chars | 100 |
+| Max description chars | 500 |
+| Visible before "More" | ~50 chars (desktop) |
+
+> Pinterest has deprioritized hashtags. Focus on keywords as natural sentences within the description for better SEO instead of relying on hashtags.
+
+---
+
+## Threads (Meta)
+
+| Element | Limit |
+|---------|-------|
+| Max hashtags | 1 per post (topic tag) |
+| Recommended hashtags | 1 |
+| Max post chars | 500 |
+| Max with text attachment | 10,500 (500 + 10,000 expandable) |
+| Visible without expanding | First ~1 – 2 lines |
+
+> Threads limits topic tags to one per post. The platform is not hashtag-driven — the algorithm prioritizes content from followed accounts mixed with recommendations.
+
+---
+
+## Usage Tips
+
+- **Hashtags count against character limits** on all platforms
+- **Front-load your message** before the "more" truncation point
+- On Instagram and TikTok, fewer hashtags now outperform hashtag-stuffing
+- On LinkedIn, hashtags at the end of the post perform better than inline
+- On Facebook, hashtags have minimal impact on reach — use sparingly