@opendirectory.dev/skills 0.1.38 → 0.1.40

package/skills/where-your-customer-lives/README.md

@@ -0,0 +1,135 @@
+# where-your-customer-lives
+
+Give this skill a product utility and ICP. It searches Reddit, Hacker News, and DuckDuckGo to find the specific communities where your customer actually gathers -- then builds a per-channel playbook: evidence your ICP is there, one entry tactic, one content angle, and specific anti-patterns.
+
+Stop guessing which communities to post in. Get signal-traced evidence.
+
+## Install
+
+```bash
+npx "@opendirectory.dev/skills" install where-your-customer-lives --target claude
+```
+
+## What It Does
+
+- Accepts: product description + ICP role + ICP pain + competitors (any combination)
+- Signal-traces: searches Reddit/HN for posts matching your ICP, extracts which communities those posts came from
+- Competitor layer: searches where competitors are discussed -- those communities have evaluating ICP
+- Discovers 7 channel types: Reddit, Slack, Discord, Newsletter, Podcast, Conference, YouTube
+- Fetches actual member counts from Reddit API and DuckDuckGo snippets -- no estimates
+- Scores channels: ICP signal count (10x) + size (log scale) + activity + competitor mentions - entry penalty
+- Generates per-channel playbook: who is here, entry tactic, content angle, anti-patterns
+- Saves to `docs/channel-map/[slug]-[date].md` + JSON snapshot
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|---|---|---|
+| GITHUB_TOKEN | Optional -- improves competitor layer rate limit | github.com/settings/tokens (no scopes needed) |
+
+No other API keys required.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Add GITHUB_TOKEN if you want higher GitHub rate limits for competitor enrichment
+```
+
+## How to Use
+
+```
+"Where does my customer live? I build observability tools for DevOps engineers."
+"Find communities for my ICP: sales leaders at B2B SaaS startups dealing with low reply rates."
+"Where should I post? Competitors: Clay, Apollo. ICP: growth engineers."
+"What channels does my ICP use? Product: compliance automation for community banks."
+"I build payment APIs for marketplaces. Who should I reach out to and where?"
+```
+
+Include competitor names for richer channel discovery. Include ICP role + pain for accurate signal-tracing.
+
+## Why This Instead of Googling
+
+A founder doing this manually would:
+- Google "devops communities" and get listicles with outdated or generic results
+- Post in r/devops without knowing if their ICP is actually there
+- Spend a month in the wrong Slack before realizing it's not their market
+
+This skill traces backwards from actual ICP pain posts to their source communities. The channels it returns are the ones where your ICP is already discussing the exact problem you solve.
+
+## Channel Scoring
+
+```
+channel_score = (
+    icp_signal_count * 10              # signals traced here -- highest weight
+    + log10(members) * 15, max 50      # community size (log scale)
+    + activity_score, max 30           # posts/week proxy
+    + competitor_mentions * 5          # competitor discussed = ICP evaluating
+) - entry_penalty                      # -20 paid, -10 invite-only, 0 open
+```
+
+Score tiers: top-priority (100+), high (60-99), medium (30-59), low (<30).
+
+## Velocity Tracking
+
+Run the skill every quarter. JSON snapshots in `docs/channel-map/` let you track which communities grow or shrink for your ICP over time.
+
+## Cost Per Run
+
+- Reddit, HN: free, no auth
+- DuckDuckGo: free, no auth
+- GitHub: free with optional token
+- AI analysis: uses the model running the skill
+- Total: free
+
+## Standalone Script
+
+Run channel discovery without Claude. Useful when you want raw channel data first, then bring it to any AI for analysis.
+
+```bash
+# Basic usage
+python3 scripts/fetch.py "devops monitoring" --icp-role "DevOps engineers" --icp-pain "alert fatigue"
+
+# With competitors
+python3 scripts/fetch.py "B2B sales" --competitors "Clay,Apollo,HubSpot" --output results.json
+
+# Print to stdout
+python3 scripts/fetch.py "startup gtm" --icp-role "technical co-founders" --stdout | jq '.summary'
+
+# With GitHub token
+GITHUB_TOKEN=your_token python3 scripts/fetch.py "devops tools" --competitors "Datadog,Grafana"
+```
+
+The script writes a JSON file with all discovered channels. Open it with Claude and ask: "Generate a channel playbook from this data."
+
+## Project Structure
+
+```
+where-your-customer-lives/
+├── SKILL.md
+├── README.md
+├── .env.example
+├── scripts/
+│   └── fetch.py           standalone channel discovery script
+├── evals/
+│   └── evals.json         5 test cases
+└── references/
+    ├── channel-types.md   7 channel types, discovery methods, scoring notes
+    ├── entry-tactics.md   entry tactic templates per channel type
+    └── scoring-guide.md   channel scoring formula and tier thresholds
+```
+
+## What map-your-market Does vs. This Skill
+
+| | map-your-market | where-your-customer-lives |
+|---|---|---|
+| Question answered | What does my market care about? | Where does my market gather? |
+| Output | Pain clusters, ICP profile, positioning framework | Ranked channel list with per-channel playbook |
+| Data sources | Reddit, HN, GitHub Issues, G2, Trends | Reddit, HN, DuckDuckGo (7 channel types) |
+| Primary use | Market research, messaging | Distribution, outreach, GTM channels |
+
+Run both for a complete picture: map-your-market tells you what to say, where-your-customer-lives tells you where to say it.
+
+## License
+
+MIT

package/skills/where-your-customer-lives/SKILL.md

@@ -0,0 +1,515 @@
+---
+name: where-your-customer-lives
+description: Given a product utility and ICP, researches the internet to find the specific channels. Where your customer actually lives, ranked by reachability with a full per-channel playbook. Returns evidence that your ICP is there, one entry tactic, one content angle, and specific anti-patterns per channel. Use when asked where my customer hangs out, what communities should I post in, where is my ICP, find channels for outreach, what forums does my ICP use, where should I spend time for distribution, or which communities are right for my product.
+compatibility: [claude-code, gemini-cli, github-copilot]
+---
+
+# Where Your Customer Lives
+
+Given a product utility and ICP, trace real ICP pain posts back to their source communities. Layer in competitor discussion signals. Discover Slack/Discord/newsletter/podcast/conference channels via DuckDuckGo. Score every channel by ICP signal count, size, activity, and competitor presence. Output a ranked playbook: evidence, entry tactic, content angle, anti-patterns -- one per channel. No guessing. Signal-traced channels only.
+
+---
+
+**Critical rule:** Every channel name in the output must exist in either the Reddit API response or DuckDuckGo search results from this run. Every member count must come from the `about.json` API or a search snippet -- never estimated. Every ICP signal count must match the raw data. If a channel type returns 0 results, report 0 -- do not fabricate channels.
+
+---
+
+## Common Mistakes
+
+| The agent will want to... | Why that's wrong |
+|---|---|
+| Recommend generic channels ("LinkedIn", "Twitter") | Every channel must be specific with a name, member count, and URL. "LinkedIn Group: DevOps for Enterprise Teams (45K members)" -- not just "LinkedIn". |
+| Use the same channels for every ICP | Signal-trace is ICP-specific. A DevOps ICP and a Finance ICP produce entirely different channel lists. Run the script fresh per ICP. |
+| Invent member counts or community names | Every channel name must come from DuckDuckGo results or Reddit API. Every member count must come from the API or a search snippet. If unavailable, write "member count not found". |
+| Skip the competitor layer | Where competitors are discussed = your ICP is evaluating alternatives = hottest outreach context. Always run competitor search even if the user did not ask. |
+| Write entry tactics that are product pitches | "Post about your product in r/devops" is not an entry tactic. Entry tactics name the specific thread type, content format, and community norm. |
+| Treat Reddit as the only channel type | The output must include at least 3 channel types. If only Reddit is found, explicitly search DuckDuckGo for Slack/Discord/newsletter/conference before stopping. |
+
+---
+
+## Step 1: Setup Check
+
+```bash
+echo "GITHUB_TOKEN: ${GITHUB_TOKEN:-not set -- competitor layer runs at 60 req/hr unauthenticated}"
+echo ""
+echo "Data sources this run will use:"
+echo "  Reddit public JSON   (no auth, signal-trace)"
+echo "  Reddit about.json    (no auth, subreddit metadata)"
+echo "  HN Algolia API       (no auth, signal-trace)"
+echo "  DuckDuckGo HTML      (no auth, channel discovery)"
+echo "  GitHub API           (${GITHUB_TOKEN:+authenticated, }optional for competitor enrichment)"
+```
+
+If `GITHUB_TOKEN` is not set: continue. All core channel discovery works without it.
+
+---
+
+## Step 2: Parse ICP
+
+Collect from the conversation:
+- `product` -- what the product does (one sentence)
+- `icp_role` -- who the ICP is (e.g. "technical co-founders", "DevOps engineers at Series A")
+- `icp_pain` -- their primary problem (e.g. "customer acquisition", "alert fatigue")
+- `category` -- market category keywords (e.g. "startup gtm sales", "devops monitoring")
+- `competitors` -- optional competitor names (e.g. "Clay, Apollo, HubSpot")
+
+**ICP cascade:**
+1. If the user's prompt contains product + icp_role + icp_pain: extract them directly and proceed.
+2. If the prompt is thin (only category or only product name): check `docs/icp.md` for a saved ICP profile. Merge with prompt details.
+3. If still insufficient (missing icp_role or icp_pain): ask these 3 questions, one at a time:
+   - "What does your product do in one sentence?"
+   - "Who is your ideal customer? (role, company type, team size)"
+   - "What is their primary problem before they find your product?"
+4. Save the final ICP to `docs/icp.md` so other skills can reuse it.
+
+Save ICP file if docs/icp.md does not already contain this product:
+
+```bash
+python3 << 'PYEOF'
+import json, os
+
+icp = {
+    "product": "PRODUCT_HERE",
+    "icp_role": "ICP_ROLE_HERE",
+    "icp_pain": "ICP_PAIN_HERE",
+    "competitors": ["COMP_1", "COMP_2"],
+    "category": "CATEGORY_HERE"
+}
+
+os.makedirs("docs", exist_ok=True)
+with open("/tmp/wcl-input.json", "w") as f:
+    json.dump(icp, f, indent=2)
+
+# Update docs/icp.md
+icp_md_path = "docs/icp.md"
+new_block = f"""## {icp['product']}
+- **ICP role:** {icp['icp_role']}
+- **ICP pain:** {icp['icp_pain']}
+- **Competitors:** {', '.join(icp['competitors']) if icp['competitors'] else 'none'}
+- **Category:** {icp['category']}
+"""
+existing = open(icp_md_path).read() if os.path.exists(icp_md_path) else ""
+if icp['product'] not in existing:
+    with open(icp_md_path, "a") as f:
+        f.write(new_block)
+    print(f"ICP saved to {icp_md_path}")
+else:
+    print(f"ICP already in {icp_md_path}")
+
+print(f"Product: {icp['product']}")
+print(f"ICP role: {icp['icp_role']}")
+print(f"ICP pain: {icp['icp_pain']}")
+print(f"Competitors: {', '.join(icp['competitors']) if icp['competitors'] else 'none'}")
+PYEOF
+```
+
+---
+
+## Step 3: Run the Standalone Data Collection Script
+
+Check if the script exists:
+
+```bash
+ls scripts/fetch.py 2>/dev/null && echo "script available" || echo "not found"
+```
+
+Run channel discovery:
+
+```bash
+GITHUB_TOKEN="${GITHUB_TOKEN:-}" python3 scripts/fetch.py \
+    "$(python3 -c "import json; d=json.load(open('/tmp/wcl-input.json')); print(d['category'])")" \
+    --icp-role "$(python3 -c "import json; d=json.load(open('/tmp/wcl-input.json')); print(d['icp_role'])")" \
+    --icp-pain "$(python3 -c "import json; d=json.load(open('/tmp/wcl-input.json')); print(d['icp_pain'])")" \
+    --product "$(python3 -c "import json; d=json.load(open('/tmp/wcl-input.json')); print(d['product'])")" \
+    --competitors "$(python3 -c "import json; d=json.load(open('/tmp/wcl-input.json')); print(','.join(d['competitors']))")" \
+    --output /tmp/wcl-raw.json
+```
+
+Wait for completion (allow up to 5 minutes -- Reddit + DuckDuckGo searches take ~120 seconds total).
+
+Verify output:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/wcl-raw.json') as f:
+    d = json.load(f)
+print(f'Reddit posts found: {d[\"reddit_posts_found\"]}')
+print(f'HN signals found:   {d[\"hn_signals_found\"]}')
+print(f'Channels discovered: {d[\"summary\"][\"total_channels\"]}')
+print(f'Top priority:        {len(d[\"summary\"][\"top_priority\"])}')
+print(f'By type:             {d[\"summary\"][\"by_type\"]}')
+print(f'Competitor layer ran: {d[\"summary\"][\"competitor_layer_ran\"]}')
+"
+```
+
+If total_channels < 3: tell the user: "Fewer than 3 channels found. The ICP description may be too narrow for Reddit/DDG coverage. Try broader category keywords, or add competitor names to activate the competitor layer." Then attempt one retry with broader category keywords before stopping.
+
+---
+
+## Step 4: Print Channel Summary
+
+Load the raw data and print a ranked summary table:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/wcl-raw.json') as f:
+    d = json.load(f)
+channels = d['channels_discovered']
+print(f'Channels found: {len(channels)}')
+print()
+print(f'{'#':<4} {'Channel':<35} {'Type':<14} {'Members':<12} {'ICP signals':<13} {'Score':<8} Tier')
+print('-' * 100)
+for i, ch in enumerate(channels[:15], 1):
+    members = ch.get('members', 0)
+    m_str = f'{members//1000}K' if members >= 1000 else str(members) if members else '?'
+    print(f'{i:<4} {ch[\"name\"]:<35} {ch[\"type\"]:<14} {m_str:<12} {ch.get(\"icp_signal_count\",0):<13} {ch.get(\"channel_score\",0):<8} {ch.get(\"tier\",\"\")}')
+"
+```
+
+Print the top 3 evidence posts from the highest-scoring channel:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/wcl-raw.json') as f:
+    d = json.load(f)
+channels = d['channels_discovered']
+if channels:
+    top = channels[0]
+    print(f'Top channel: {top[\"name\"]}')
+    print(f'Evidence posts:')
+    for ep in top.get('evidence_posts', [])[:3]:
+        print(f'  [{ep.get(\"score\",0):.0f}] {ep.get(\"title\",\"\")}')
+        print(f'       {ep.get(\"url\",\"\")}')
+"
+```
+
+---
+
+## Step 5: AI Channel Enrichment
+
+You now have the raw channel data. For each channel in the top-priority and high tiers, generate a playbook entry.
+
+Load all channels:
+
+```bash
+python3 -c "
+import json
+with open('/tmp/wcl-raw.json') as f:
+    d = json.load(f)
+top_channels = [ch for ch in d['channels_discovered'] if ch.get('tier') in ('top-priority', 'high')]
+print(json.dumps(top_channels, indent=2))
+"
+```
+
+For each channel above, generate:
+
+**who_is_here:** 2 sentences describing the specific type of ICP present in this channel. Derive from the evidence posts, subreddit description, and ICP profile. Do NOT write "your target audience" -- be specific. Example: "DevOps engineers at companies of 50-500 who own the infra stack without a dedicated SRE team. They post about on-call burnout, Kubernetes sprawl, and choosing between cloud-native and self-hosted observability."
+
+**entry_tactic:** One specific, actionable entry move. Name the thread type, posting format, and community norm. NOT "engage with the community." Example: "Find the weekly 'What are you working on?' thread (posted every Monday by automoderator). Reply with a 3-sentence technical challenge you solved -- what broke, what you tried, what worked. No product mention. Build karma before posting standalone content."
+
+**content_angle:** The content format that gets highest engagement in this specific channel, derived from evidence post titles and scores. Example: "Technical post-mortems outperform product announcements 5:1 here. Format: 'We migrated 200K users from X to Y -- here is what broke and why.' Concrete numbers + what failed = most upvotes."
+
+**anti_patterns:** 2-3 specific behaviors that get posts removed or reputation destroyed in this community. Derive from subreddit rules (if available in description) and evidence post patterns. Example: ["Posting product links in non-promotional threads -- moderators remove within hours", "Asking 'what tools do you use?' without specific context -- flagged as market research farming"]
+
+Write the enriched playbook to `/tmp/wcl-channels.json`:
+
+```json
+{
+  "playbook": [
+    {
+      "channel": "r/devops",
+      "evidence": "34 ICP signals traced here, avg pain score 180",
+      "who_is_here": "...",
+      "entry_tactic": "...",
+      "content_angle": "...",
+      "anti_patterns": ["...", "..."]
+    }
+  ]
+}
+```
+
+```bash
+python3 -c "
+import json
+with open('/tmp/wcl-channels.json') as f:
+    d = json.load(f)
+print(f'Playbook entries: {len(d[\"playbook\"])}')
+for p in d['playbook']:
+    print(f'  {p[\"channel\"]}')
+"
+```
+
+---
+
+## Step 6: Generate Full Ranked Output
+
+Write the complete ranked playbook to `/tmp/wcl-output.json`:
+
+```bash
+python3 << 'PYEOF'
+import json
+from datetime import datetime
+
+with open('/tmp/wcl-input.json') as f:
+    inp = json.load(f)
+with open('/tmp/wcl-raw.json') as f:
+    raw = json.load(f)
+with open('/tmp/wcl-channels.json') as f:
+    enriched = json.load(f)
+
+playbook_by_channel = {p['channel']: p for p in enriched['playbook']}
+channels = raw['channels_discovered']
+
+output = {
+    "date": raw['date'],
+    "product": inp['product'],
+    "icp_role": inp['icp_role'],
+    "icp_pain": inp['icp_pain'],
+    "competitors": inp.get('competitors', []),
+    "total_channels": raw['summary']['total_channels'],
+    "channels": []
+}
+
+for ch in channels:
+    name = ch['name']
+    playbook = playbook_by_channel.get(name, {})
+    output['channels'].append({
+        "rank": channels.index(ch) + 1,
+        "name": name,
+        "type": ch['type'],
+        "url": ch['url'],
+        "members": ch.get('members', 0),
+        "active_users": ch.get('active_users', 0),
+        "icp_signal_count": ch.get('icp_signal_count', 0),
+        "competitor_mentions": ch.get('competitor_mentions', 0),
+        "channel_score": ch.get('channel_score', 0),
+        "tier": ch.get('tier', ''),
+        "entry_type": ch.get('entry_type', 'open'),
+        "evidence_posts": ch.get('evidence_posts', []),
+        "who_is_here": playbook.get('who_is_here', ''),
+        "entry_tactic": playbook.get('entry_tactic', ''),
+        "content_angle": playbook.get('content_angle', ''),
+        "anti_patterns": playbook.get('anti_patterns', []),
+    })
+
+with open('/tmp/wcl-output.json', 'w') as f:
+    json.dump(output, f, indent=2)
+
+print(f"Output written: /tmp/wcl-output.json")
+print(f"Total channels: {len(output['channels'])}")
+PYEOF
+```
+
+---
+
+## Step 7: Self-QA
+
+```bash
+python3 -c "
+import json
+
+with open('/tmp/wcl-raw.json') as f:
+    raw = json.load(f)
+with open('/tmp/wcl-output.json') as f:
+    output = json.load(f)
+
+full_text = json.dumps(output)
+raw_channel_names = {ch['name'].lower() for ch in raw['channels_discovered']}
+passes = 0
+fails = 0
+
+# Check 1: No em dashes
+if chr(8212) in full_text:
+    print('FAIL: em dash found in output -- replace with hyphen')
+    fails += 1
+else:
+    print('PASS: no em dashes')
+    passes += 1
+
+# Check 2: No banned words
+banned = ['powerful', 'robust', 'seamless', 'innovative', 'game-changing',
+          'streamline', 'leverage', 'transform', 'revolutionize']
+found = [w for w in banned if w.lower() in full_text.lower()]
+if found:
+    print(f'FAIL: banned words: {found}')
+    fails += 1
+else:
+    print('PASS: no banned words')
+    passes += 1
+
+# Check 3: At least 3 channel types
+types = {ch['type'] for ch in output['channels']}
+if len(types) < 3:
+    print(f'FAIL: only {len(types)} channel type(s) in output: {types}')
+    fails += 1
+else:
+    print(f'PASS: {len(types)} channel types: {types}')
+    passes += 1
+
+# Check 4: All channel names exist in raw data
+for ch in output['channels']:
+    if ch['name'].lower() not in raw_channel_names:
+        print(f'FAIL: channel not in raw data: {ch[\"name\"]}')
+        fails += 1
+
+if fails == 0:
+    print('PASS: all channel names verified in raw data')
+    passes += 1
+
+# Check 5: No generic entry tactics
+generic_phrases = ['engage with the community', 'post about your product', 'share your content']
+for ch in output['channels']:
+    tactic = ch.get('entry_tactic', '').lower()
+    for phrase in generic_phrases:
+        if phrase in tactic:
+            print(f'FAIL: generic entry tactic in {ch[\"name\"]}: contains \"{phrase}\"')
+            fails += 1
+
+if fails == 0:
+    print('PASS: entry tactics are channel-specific')
+
+print()
+print(f'Result: {passes} passed, {fails} failed')
+if fails > 0:
+    print('Fix failures before saving.')
+else:
+    print('All checks passed. Ready to save.')
+"
+```
+
+Fix any failures before proceeding to Step 8.
+
+---
+
+## Step 8: Save Output and Clean Up
+
+```bash
+python3 << 'PYEOF'
+import json, os, re
+from datetime import datetime
+
+with open('/tmp/wcl-input.json') as f:
+    inp = json.load(f)
+with open('/tmp/wcl-raw.json') as f:
+    raw = json.load(f)
+with open('/tmp/wcl-output.json') as f:
+    output = json.load(f)
+
+slug = re.sub(r'[^a-z0-9]+', '-', (inp.get('icp_role') or inp['category']).lower()).strip('-')[:40]
+date = datetime.now().strftime('%Y-%m-%d')
+os.makedirs('docs/channel-map', exist_ok=True)
+
+outpath_md = f"docs/channel-map/{slug}-{date}.md"
+outpath_json = f"docs/channel-map/{slug}-{date}.json"
+
+channels = output['channels']
+by_type = {}
+for ch in channels:
+    by_type.setdefault(ch['type'], []).append(ch)
+
+lines = [
+    f"# Where Your Customer Lives: {inp['product'] or inp['category'].title()}",
+    f"ICP: {inp['icp_role']} | Date: {date} | Channels found: {len(channels)}",
+    "",
+    "---",
+    "",
+    "## Channel Ranking",
+    "",
+]
+
+tier_labels = {"top-priority": "TOP PRIORITY", "high": "HIGH", "medium": "MEDIUM", "low": "LOW"}
+
+for ch in channels:
+    members = ch.get('members', 0)
+    m_str = f"{members//1000}K" if members >= 1000 else str(members) if members else "member count not found"
+    tier_label = tier_labels.get(ch.get('tier', ''), ch.get('tier', '').upper())
+    
+    lines.append(f"### #{ch['rank']}: {ch['name']} [score: {ch['channel_score']}] -- {tier_label}")
+    
+    active = ch.get('active_users', 0)
+    active_str = f" | Active: {active//1000}K/day" if active >= 1000 else f" | Active: {active}/day" if active else ""
+    lines.append(f"Type: {ch['type'].title()} | Members: {m_str}{active_str} | {ch.get('entry_type', 'open').title()} to join")
+    
+    evidence_str = f"{ch['icp_signal_count']} ICP signals traced here" if ch['icp_signal_count'] > 0 else "Discovered via DuckDuckGo search"
+    lines.append(f"Evidence: {evidence_str}")
+    
+    if ch.get('competitor_mentions', 0) > 0 and inp.get('competitors'):
+        lines.append(f"Competitor mentions: {ch['competitor_mentions']} across {', '.join(inp['competitors'][:3])}")
+    
+    lines.append("")
+    
+    if ch.get('who_is_here'):
+        lines.append(f"**Who is here:** {ch['who_is_here']}")
+        lines.append("")
+    
+    if ch.get('entry_tactic'):
+        lines.append(f"**Entry tactic:** {ch['entry_tactic']}")
+        lines.append("")
+    
+    if ch.get('content_angle'):
+        lines.append(f"**Content angle:** {ch['content_angle']}")
+        lines.append("")
+    
+    if ch.get('anti_patterns'):
+        lines.append("**Anti-patterns:**")
+        for ap in ch['anti_patterns']:
+            lines.append(f"- {ap}")
+        lines.append("")
+    
+    lines.append("---")
+    lines.append("")
+
+lines += [
+    "## Channel Summary by Type",
+    "",
+    "| Type | Count | Best channel | Score |",
+    "|---|---|---|---|",
+]
+for ch_type, chs in sorted(by_type.items(), key=lambda x: -max(c['channel_score'] for c in x[1])):
+    best = max(chs, key=lambda x: x['channel_score'])
+    lines.append(f"| {ch_type.title()} | {len(chs)} | {best['name']} | {best['channel_score']} |")
+
+lines += [
+    "",
+    "---",
+    "",
+    "## Data Quality Notes",
+    f"- All channel names exist in Reddit API response or DuckDuckGo search results",
+    f"- Member counts from Reddit about.json API or search snippets",
+    f"- ICP signal counts match raw data ({raw['reddit_posts_found']} Reddit posts, {raw['hn_signals_found']} HN signals)",
+    f"- Competitor layer ran: {raw['summary']['competitor_layer_ran']}",
+    f"- Sources: Reddit signal-trace, HN signal-trace, DuckDuckGo channel discovery",
+    "",
+    f"Saved to: {outpath_md}",
+    f"JSON snapshot: {outpath_json}",
+]
+
+with open(outpath_md, 'w') as f:
+    f.write('\n'.join(lines))
+
+# JSON snapshot
+snapshot = {
+    "input": inp,
+    "channels": channels,
+    "summary": raw['summary'],
+    "date": date,
+}
+with open(outpath_json, 'w') as f:
+    json.dump(snapshot, f, indent=2)
+
+print(f"Report saved: {outpath_md}")
+print(f"JSON snapshot: {outpath_json}")
+PYEOF
+```
+
+Clean up temp files:
+
+```bash
+rm -f /tmp/wcl-input.json /tmp/wcl-raw.json /tmp/wcl-channels.json /tmp/wcl-output.json
+echo "Done. Channel map saved to docs/channel-map/"
+```
+
+Present the full contents of the saved `.md` file to the user.