arkaos 4.26.0 → 4.28.0

package/departments/marketing/tools/integrations/firehose.md

@@ -0,0 +1,159 @@
+# Firehose
+
+Real-time web data streaming API that monitors web pages and delivers matching content instantly via server-sent events (SSE). Built for competitive intelligence, brand monitoring, and news tracking without polling.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | RESTful endpoints for managing rules + SSE for streaming |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | - | Native AI agent skill available |
+
+## Authentication
+
+- **Type**: API Key
+- **Currently**: Free beta — no credit card required
+- **Get access**: Sign up at firehose.com
+
+## Core Concepts
+
+**Rules** — Filters that define what content to match. Uses Lucene query syntax.
+
+**Stream** — A server-sent event (SSE) connection that delivers matching content in real-time as it's published on the web.
+
+Instead of polling an endpoint on a schedule, you define rules once and receive a continuous stream of matches as they happen.
+
+## Query Syntax (Lucene)
+
+```
+# Exact phrase
+"your brand name"
+
+# Field-specific
+title:tesla
+domain:reuters.com
+domain:techcrunch.com
+
+# Boolean operators
+"Series A" AND (SaaS OR software)
+competitor OR "competitor name" NOT "your company"
+
+# Wildcard
+market* AND funding
+
+# Language filter
+language:en
+
+# Date range
+publish_time:[2026-01-01 TO 2026-03-18]
+
+# ML-classified categories
+category:finance
+category:technology
+```
+
+## Common Agent Operations
+
+### Create a monitoring rule
+
+```bash
+POST https://api.firehose.com/rules
+
+{
+  "query": "\"your brand name\" OR \"your product name\"",
+  "label": "brand-mentions"
+}
+```
+
+### List active rules
+
+```bash
+GET https://api.firehose.com/rules
+```
+
+### Delete a rule
+
+```bash
+DELETE https://api.firehose.com/rules/{rule_id}
+```
+
+### Connect to the stream
+
+```bash
+GET https://api.firehose.com/stream
+Authorization: Bearer {api_key}
+
+# Returns server-sent events:
+# data: {"url": "...", "title": "...", "publish_time": "...", "matched_rule": "..."}
+```
+
+### Example: Node.js stream consumer
+
+```javascript
+import EventSource from 'eventsource';
+
+const stream = new EventSource('https://api.firehose.com/stream', {
+  headers: { Authorization: `Bearer ${process.env.FIREHOSE_API_KEY}` }
+});
+
+stream.onmessage = (event) => {
+  const item = JSON.parse(event.data);
+  console.log(`[${item.matched_rule}] ${item.title} — ${item.url}`);
+};
+```
+
+## Use Cases for Marketing
+
+### Competitive intelligence
+Monitor competitors' press coverage, product announcements, and funding news in real-time.
+
+```
+query: "CompetitorName" AND (launch OR funding OR "product update" OR partnership)
+```
+
+### Brand monitoring
+Track mentions of your brand across news and web content.
+
+```
+query: "YourBrand" OR "YourProductName" NOT site:yourdomain.com
+```
+
+### Category / market news
+Stay current on your market without manually checking sources.
+
+```
+query: category:technology AND ("no-code" OR "low-code") AND funding
+domain:techcrunch.com OR domain:venturebeat.com
+```
+
+### Lead trigger monitoring
+Track signals that indicate a prospect is ready to buy (hiring, funding, tool mentions).
+
+```
+query: ("hiring" OR "we're growing") AND "RevOps" AND (HubSpot OR Salesforce)
+```
+
+### PR and link building
+Get alerted when publications cover topics in your space, enabling timely outreach.
+
+```
+query: "best [category] tools" OR "top [category] software" AND publish_time:[now-7d TO now]
+```
+
+## When to Use
+
+- Real-time competitive intelligence (faster than Google Alerts)
+- Brand mention monitoring across news and web
+- Market signal tracking for sales prospecting
+- Automated content curation pipelines
+- Trigger-based workflows (new mention → Slack alert, CRM update, etc.)
+
+## Relevant Skills
+
+- competitors
+- customer-research
+- content-strategy
+- cold-email
+- marketing-ideas

