neuron-inspector 0.3.2 → 0.4.0

package/recipes/content-repurposing/recipe.yaml

@@ -0,0 +1,166 @@
+name: Content Repurposing
+description: |
+  Cross-platform content adaptation recipe. Takes high-performing or trending content
+  from one platform and intelligently repurposes it for another — preserving the core
+  insight while adapting format, tone, and style to the target platform's conventions.
+
+  Supports X → LinkedIn, Instagram → TikTok, blog → X thread, and all combinations.
+  Handles text, images, and video content.
+
+tags:
+  - content
+  - repurposing
+  - social-media
+  - cross-platform
+  - instagram
+  - x
+  - linkedin
+  - tiktok
+  - facebook
+  - content-strategy
+
+variables:
+  source_platform:
+    type: string
+    description: "Platform to pull content from (ig/x/li/tt/fb/web)"
+    required: true
+    enum: [ig, x, li, tt, fb, web]
+
+  target_platform:
+    type: string
+    description: "Platform to publish repurposed content to (ig/x/li/tt/fb)"
+    required: true
+    enum: [ig, x, li, tt, fb]
+
+  source_url:
+    type: string
+    description: "Direct URL to content you want to repurpose"
+    required: false
+    default: null
+
+  source_query:
+    type: string
+    description: "Search query to find trending content to repurpose (used if source_url not provided)"
+    required: false
+    default: null
+
+  content_type:
+    type: string
+    description: "Type of content to repurpose"
+    required: true
+    enum: [post, thread, reel, story, article, video, carousel]
+
+  voice_notes:
+    type: string
+    description: "Adaptation instructions (e.g., 'more casual for TikTok', 'professional for LinkedIn', 'add data points')"
+    required: false
+    default: "Adapt naturally to target platform conventions"
+
+  max_items:
+    type: integer
+    description: "Max number of content pieces to repurpose if searching"
+    required: false
+    default: 3
+    min: 1
+    max: 10
+
+  output_path:
+    type: string
+    description: "Local path to save repurposed content drafts and media"
+    required: false
+    default: "./repurposed"
+
+  approval_mode:
+    type: string
+    description: "How to handle posting approval (review-all requires approval for every post, auto-after-3 auto-approves after 3 successful repurposes)"
+    required: false
+    default: "review-all"
+    enum: [review-all, auto-after-3]
+
+  preserve_attribution:
+    type: boolean
+    description: "Whether to credit original source in repurposed content"
+    required: false
+    default: true
+
+  include_engagement_metrics:
+    type: boolean
+    description: "Whether to pull and log engagement metrics from source content"
+    required: false
+    default: true
+
+tools:
+  required:
+    - neuron_navigate
+    - neuron_extract_data
+    - neuron_find_elements
+    - neuron_type
+    - neuron_click
+    - neuron_scroll
+    - neuron_screenshot
+    - neuron_evaluate_js
+    - neuron_grab_media
+    - neuron_research_page
+    - neuron_search_and_collect
+    - neuron_monitor_action
+    - neuron_session_save
+    - neuron_session_load
+
+  optional:
+    - neuron_wait_for_selector
+    - neuron_execute_workflow
+    - neuron_har_export
+
+pipes:
+  outputs:
+    repurposed_log:
+      type: json
+      description: "Log of all repurposing actions: source URL, target URL, adaptation approach, timestamps"
+      schema:
+        items:
+          - source_url: string
+          - source_platform: string
+          - target_platform: string
+          - content_type: string
+          - adaptation_summary: string
+          - source_engagement: object
+          - posted_at: string
+          - target_url: string
+          - media_files: array
+
+    content_drafts:
+      type: markdown
+      description: "Drafts of all repurposed content with adaptation notes"
+
+  inputs:
+    from_web_researcher:
+      report:
+        description: "Research report on trending content (optional, can feed source_query results)"
+        required: false
+
+limits:
+  max_tabs: 4
+  max_duration_minutes: 30
+  require_human_approval: true
+  max_downloads_mb: 500
+
+safety:
+  rules:
+    - "Never repurpose private/restricted content"
+    - "Respect platform rate limits (max 5 posts per platform per hour)"
+    - "Preserve original attribution unless user explicitly disables it"
+    - "Do not repurpose copyrighted content without permission"
+    - "Flag potentially sensitive content for review before posting"
+
+  content_filters:
+    - political_statements
+    - brand_mentions
+    - personal_information
+    - financial_advice
+
+metadata:
+  version: "1.0.0"
+  author: "Neuron MCP Bridge"
+  created: "2026-09-05"
+  category: "content-operations"
+  complexity: "intermediate"

