arkaos 4.26.0 → 4.27.0

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

@@ -0,0 +1,144 @@
+# Gong
+
+Revenue intelligence platform that records, transcribes, and analyzes sales conversations (calls, video meetings, emails) to surface deal insights, coaching opportunities, and competitive intelligence.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API, Basic Auth or OAuth2 |
+| MCP | - | Not available |
+| CLI | - | Not available |
+| SDK | - | REST API only; community Python client via dltHub |
+
+## Authentication
+
+- **Type**: Basic Auth (Access Key + Secret) or OAuth2 for published apps
+- **Get key**: Admin-only — Settings > API at https://app.gong.io
+- **Base URL**: Tenant-specific — retrieve from your Gong API settings (typically `https://{tenant}.api.gong.io/v2/`)
+- **Docs**: https://help.gong.io/docs/what-the-gong-api-provides
+
+## API Endpoints
+
+Most Gong API endpoints use **POST** with JSON request bodies for filtering. Check the [official API docs](https://gong.app.gong.io/settings/api/documentation) for current endpoint availability.
+
+### Calls
+
+```bash
+# List calls (with date/user filters)
+POST /v2/calls/extensive
+
+# Get call transcripts (batch, by call IDs)
+POST /v2/calls/transcript
+```
+
+### Users & Stats
+
+```bash
+# List users
+GET /v2/users
+
+# Get activity stats (talk ratio, questions asked, longest monologue)
+POST /v2/stats/activity/day-by-day
+```
+
+### Engagement Flows
+
+```bash
+# List flows
+GET /v2/flows
+
+# Get flow analytics
+GET /v2/flows/{id}/analytics
+```
+
+## Key Data Points
+
+### Per Call
+- Full transcript with speaker labels and timestamps
+- Talk-to-listen ratio per participant
+- Topics discussed (auto-detected)
+- Questions asked (count and content)
+- Longest monologue duration
+- Next steps mentioned
+- Competitor mentions
+- Pricing discussions flagged
+
+### Per Deal
+- All associated calls and emails
+- Deal stage progression
+- Risk signals (gone dark, competitor mentioned, champion left)
+- Engagement score
+
+### Per Rep
+- Talk ratio trends
+- Question frequency
+- Topic coverage vs. playbook
+- Win rate correlation with behaviors
+
+## Common Agent Operations
+
+### Extract Competitive Intelligence from Calls
+
+1. Query calls mentioning competitor names
+2. Extract: objections raised, features compared, pricing discussed
+3. Synthesize into competitive battlecard updates
+4. Track competitor mention frequency over time
+
+### Mine Calls for Customer Research
+
+1. Pull transcripts from recent won/lost deals
+2. Extract: pain points, trigger events, decision criteria, language used
+3. Feed into persona building and messaging work
+4. Identify recurring objections for sales enablement
+
+### Revenue Attribution
+
+1. Pull call data alongside CRM deal data
+2. Map which content/pages were discussed in winning deals
+3. Identify which talking points correlate with closed-won
+4. Build content-to-revenue attribution reports
+
+### Rep Coaching Insights
+
+1. Compare top performer call patterns vs. team average
+2. Identify: talk ratio, question frequency, topic coverage gaps
+3. Surface specific call moments for coaching review
+4. Track improvement over time
+
+## Rate Limits
+
+- 3 API calls per second
+- 10,000 API calls per day
+- Pagination required for large result sets
+
+## When to Use
+
+- Mining sales call transcripts for customer research and VOC data
+- Extracting competitive intelligence from prospect conversations
+- Building revenue attribution models (content → deal influence)
+- Analyzing win/loss patterns across deal transcripts
+- Coaching sales reps based on conversation analytics
+- Identifying common objections and buying signals
+
+## Limitations
+
+- API access requires admin credentials
+- Transcript quality depends on call audio quality
+- Rate limits (10k/day) may constrain large-scale analysis
+- Pricing is enterprise-level (not publicly listed, typically $100+/user/month)
+- Requires team adoption — records calls via integrations, but also supports uploading calls from non-integrated telephony systems
+
+## Relevant Skills
+
+- customer-research
+- sales-enablement
+- competitors
+- revops
+- cold-email
+
+## Sources
+
+- [Gong API overview](https://help.gong.io/docs/what-the-gong-api-provides)
+- [Gong API documentation](https://gong.app.gong.io/settings/api/documentation)
+- [Call upload support](https://help.gong.io/docs/uploading-calls-from-a-non-integrated-telephony-system)

package/departments/marketing/tools/integrations/google-ads.md

@@ -0,0 +1,159 @@
+# Google Ads
+
+Pay-per-click advertising platform for search, display, and video campaigns.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Google Ads API for campaign management |
+| MCP | ✓ | Available via Google Ads MCP server |
+| CLI | - | Use gcloud or API scripts |
+| SDK | ✓ | Client libraries for multiple languages |
+
+## Authentication
+
+- **Type**: OAuth 2.0
+- **Scopes**: `https://www.googleapis.com/auth/adwords`
+- **Setup**: Create credentials in Google Cloud Console, link to Google Ads account
+- **Headers**: `developer-token`, `login-customer-id` (for MCC)
+
+## Common Agent Operations
+
+### Get account info
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT customer.id, customer.descriptive_name FROM customer"
+}
+```
+
+### List campaigns
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT campaign.id, campaign.name, campaign.status, campaign_budget.amount_micros FROM campaign ORDER BY campaign.id"
+}
+```
+
+### Get campaign performance
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS"
+}
+```
+
+### Get ad group performance
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT ad_group.name, metrics.impressions, metrics.clicks, metrics.conversions FROM ad_group WHERE segments.date DURING LAST_7_DAYS"
+}
+```
+
+### Get keyword performance
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/googleAds:searchStream
+
+{
+  "query": "SELECT ad_group_criterion.keyword.text, metrics.impressions, metrics.clicks, metrics.average_cpc FROM keyword_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 50"
+}
+```
+
+### Pause campaign
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/campaigns:mutate
+
+{
+  "operations": [{
+    "update": {
+      "resourceName": "customers/{customer_id}/campaigns/{campaign_id}",
+      "status": "PAUSED"
+    },
+    "updateMask": "status"
+  }]
+}
+```
+
+### Update budget
+
+```bash
+POST https://googleads.googleapis.com/v14/customers/{customer_id}/campaignBudgets:mutate
+
+{
+  "operations": [{
+    "update": {
+      "resourceName": "customers/{customer_id}/campaignBudgets/{budget_id}",
+      "amountMicros": "50000000"
+    },
+    "updateMask": "amountMicros"
+  }]
+}
+```
+
+## Key Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `metrics.impressions` | Ad impressions |
+| `metrics.clicks` | Clicks |
+| `metrics.cost_micros` | Cost in micros (divide by 1M) |
+| `metrics.conversions` | Conversions |
+| `metrics.conversions_value` | Conversion value |
+| `metrics.average_cpc` | Average cost per click |
+| `metrics.ctr` | Click-through rate |
+| `metrics.conversion_rate` | Conversion rate |
+
+## Campaign Types
+
+- `SEARCH` - Search network text ads
+- `DISPLAY` - Display network
+- `SHOPPING` - Product shopping ads
+- `VIDEO` - YouTube video ads
+- `PERFORMANCE_MAX` - AI-optimized across channels
+- `DEMAND_GEN` - Discovery/Demand Gen
+
+## GAQL (Google Ads Query Language)
+
+```sql
+SELECT
+  campaign.name,
+  metrics.clicks,
+  metrics.conversions
+FROM campaign
+WHERE
+  campaign.status = 'ENABLED'
+  AND segments.date DURING LAST_30_DAYS
+ORDER BY metrics.conversions DESC
+LIMIT 10
+```
+
+## When to Use
+
+- Managing search advertising campaigns
+- Analyzing campaign performance
+- Adjusting budgets and bids
+- Keyword research and management
+- Conversion tracking analysis
+
+## Rate Limits
+
+- 15,000 operations per day (basic)
+- Higher limits with developer token levels
+
+## Relevant Skills
+
+- ads
+- analytics
+- cro

package/departments/marketing/tools/integrations/google-search-console.md

@@ -0,0 +1,147 @@
+# Google Search Console
+
+Free tool for monitoring website search performance and indexing.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Search Analytics API, URL Inspection API |
+| MCP | - | Not available |
+| CLI | - | Use gcloud or API scripts |
+| SDK | ✓ | Google API client libraries |
+
+## Authentication
+
+- **Type**: OAuth 2.0 or Service Account
+- **Scopes**: `https://www.googleapis.com/auth/webmasters.readonly`
+- **Setup**: Create credentials in Google Cloud Console
+
+## Common Agent Operations
+
+### Get search analytics
+
+```bash
+POST https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/searchAnalytics/query
+
+{
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "dimensions": ["query"],
+  "rowLimit": 100
+}
+```
+
+### Get performance by page
+
+```bash
+POST https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/searchAnalytics/query
+
+{
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "dimensions": ["page"],
+  "rowLimit": 50
+}
+```
+
+### Get performance by country
+
+```bash
+POST https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/searchAnalytics/query
+
+{
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "dimensions": ["country", "query"],
+  "rowLimit": 100
+}
+```
+
+### Inspect URL
+
+```bash
+POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
+
+{
+  "inspectionUrl": "https://example.com/page",
+  "siteUrl": "https://example.com/"
+}
+```
+
+### List sitemaps
+
+```bash
+GET https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/sitemaps
+
+Authorization: Bearer {access_token}
+```
+
+### Submit sitemap
+
+```bash
+PUT https://searchconsole.googleapis.com/webmasters/v3/sites/{site_url}/sitemaps/{sitemap_url}
+
+Authorization: Bearer {access_token}
+```
+
+### Request indexing
+
+```bash
+POST https://indexing.googleapis.com/v3/urlNotifications:publish
+
+{
+  "url": "https://example.com/new-page",
+  "type": "URL_UPDATED"
+}
+```
+
+## Dimensions
+
+- `query` - Search query
+- `page` - Page URL
+- `country` - Country code
+- `device` - Device type (MOBILE, DESKTOP, TABLET)
+- `date` - Date
+- `searchAppearance` - Search result type
+
+## Metrics
+
+- `clicks` - Clicks from search
+- `impressions` - Search impressions
+- `ctr` - Click-through rate
+- `position` - Average position
+
+## Filters
+
+```json
+{
+  "dimensionFilterGroups": [{
+    "filters": [{
+      "dimension": "query",
+      "operator": "contains",
+      "expression": "keyword"
+    }]
+  }]
+}
+```
+
+## When to Use
+
+- Analyzing search performance
+- Finding keyword opportunities
+- Monitoring indexing status
+- Submitting new pages for indexing
+- Identifying crawl issues
+- Tracking position changes
+
+## Rate Limits
+
+- 200 queries per minute
+- 1,200 requests per minute
+
+## Relevant Skills
+
+- seo-audit
+- programmatic-seo
+- analytics

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

@@ -0,0 +1,126 @@
+# HeyGen
+
+AI avatar video generation platform. Create talking-head videos from text scripts with realistic lip-sync, expressions, and gestures.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | Yes | REST API v2 for video generation, avatars, templates |
+| MCP | Yes | Official hosted MCP server — no local install needed |
+| CLI | - | - |
+| SDK | Yes | Node.js SDK available |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `X-Api-Key: {api_key}`
+- **Get key**: Settings > API in HeyGen dashboard
+
+## MCP Server Setup
+
+HeyGen provides a hosted remote MCP server. No local installation required.
+
+### Claude Code / Claude Desktop
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "heygen": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.heygen.com/mcp"]
+    }
+  }
+}
+```
+
+On first use, authenticates via browser OAuth. The MCP server exposes tools for:
+- Creating videos from scripts
+- Listing and selecting avatars
+- Managing templates
+- Checking video status
+
+## API Quick Start
+
+### Create a Video
+
+```bash
+curl -X POST https://api.heygen.com/v2/video/generate \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "video_inputs": [{
+      "character": {
+        "type": "avatar",
+        "avatar_id": "AVATAR_ID",
+        "avatar_style": "normal"
+      },
+      "voice": {
+        "type": "text",
+        "input_text": "Your script goes here.",
+        "voice_id": "VOICE_ID"
+      }
+    }],
+    "dimension": {
+      "width": 1920,
+      "height": 1080
+    }
+  }'
+```
+
+### List Avatars
+
+```bash
+curl https://api.heygen.com/v2/avatars \
+  -H "X-Api-Key: YOUR_API_KEY"
+```
+
+### Check Video Status
+
+```bash
+curl https://api.heygen.com/v1/video_status.get?video_id=VIDEO_ID \
+  -H "X-Api-Key: YOUR_API_KEY"
+```
+
+## Common Marketing Use Cases
+
+| Use Case | Approach |
+|----------|----------|
+| Product explainer | Script from features → avatar presents |
+| Feature announcement | Template with avatar + screen recording |
+| Multilingual content | Same script, different language/voice |
+| Personalized outreach | Dynamic variables (name, company) in script |
+| Weekly updates | Recurring template, swap script text |
+
+## Custom Avatars
+
+Upload a 2-5 minute video of yourself speaking to create a digital twin:
+- Looks and sounds like you
+- Generates unlimited videos from text scripts
+- Available on Creator plan and above
+
+## Pricing
+
+| Plan | Videos/mo | Max Duration |
+|------|-----------|-------------|
+| Free | 3 | 3 min |
+| Creator | Unlimited | 5 min |
+| Business | Unlimited | 20 min |
+| Enterprise | Unlimited | Custom |
+
+Check [heygen.com/pricing](https://www.heygen.com/pricing) for current prices — they change frequently.
+
+## Rate Limits
+
+- Free: 3 videos/month
+- Paid: Based on plan tier, concurrent generation limits apply
+- API rate limits: Check response headers for `X-RateLimit-*`
+
+## Relevant Skills
+
+- video
+- social
+- ad-creative
+- sales-enablement

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

@@ -0,0 +1,147 @@
+# Hotjar
+
+Behavior analytics platform with heatmaps, session recordings, and surveys for understanding user experience.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Surveys, Responses, Sites, Heatmaps, Recordings |
+| MCP | - | Not available |
+| CLI | ✓ | [hotjar.js](../clis/hotjar.js) |
+| SDK | ✓ | JavaScript tracking snippet, Identify API, Events API |
+
+## Authentication
+
+- **Type**: OAuth 2.0 Client Credentials
+- **Token endpoint**: `POST https://api.hotjar.io/v1/oauth/token`
+- **Header**: `Authorization: Bearer {access_token}`
+- **Get credentials**: Hotjar Dashboard > Integrations > API
+- **Token expiry**: 3600 seconds (1 hour)
+
+### Token Request
+
+```bash
+POST https://api.hotjar.io/v1/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
+```
+
+### Token Response
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+## Common Agent Operations
+
+### List Sites
+
+```bash
+GET https://api.hotjar.io/v1/sites
+
+Authorization: Bearer {access_token}
+```
+
+### List Surveys
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/surveys
+
+Authorization: Bearer {access_token}
+```
+
+### Get Survey Responses
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/surveys/{survey_id}/responses?limit=100
+
+Authorization: Bearer {access_token}
+```
+
+Supports cursor-based pagination with `cursor` and `limit` parameters.
+
+### List Heatmaps
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/heatmaps
+
+Authorization: Bearer {access_token}
+```
+
+### List Recordings
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/recordings
+
+Authorization: Bearer {access_token}
+```
+
+### List Forms
+
+```bash
+GET https://api.hotjar.io/v1/sites/{site_id}/forms
+
+Authorization: Bearer {access_token}
+```
+
+## Key Metrics
+
+### Survey Response Data
+- `response_id` - Unique response identifier
+- `answers` - Array of question/answer pairs
+- `created_at` - Response timestamp
+- `device_type` - Desktop, mobile, tablet
+
+### Heatmap Data
+- `url` - Page URL
+- `click_count` - Total clicks tracked
+- `visitors` - Unique visitors
+- `created_at` - Heatmap creation date
+
+### Recording Data
+- `recording_id` - Unique recording ID
+- `duration` - Session duration
+- `pages_visited` - Pages in session
+- `device` - Device information
+
+## Parameters
+
+### Survey Responses
+- `limit` - Results per page (default: 100)
+- `cursor` - Pagination cursor from previous response
+- `sort` - Sort order (default: created_at desc)
+
+### Recordings
+- `limit` - Results per page
+- `cursor` - Pagination cursor
+- `date_from` - Start date filter
+- `date_to` - End date filter
+
+## When to Use
+
+- Analyzing user behavior patterns on landing pages
+- Collecting qualitative feedback via on-site surveys
+- Identifying UX issues through session recordings
+- Understanding scroll depth and engagement via heatmaps
+- Validating CRO hypotheses with user behavior data
+- Form abandonment analysis
+
+## Rate Limits
+
+- 3000 requests/minute (50 per second)
+- Rate limited by source IP address
+- Cursor-based pagination for large result sets
+
+## Relevant Skills
+
+- cro
+- ab-testing
+- analytics
+- ux-audit
+- landing-page