package/departments/marketing/tools/integrations/g2.md

@@ -0,0 +1,179 @@
+# G2
+
+Software review and research platform for B2B buyers. Access reviews, product data, competitor comparisons, and buyer intent signals.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Reviews, Products, Reports, Categories, Tracking |
+| MCP | - | Not available |
+| CLI | ✓ | [g2.js](../clis/g2.js) |
+| SDK | - | REST API with JSON:API format |
+
+## Authentication
+
+- **Type**: API Token
+- **Header**: `Authorization: Token token={YOUR_API_TOKEN}`
+- **Content-Type**: `application/vnd.api+json` (JSON:API)
+- **Get token**: G2 Admin Portal > Integrations > API Tokens
+- **Docs**: https://data.g2.com/api/docs
+
+## Common Agent Operations
+
+### List reviews (survey responses)
+
+```bash
+GET https://data.g2.com/api/v1/survey-responses?page[size]=25&page[number]=1
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### Get a specific review
+
+```bash
+GET https://data.g2.com/api/v1/survey-responses/{id}
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### Filter reviews by product
+
+```bash
+GET https://data.g2.com/api/v1/survey-responses?filter[product_id]={product_id}&page[size]=25
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### List products
+
+```bash
+GET https://data.g2.com/api/v1/products?page[size]=25&page[number]=1
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### Get a specific product
+
+```bash
+GET https://data.g2.com/api/v1/products/{id}
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### List reports
+
+```bash
+GET https://data.g2.com/api/v1/reports?page[size]=25&page[number]=1
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### List categories
+
+```bash
+GET https://data.g2.com/api/v1/categories?page[size]=25&page[number]=1
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### Get competitor comparisons
+
+```bash
+GET https://data.g2.com/api/v1/competitor-comparisons?filter[product_id]={product_id}&page[size]=25
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+### Get tracking events (buyer intent)
+
+```bash
+GET https://data.g2.com/api/v1/tracking-events?filter[start_date]=2025-01-01&filter[end_date]=2025-12-31
+
+Headers:
+  Authorization: Token token={API_TOKEN}
+  Content-Type: application/vnd.api+json
+```
+
+## API Pattern
+
+G2 follows the JSON:API specification (https://jsonapi.org/):
+- Responses use `data`, `attributes`, `relationships`, `meta` structure
+- Pagination: `page[number]` and `page[size]` query parameters
+- Filtering: `filter[field]=value` query parameters
+- Reviews returned newest-first by default (10 per page default)
+
+## Key Metrics
+
+### Review Metrics
+- `star_rating` - Overall star rating
+- `title` - Review title
+- `comment_answers` - Structured review responses (likes, dislikes, recommendations)
+- `submitted_at` - Review submission date
+- `is_public` - Whether the review is publicly visible
+
+### Product Metrics
+- `name` - Product name
+- `slug` - URL slug on G2
+- `avg_rating` - Average star rating
+- `total_reviews` - Total review count
+- `category` - G2 category placement
+
+### Buyer Intent (Tracking)
+- `company_name` - Visiting company name
+- `page_visited` - G2 page URL visited
+- `visited_at` - Visit timestamp
+- `activity_type` - Type of buyer activity
+
+## Parameters
+
+### Pagination
+- `page[number]` - Page number (default: 1)
+- `page[size]` - Items per page (default: 10, max: 100)
+
+### Review Filters
+- `filter[product_id]` - Filter by product ID
+- `filter[state]` - Filter by review state
+
+### Tracking Filters
+- `filter[start_date]` - Start date (YYYY-MM-DD)
+- `filter[end_date]` - End date (YYYY-MM-DD)
+
+## When to Use
+
+- Monitoring and analyzing software product reviews
+- Tracking buyer intent signals from G2 visitors
+- Pulling competitor comparison data for positioning
+- Feeding review data into CRM or marketing automation
+- Building social proof content from G2 reviews
+- Tracking G2 category rankings and report placements
+
+## Rate Limits
+
+- 10,000 requests per hour per API token
+- Implement exponential backoff on 429 responses
+- Cache results where possible to reduce API calls
+
+## Relevant Skills
+
+- competitors
+- social-proof
+- reputation-management
+- customer-feedback
+- review-generation

package/departments/marketing/tools/integrations/ga4.md

@@ -0,0 +1,126 @@
+# Google Analytics 4 (GA4)
+
+Web analytics platform for tracking user behavior, conversions, and marketing performance.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Data API for reports, Admin API for configuration |
+| MCP | ✓ | Available via Google Analytics MCP server |
+| CLI | - | Use gcloud for some operations |
+| SDK | ✓ | gtag.js, Google Analytics SDK for mobile |
+
+## Authentication
+
+- **Type**: OAuth 2.0 or Service Account
+- **Scopes**: `https://www.googleapis.com/auth/analytics.readonly` (read), `https://www.googleapis.com/auth/analytics.edit` (write)
+- **Setup**: Create credentials in Google Cloud Console
+
+## Common Agent Operations
+
+### Run a report (Data API)
+
+```bash
+POST https://analyticsdata.googleapis.com/v1beta/properties/{property_id}:runReport
+
+{
+  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
+  "dimensions": [{"name": "sessionSource"}],
+  "metrics": [{"name": "sessions"}, {"name": "conversions"}]
+}
+```
+
+### Get real-time data
+
+```bash
+POST https://analyticsdata.googleapis.com/v1beta/properties/{property_id}:runRealtimeReport
+
+{
+  "dimensions": [{"name": "country"}],
+  "metrics": [{"name": "activeUsers"}]
+}
+```
+
+### List conversion events
+
+```bash
+GET https://analyticsadmin.googleapis.com/v1beta/properties/{property_id}/conversionEvents
+```
+
+### Create a conversion event
+
+```bash
+POST https://analyticsadmin.googleapis.com/v1beta/properties/{property_id}/conversionEvents
+
+{
+  "eventName": "purchase"
+}
+```
+
+## Client-Side Tracking
+
+### Send custom event (gtag.js)
+
+```javascript
+gtag('event', 'signup_completed', {
+  'method': 'email',
+  'plan': 'free'
+});
+```
+
+### Send event via Measurement Protocol
+
+```bash
+POST https://www.google-analytics.com/mp/collect?measurement_id={measurement_id}&api_secret={api_secret}
+
+{
+  "client_id": "client_123",
+  "events": [{
+    "name": "purchase",
+    "params": {
+      "value": 99.99,
+      "currency": "USD"
+    }
+  }]
+}
+```
+
+## Key Dimensions & Metrics
+
+### Common Dimensions
+- `sessionSource` - Traffic source
+- `sessionMedium` - Traffic medium
+- `sessionCampaignName` - Campaign name
+- `landingPage` - Entry page
+- `deviceCategory` - Device type
+- `country` - User country
+
+### Common Metrics
+- `sessions` - Total sessions
+- `activeUsers` - Active users
+- `newUsers` - New users
+- `conversions` - Conversion events
+- `engagementRate` - Engaged sessions rate
+- `averageSessionDuration` - Session duration
+
+## When to Use
+
+- Tracking website traffic and user behavior
+- Measuring marketing campaign performance
+- Setting up conversion tracking
+- Analyzing user journeys and funnels
+- Attribution modeling
+
+## Rate Limits
+
+- Data API: 10 requests per second per property
+- Admin API: Varies by endpoint
+- Measurement Protocol: 1M hits/day for free tier
+
+## Relevant Skills
+
+- analytics
+- ab-testing
+- seo-audit
+- cro

package/departments/marketing/tools/integrations/github.md

@@ -0,0 +1,182 @@
+# GitHub
+
+GitHub REST API for prospecting use cases: listing users who star, fork, or watch a repo as a high-quality developer-intent signal.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Public REST API, well-documented |
+| MCP | - | Several community MCP servers exist; not bundled here |
+| CLI | ✓ | [github-prospects.js](../clis/github-prospects.js) — stargazers, forks, watchers, user, rate-limit |
+| SDK | ✓ | Official Octokit (JS, Python, Ruby, .NET, Go) |
+
+## Authentication
+
+- **Type**: Personal Access Token (PAT) or Fine-Grained PAT
+- **Header**: `Authorization: Bearer {token}`
+- **Get token**: https://github.com/settings/tokens
+- **Scopes for prospecting**:
+  - Public data (stargazers, forks, public profiles): **no scope required** with a token, or unauthenticated
+  - Public repo metadata: `public_repo` scope
+- **Env var**: `GITHUB_TOKEN`
+
+### Rate limits
+
+| Auth | Limit | When you hit it |
+|------|-------|-----------------|
+| Unauthenticated | 60 req/hr | Fine for one-off small lookups |
+| Authenticated PAT | 5,000 req/hr | Sufficient for a 10K-star repo pull in one hour |
+| GitHub App | 5,000–15,000 req/hr | For high-volume use |
+
+A 1,000-star repo with full enrichment (1 list call + 1 profile call per user) = ~1,011 requests. Always set a token.
+
+## Common Agent Operations
+
+### List stargazers (users who starred a repo)
+
+```bash
+GET https://api.github.com/repos/{owner}/{repo}/stargazers?per_page=100&page=1
+
+Accept: application/vnd.github+json
+X-GitHub-Api-Version: 2022-11-28
+Authorization: Bearer {token}
+```
+
+Pagination via `Link` header (`rel="next"`, `rel="last"`). Default 30 per page, max 100.
+
+Returns array of user objects with `login`, `id`, `html_url`, `type` (User or Organization). Full profile fields (email, company, blog, bio, location) require a follow-up call per user.
+
+### List forks (gives fork owner profiles)
+
+```bash
+GET https://api.github.com/repos/{owner}/{repo}/forks?per_page=100&page=1
+```
+
+Each fork object includes the `owner` (the user/org that forked). Forks are a stronger signal than stars — they imply intent to modify, not just bookmark.
+
+### List watchers (subscribers)
+
+```bash
+GET https://api.github.com/repos/{owner}/{repo}/subscribers?per_page=100&page=1
+```
+
+GitHub's "watch" → API's "subscribers". Smaller pool than stargazers but signals deeper engagement.
+
+### Get user profile (enrichment)
+
+```bash
+GET https://api.github.com/users/{username}
+```
+
+Returns: `name`, `company`, `blog`, `email` (if public), `bio`, `twitter_username`, `location`, `public_repos`, `followers`, `created_at`, `hireable`.
+
+**Key fields for prospecting**:
+- `email`: only ~5–20% of users publish this. Always nullable.
+- `company`: many users include `@org` syntax — strip the `@` for plain company name.
+- `blog`: often a personal website where contact info is published.
+- `twitter_username` / `bio`: useful for cross-channel research.
+
+### Check rate limit
+
+```bash
+GET https://api.github.com/rate_limit
+```
+
+## Prospecting Workflows
+
+### Workflow 1 — Stargazers of a competitor or adjacent tool
+
+```bash
+# 100 stargazers, enrich each one, only keep those with email or company set
+node tools/clis/github-prospects.js stargazers vercel/next.js \
+  --limit 100 --enrich --format csv > nextjs-stars.csv
+```
+
+Filter the CSV in your spreadsheet by `company` set OR `email` set OR `blog` set. Hand off to Apollo/Clay/Hunter to enrich the rest with email-by-name+company.
+
+### Workflow 2 — Forks of your own repo (warm intent)
+
+People who fork your repo have already shown direct interest. High-conversion outreach prospects.
+
+```bash
+node tools/clis/github-prospects.js forks yourorg/yourrepo \
+  --enrich --with-email --format csv > my-fork-prospects.csv
+```
+
+### Workflow 3 — Watchers of a category-defining repo
+
+Watchers are smaller in number but higher in intent — they're tracking changes, not just bookmarking.
+
+```bash
+node tools/clis/github-prospects.js watchers tldraw/tldraw \
+  --enrich --with-company --format csv > tldraw-watchers.csv
+```
+
+## CLI Reference
+
+```bash
+# Stargazers
+node tools/clis/github-prospects.js stargazers <owner/repo> \
+  [--limit N] [--enrich] [--with-email] [--with-company] \
+  [--with-blog] [--type User|Organization] [--format csv|json]
+
+# Forks
+node tools/clis/github-prospects.js forks <owner/repo> [...same flags]
+
+# Watchers (subscribers in API terms)
+node tools/clis/github-prospects.js watchers <owner/repo> [...same flags]
+
+# Single user lookup
+node tools/clis/github-prospects.js user <username>
+
+# Check rate limit
+node tools/clis/github-prospects.js rate-limit
+```
+
+**Flags**:
+- `--limit N`: cap total results pulled from the list endpoint
+- `--target N`: when filtering with `--with-*`, stop enriching as soon as N users match (saves quota on restrictive filters)
+- `--enrich`: fetch full profile per user (1 extra request each)
+- `--with-email` / `--with-company` / `--with-blog`: filter to users with these fields set (implies `--enrich`)
+- `--type User|Organization`: filter by account type
+- `--format csv`: output prospecting-ready CSV; default is JSON
+- `--dry-run`: preview the request without sending
+
+## When to Use
+
+- **SaaS prospecting** (primary use case): stargazers of a competitor, complement, or category-defining repo as in-market developer signal
+- **Open-source product marketing**: see who's forking or watching your own repo for warm outreach
+- **Developer-tool ICP discovery**: stargazers of `next.js`, `prisma`, `tailwindcss`, etc., signal a Next.js / Prisma / Tailwind developer
+- **Trigger event monitoring**: a recent fork of a competitor's repo often signals dissatisfaction or active evaluation
+
+## When NOT to Use
+
+- **Email is your only signal you need** — GitHub yields email for only ~5–20% of users. Pair with Apollo, Clay, or Hunter for enrichment from name + company.
+- **Hyper-broad lists** — a repo with 100K+ stars is mostly noise. Smaller, more specific repos (5K–25K stars) give higher-signal lists.
+- **You don't have a way to handle high-volume LinkedIn lookup downstream** — most enrichment from GitHub username goes through LinkedIn Sales Nav manually.
+
+## Compliance Notes
+
+- **GitHub data is public** — no ToS issue with reading the API. The ToS prohibits abusive scraping (bypassing rate limits, mass account creation), not legitimate API usage.
+- **Personal emails published on GitHub** — users opt in to publishing their email. Treat as business contact when paired with company/blog signals; respect GDPR/CAN-SPAM for the downstream send.
+- **Source URL lineage** — for every prospect added from GitHub, capture `html_url` (their profile URL) and the source repo. Required for GDPR DSAR defense.
+- **Cool-down between large pulls** — even at 5,000 req/hr, don't burst-fingerprint. Pagination is naturally paced; respect `X-RateLimit-Remaining` headers.
+
+## Pairing with Other Tools
+
+Typical GitHub prospecting pipeline:
+
+1. Pull stargazers/forkers via this CLI
+2. Filter to users with company set (or other signal)
+3. **Enrich missing emails** via Apollo / Clay / Hunter (lookup by name + company domain)
+4. **Validate emails** via Truelist before adding to outreach list
+5. **Hand off** to cold-email skill for outreach
+
+See `skills/prospecting/references/saas-prospecting.md` and `data-sources.md` for the full prospecting framework.
+
+## Relevant Skills
+
+- prospecting (primary use case)
+- cold-email (downstream outreach)
+- competitor-profiling (deeper account-level research on individual stargazers worth pursuing)