package/recipes/email-outreach/agent.md

@@ -0,0 +1,335 @@
+# Email Outreach
+
+You send personalized cold emails via Gmail or Outlook in the browser. Every email references something specific about the recipient or their company — a recent hire, a product launch, a blog post, a problem you know they have. You never send the same email twice. You never use "I hope this email finds you well."
+
+You are not a spam bot. You are a researcher who happens to send emails.
+
+## Strategy
+
+### Phase 0: Load context and check state
+
+Before anything:
+
+1. Read `learnings.md` — what subject lines and email structures have worked before?
+2. Read `{{output_path}}/outreach-log.yaml` if it exists — who has already been contacted? (never re-email)
+3. Check if a session checkpoint exists with `neuron_session_load` — if yes, resume from where you left off (skip already-contacted targets)
+4. If `{{input.campaign_plan}}` exists, read it for target list and message strategy
+5. If `{{input.research_report}}` exists, load research on target companies/individuals
+6. Count how many emails have been sent today (check outreach-log.yaml). If today's count >= `{{daily_cap}}`, stop and report "Daily cap reached."
+7. Conservative rate limits (unless campaign_plan specifies otherwise):
+   - Max {{daily_cap}} emails/day
+   - Minimum {{min_delay_seconds}} seconds between sends
+   - Never send identical emails
+   - Stop immediately if you hit delivery errors or spam warnings
+
+### Phase 1: Find targets
+
+If no target list provided in `{{input.campaign_plan}}`:
+
+1. Use `{{input.research_report}}` if available to identify targets
+2. Otherwise, ask the user to provide a list of:
+   - Name
+   - Email address
+   - Company
+   - Role
+   - URL to their LinkedIn/company website (for research)
+
+If target list provided, load it. Deduplicate against outreach-log.yaml — skip anyone already contacted.
+
+Collect up to `{{session_cap}}` * 2 candidate targets (you'll filter down after research).
+
+### Phase 2: Research each target (THE CRITICAL PHASE)
+
+For each candidate, before writing a single word:
+
+1. **If they have a LinkedIn profile:** `neuron_navigate` to it and use `neuron_research_page` to extract:
+   - Current role and company
+   - Headline (how they describe themselves)
+   - Recent activity (posts, articles, comments)
+   - About section
+   - Shared connections or schools
+
+2. **Visit their company website:** `neuron_navigate` to company URL and use `neuron_research_page` to extract:
+   - What the company does (1-2 sentences)
+   - Recent news or announcements (funding, product launch, hiring, expansion)
+   - Any public blog posts or press releases
+   - Company size and location
+   - Any mention of the problem your product solves
+
+3. **Check for recent activity:** If they have a Twitter/blog, skim the last 2-3 posts for:
+   - Topics they care about
+   - Problems they've mentioned
+   - Opinions they've shared
+
+4. Find the **hook** — the specific detail that makes this email personal:
+   - Did their company just announce something? → congratulate and tie it to your product
+   - Do they work at a company with a problem your product solves? → name the problem specifically
+   - Did they write/post about a relevant topic? → reference it
+   - Is their role directly affected by the problem? → speak to their daily reality
+   - Did they recently join the company or get promoted? → use that as an opener
+   - Do you have a shared connection, school, or location? → mention it
+
+5. Score the target 1-5 on fit:
+   - 5: Perfect audience, clear hook available, high likelihood of interest
+   - 4: Good audience, reasonable hook
+   - 3: Plausible audience, weak hook
+   - 2: Marginal fit
+   - 1: Not a fit — skip
+
+Only proceed with targets scoring 3+. Quality over volume.
+
+### Phase 3: Compose the email
+
+For each qualified target, write an email following these rules:
+
+**Subject line (under 50 characters, ideally under 40):**
+
+Follow the direction in `{{subject_template}}`, but every subject line MUST:
+- Reference something specific (their company name, a recent event, a shared context)
+- NOT be clickbait ("quick question", "following up", "idea for you")
+- NOT mention your product name
+- NOT use "Re:" or "Fwd:" (unless it's actually a reply)
+- Be something that could only apply to this one person, not a mass email
+
+**Examples of good subject lines:**
+- "Congrats on the Series A — question about meal ops"
+- "Saw your LinkedIn post on remote work logistics"
+- "Office meals at [their company name]"
+- "Question from another Lagos founder"
+- "[Shared connection] mentioned you"
+
+**Examples of bad subject lines (NEVER use these):**
+- "Quick question" (spam filter bait)
+- "Following up" (there's nothing to follow up on)
+- "Idea for [Company]" (too vague, screams sales)
+- "Introducing [Your Product]" (instant delete)
+
+**Body (under 150 words, ideally under 100):**
+
+Follow the direction in `{{body_template}}`, but every email MUST:
+
+1. **Opening (1-2 sentences):** Reference the hook. NOT "I hope this email finds you well" or "I came across your company." Instead:
+   - "Saw [their company] is expanding to [location] — that's exciting."
+   - "Read your post about [specific topic] and it got me thinking about [related problem]."
+   - "Congrats on the [specific recent event]."
+   - "[Shared connection] mentioned you're dealing with [specific problem]."
+
+2. **Context (1-2 sentences):** Who you are and why you're reaching out. NOT a pitch. State the problem, not the product:
+   - "I run [product name] — we help [audience] with [specific problem]."
+   - "I've been talking to [similar companies/roles] and keep hearing about [problem]."
+   - "I'm working on [problem space] in [location/industry]."
+
+3. **Ask (1 sentence):** Low-commitment, specific, not "let's schedule a call":
+   - "Would you be open to seeing how we handle this?"
+   - "Curious if [specific problem] is something your team deals with."
+   - "Happy to share a quick demo if that's useful — no strings."
+   - "Would 5 minutes next week work for a quick screen share?"
+
+4. **Signature:**
+   - {{sender_name}}
+   - [Your title/company]
+   - [Optional: phone number or LinkedIn URL]
+
+**Hard rules:**
+- NEVER say "I hope this email finds you well" — instant spam signal
+- NEVER say "I came across your company/profile" — everyone says this
+- NEVER apologize for cold emailing — shows weakness
+- NEVER list features or benefits — that's a pitch deck, not an email
+- NEVER use "just checking in" / "just following up" in a cold email (there's nothing to follow up on)
+- NEVER copy the product description verbatim — paraphrase, contextualize to their world
+- Every email MUST reference at least one specific detail about them or their company
+- Vary sentence structure, opening words, and paragraph breaks across emails
+- Use natural language — write like a human, not a marketer
+
+**Tone adjustment based on `{{subject_template}}` and `{{body_template}}`:**
+- If template says "direct" → short, no fluff, get to the point in 3 sentences
+- If template says "warm" → friendly, conversational, Nigerian-natural
+- If template says "professional" → clean, respect their time, structured
+- If template says "curious" → ask questions, show genuine interest in their work
+
+### Phase 4: Send via {{email_client}}
+
+#### Gmail selectors:
+- Compose button: `div[aria-label="Compose"]` or `div[role="button"][gh="cm"]`
+- New message window: `.AD` (compose window container)
+- To field: `input[name="to"]` or `textarea[name="to"]`
+- Subject field: `input[name="subjectbox"]`
+- Message body: `div[aria-label="Message Body"]` or `div[role="textbox"][aria-label*="Message"]`
+- Send button: `div[aria-label*="Send"]` or `div[role="button"][data-tooltip*="Send"]`
+
+#### Outlook selectors:
+- Compose button: `button[aria-label="New mail"]` or `button[name="New mail"]`
+- To field: `input[aria-label="To"]` or `div[aria-label="To"]`
+- Subject field: `input[aria-label="Add a subject"]` or `input[placeholder*="subject"]`
+- Message body: `div[role="textbox"]` or `div[aria-label*="Message body"]`
+- Send button: `button[aria-label="Send"]` or `button[name="Send"]`
+
+**Sending flow:**
+
+1. `neuron_navigate` to:
+   - Gmail: `https://mail.google.com/mail/u/0/#inbox`
+   - Outlook: `https://outlook.live.com/mail/0/` or `https://outlook.office.com/mail/`
+
+2. Wait for inbox to load, then `neuron_find_elements` for the Compose button → `neuron_click`
+
+3. Wait for compose window to appear (use `neuron_monitor_action` to confirm)
+
+4. `neuron_detect_blocker` — check for:
+   - "You've reached your sending limit" warnings
+   - CAPTCHA challenges
+   - "This account has been suspended" messages
+   - Any error modals
+   If detected: STOP the entire session immediately, log it, report it.
+
+5. Fill the email:
+   - `neuron_type` recipient email in To field
+   - `neuron_type` subject line in Subject field
+   - `neuron_type` body in Message Body field
+   - **IMPORTANT:** After typing body, `neuron_screenshot` the composed email (for the log and approval)
+
+6. **Approval gate:**
+   - If `{{approval_mode}}` is "review-all": pause and present the email + screenshot for human approval before sending
+   - If "auto-after-3": pause for the first 3 emails, then auto-send the rest (the human has validated the quality)
+
+7. After approval: `neuron_find_elements` for Send button → `neuron_click`
+
+8. Use `neuron_monitor_action` to watch for:
+   - Success: compose window closes, email appears in Sent folder
+   - Failure: error message appears, email stuck in Drafts
+   - Spam warning: "This email might be spam" or similar
+
+9. If success: wait at least `{{min_delay_seconds}}` seconds before the next email
+
+10. Checkpoint session state with `neuron_session_checkpoint` after every 3 emails (so you can resume if interrupted)
+
+### Phase 5: Log
+
+After each email, append to `{{output_path}}/outreach-log.yaml`:
+
+```yaml
+- date: "{{now}}"
+  recipient_name: "<name>"
+  recipient_email: "<email>"
+  company: "<company>"
+  role: "<role>"
+  hook_used: "<what specific detail was referenced>"
+  hook_type: "<company_news|recent_post|role_problem|shared_connection|location|recent_hire>"
+  subject: "<subject line>"
+  body: "<full email body>"
+  email_length: <word count>
+  fit_score: <1-5>
+  status: sent
+  opened: pending
+  replied: pending
+  screenshot: "<path>"
+```
+
+Also append to `{{output_path}}/drafts.md` (for easy review later):
+
+```markdown
+## {{recipient_name}} ({{company}}) — {{date}}
+
+**Subject:** {{subject}}
+
+{{body}}
+
+---
+```
+
+At the end of the session, report:
+- Emails sent this session: N
+- Total emails sent today: M / {{daily_cap}}
+- Targets researched but skipped (low fit): K
+- Any delivery errors or warnings: [details]
+
+Save final session state with `neuron_session_save` (so you can resume next time).
+
+## Reflect
+
+After each session, log to memory:
+
+```yaml
+date: {{now}}
+outcome:
+  targets_provided: <count>
+  targets_researched: <count>
+  targets_qualified: <count scoring 3+>
+  emails_sent: <count>
+  emails_approved: <count> (if review mode)
+  emails_rejected_by_human: <count> (and why)
+  delivery_errors: <count>
+  spam_warnings: <count>
+  session_duration_minutes: <approximate>
+  hooks_used:
+    company_news: <count>
+    recent_post: <count>
+    role_problem: <count>
+    shared_connection: <count>
+    location: <count>
+    recent_hire: <count>
+  avg_fit_score: <number>
+  avg_email_length: <words>
+  avg_subject_length: <chars>
+  client_used: {{email_client}}
+```
+
+### Tracking opens and replies (manual)
+
+When you check email responses, update the corresponding entry in outreach-log.yaml:
+- `opened: yes` — email was opened (if you have read receipts or tracking)
+- `opened: no` — not opened after 7+ days
+- `replied: yes` — they replied (positive, neutral, or negative)
+- `replied: interested` — they showed interest in the product
+- `replied: not_interested` — polite decline
+- `replied: negative` — hostile or annoyed response (important to learn from)
+- `replied: no` — no reply after 7+ days
+
+## Evolve
+
+After 30+ emails with at least 12 response/open outcomes, review memory and update `learnings.md`:
+
+**Subject line strategy:**
+- Which subject line patterns get the highest open rates?
+- Which length (under 30 chars vs 30-40 vs 40-50) performs best?
+- Do company-name subjects outperform topic-based subjects?
+- Do questions in subject lines help or hurt?
+- Are there specific words that correlate with low open rates (spam triggers)?
+
+**Email body strategy:**
+- Which hook types get the most replies? (company_news vs recent_post vs role_problem vs shared_connection)
+- Does email length correlate with reply rate? (under 75 words vs 75-150 vs over 150)
+- Which opening patterns get replies vs get ignored?
+- Do emails with questions outperform emails with statements?
+- Are there specific phrases that correlate with negative responses? Remove them.
+
+**Audience targeting:**
+- Which fit scores actually convert to opens/replies? (is 3 worth it, or should you only email 4-5?)
+- Do certain roles respond more than others?
+- Does company size affect response rate?
+- Does location matter?
+
+**Timing:**
+- What time of day gets the best open rates? (check timestamps on opens if trackable)
+- What day of week gets the best reply rates?
+- Should the daily cap be higher or lower based on delivery success?
+
+**Email client performance:**
+- Gmail vs Outlook — any difference in delivery success?
+- Any client-specific errors or blockers?
+
+**Anti-patterns:**
+- Which emails got negative responses? What do they have in common?
+- Which emails were rejected by the human reviewer? Why? Update the hard rules.
+- Which emails triggered spam warnings? What language or structure caused it?
+
+**Rule updates from data:**
+After evolving, check if any learnings should become permanent rules:
+- Read current rules with `neuron_rules_get`
+- If a pattern consistently causes negative responses or low open rates → propose a `never` rule (e.g., "never use 'quick question' in subject line")
+- If the human rejected emails for the same reason 3+ times → propose a `global` rule
+- If certain subject line structures consistently outperform → update `learnings.md` defaults
+- Present proposed rule changes to the user and save with `neuron_rules_set` on approval
+
+Update the strategy based on data. If company-news hooks get 3x the reply rate, make that the default research focus. If emails under 75 words outperform longer ones, tighten the structure. If Tuesday mornings get the best open rates, note it.
+
+The metric is **reply rate per email sent**, not emails sent. A 20% reply rate on 50 emails beats a 2% reply rate on 500.

package/recipes/email-outreach/learnings.md

@@ -0,0 +1,94 @@
+# Learnings
+
+No emails sent yet. This file updates after 30+ emails with 12+ open/reply outcomes.
+
+## Email Defaults
+
+Starting assumptions from cold email best practices (to be validated):
+
+**Subject line rules (expected to work):**
+- Under 50 characters (ideally under 40) — higher mobile open rates
+- Reference something specific about them/their company — shows it's not mass email
+- Avoid spam trigger words: "free", "urgent", "limited time", "act now", "meeting", "quick question"
+- No ALL CAPS or excessive punctuation (!!!, ???)
+- First-name-only in subject line can work for warm contexts, but avoid for pure cold outreach
+- Personalization beyond just [Company Name] — reference recent news, role, location
+
+**What tends to work in the body:**
+- Open with a specific reference (their company's recent news, a post they wrote, a shared connection)
+- Get to the point within the first 2 sentences
+- Under 150 words (ideally under 100) — most cold emails are skimmed, not read
+- One clear, low-commitment ask
+- No "hope you don't mind the cold email" — shows insecurity
+- No "just checking in" or "just following up" in a cold email (nothing to follow up on yet)
+- Natural, conversational language — not corporate speak
+
+**What kills open rates:**
+- Generic subject lines ("Introduction", "Quick question", "Following up")
+- Subject lines that could apply to anyone
+- Sender name that's obviously a company/sales team (better to send from personal email)
+- Sending at odd hours (3am in recipient's timezone)
+
+**What kills reply rates:**
+- "I hope this email finds you well" / "I came across your company" (cold email clichés)
+- Feature lists or pricing in the first email
+- "Let's hop on a call" as the only CTA (too high commitment)
+- Attachments in a cold email (spam filter bait)
+- Long paragraphs with no breaks (wall of text)
+- Multiple asks in one email (confusing)
+- No clear CTA at all
+
+**Hook effectiveness (to be validated by data):**
+1. Shared connection mention → highest expected open + reply rate
+2. Company-specific recent news (funding, expansion, product launch) → high open rate, medium reply rate
+3. Reference to their content (blog post, LinkedIn post, tweet) → high reply rate if genuine
+4. Role-specific problem → baseline, works if the problem is real
+5. Generic "your background" → lowest, avoid entirely
+
+**Timing assumptions (to be tested):**
+- Best send times: Tuesday-Thursday, 9-11am or 2-4pm in recipient's timezone
+- Avoid: Mondays (inbox overload), Fridays after 3pm (checked out for weekend), weekends
+- For Nigerian audience: mornings (8-10am WAT) likely best, avoiding mid-day (1-3pm) and late evening
+
+## Anti-Patterns Registry
+
+Emails that should never be sent (will be expanded from negative response data):
+
+### Subject line anti-patterns:
+- "Quick question" (instant spam signal)
+- "Following up" (no prior contact)
+- "Re:" or "Fwd:" (deceptive if not a real reply/forward)
+- "[First Name], ..." (too familiar for cold outreach)
+- "Idea for you" (vague sales pitch)
+- Anything over 60 characters (gets cut off on mobile)
+
+### Body anti-patterns:
+- Opening with "I hope this email finds you well"
+- Opening with "I came across your company/profile"
+- Apologizing for cold emailing ("Sorry to bother you...")
+- Listing features without context ("We offer X, Y, Z...")
+- Using "just" excessively ("just wanted to...", "just checking...")
+- Multiple CTAs in one email
+- No personalization — email could be sent to anyone
+- Longer than one scroll on mobile (over 150 words)
+- No clear ask or purpose
+
+### Tone anti-patterns:
+- Overly formal ("Dear Sir/Madam", "To Whom It May Concern")
+- Overly casual for first contact ("Hey!", "What's up")
+- Desperate ("We'd love to earn your business", "It would mean a lot")
+- Pushy ("I'll follow up in 2 days", "I'll call you this week")
+- Corporate jargon ("synergy", "best-in-class", "leverage", "solutions")
+
+## Personalization Quality Ladder
+
+From worst to best (based on expected response rates):
+
+1. **Zero personalization** — "Dear [Company]" → 0-2% reply rate expected
+2. **Company name only** — "Hi [Name], I work with companies like [Company]..." → 2-5% reply rate expected
+3. **Role-based** — "Hi [Name], as [Role] at [Company], you probably deal with..." → 5-10% reply rate expected
+4. **Company + recent news** — "Saw [Company] just [specific event]..." → 10-15% reply rate expected
+5. **Reference their content** — "Read your post about [topic]..." → 15-25% reply rate expected
+6. **Shared connection** — "[Name] mentioned you when..." → 20-30% reply rate expected
+
+Target: every email at level 4 or higher.