@synap-core/workspace-templates 0.11.0 → 0.23.0

package/capabilities/agency-skills.capability.json

@@ -0,0 +1,157 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "agency-skills",
+    "name": "Agency Skills — Outreach & Client Work",
+    "description": "Writing skills for agency work: draft outreach and replies, qualify replies, summarize threads, pull action items and build client briefs. Includes Lead Outreach and Client Onboarding playbooks. Outbound messages always wait for your approval.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "agency-skills",
+    "name": "Agency — AI Know-How",
+    "description": "The agency's AI know-how bundle: six instruction skills (prompt/doc skills injected into the agent's turn — no sandboxed code, no connector calls) that teach the agent how to draft outreach, draft replies, qualify replies, summarize threads, extract action items, and assemble a client brief. Plus two process playbooks (lead-outreach, client-onboarding) that sequence those skills + the connector tools into the §2 agency flows. Instruction skills are pure know-how: when the agent runs in a client's thread it gets that client as the subject (contextEntityId), and these skills shape WHAT it writes. Their `requires` lists name the connector tools the skill's output feeds into (e.g. draft-outreach feeds the LinkedIn send) — the tools come from the sibling capabilities (unipile-linkedin, nango-google, telegram-bridge); apply those to wire the links. Outbound actions remain proposal-gated and reversible.",
+    "params": [],
+    "vault": [],
+    "tools": [],
+    "skills": [
+      {
+        "name": "draft-outreach",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Write a personalized, non-salesy first outreach message to a lead, grounded in their LinkedIn profile and our agency's pitch. Output feeds the LinkedIn send (Unipile), which stays proposal-gated.",
+        "requires": [
+          "unipile_linkedin"
+        ],
+        "code": "# Draft Outreach\n\nYou are writing the FIRST message to a lead we just connected with on LinkedIn. The goal is to start a genuine conversation, not to sell. A good first message earns a reply; a salesy one gets ignored.\n\n## Inputs you are given\n- The lead's LinkedIn profile (name, headline, current company, role, recent activity, location).\n- Our agency's pitch / positioning (what we do, who we help, the outcome we deliver).\n- Any prior context about why this lead was sourced (the list they came from, the angle).\n\n## How to write it\n1. **Open with them, not us.** Reference something specific and true from their profile — their role, a company milestone, a post they shared, a shared interest. Generic openers (\"I came across your profile\") are a tell; be specific enough that it could only have been written for this person.\n2. **One sentence of relevance.** Connect what they do to what we do, lightly. Show you understand their world.\n3. **A low-friction invitation.** Ask one easy, open question OR offer something small and useful (an idea, a resource). Never pitch the engagement in message one. No calendar links, no \"hop on a call\" yet.\n4. **Be brief.** 3–5 sentences. LinkedIn rewards short. If it reads like a template, rewrite it.\n5. **Match their register.** Mirror the lead's seniority and tone — peer-to-peer for founders/execs, warm and concrete for operators.\n\n## Hard rules\n- No flattery that isn't earned, no buzzwords (\"synergy\", \"circle back\", \"game-changer\").\n- No more than one ask. No links unless they're genuinely helpful.\n- Use the lead's first name once, naturally.\n- Never invent facts about the lead — only use what's in the profile.\n\n## Output\nReturn ONLY the message text, ready to review and send. No subject line (LinkedIn DMs have none), no preamble, no explanation. The operator reviews and edits before it sends."
+      },
+      {
+        "name": "draft-reply",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Draft a proposed reply to a client's mail or Telegram thread, in the client's voice and with full client context. Output feeds the Gmail/Telegram send, which stays proposal-gated and operator-reviewed.",
+        "requires": [
+          "gmail",
+          "telegram"
+        ],
+        "code": "# Draft Reply\n\nYou are drafting a reply on behalf of the operator, inside a specific client's communication thread (mail or Telegram). The operator will review and edit before it sends — your job is to get them 90% of the way with a reply they can approve in one read.\n\n## Inputs you are given\n- The full thread (most recent message last) — mail or Telegram.\n- The client's context: who they are, the engagement, recent activity, known preferences (e.g. \"prefers async\", \"likes bullet points\", tone).\n- Any open commitments or deadlines relevant to this thread.\n\n## How to write it\n1. **Answer what was actually asked.** Identify the concrete asks/questions in the latest message and address each. Don't dodge, don't pad.\n2. **Match the client's voice and channel.** Mail can be a touch more formal; Telegram is shorter and warmer. Mirror how this client and operator have written earlier in the thread.\n3. **Be specific and committed.** If we owe something, say what and by when. If we need info, ask precisely. Avoid vague reassurance (\"we'll look into it\").\n4. **Acknowledge, then move forward.** One line of acknowledgement if warranted, then the substance. No long apologies.\n5. **Surface, don't hide, uncertainty.** If a question can't be answered without info the operator holds, draft the reply with a clearly-marked placeholder like [confirm timeline with operator] rather than guessing.\n\n## Hard rules\n- Never commit to a date, price, or scope that isn't supported by the thread or client context — flag it for the operator instead.\n- Don't invent facts about the engagement.\n- Keep it tight: clients value brevity. Cut anything that doesn't serve the reply.\n\n## Output\nReturn ONLY the reply body, ready to review and send. For mail, you MAY include a one-line subject ONLY if starting a new subject; otherwise omit it. No commentary about your reasoning — just the draft."
+      },
+      {
+        "name": "qualify-reply",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Classify a lead's or client's reply (interested / not-interested / needs-info) and state the single recommended next step. Pure classification — no tools, no sends.",
+        "code": "# Qualify Reply\n\nYou are triaging an inbound reply from a lead or client so the operator (and the automation) knows what to do next. Be decisive and honest — a wrong \"interested\" wastes outreach, a wrong \"not\" loses a deal.\n\n## Inputs you are given\n- The reply text.\n- The thread it replied to (what we asked / sent).\n- Light context on the lead/client and where they are in the flow.\n\n## Classify into exactly ONE label\n- **interested** — they signal openness: a question back, a yes, a request to talk, curiosity about what we do. Lukewarm-but-engaged counts as interested.\n- **not-interested** — a clear no, \"not now\", \"please remove me\", silence-with-decline, or an out-of-office that closes the door. Respect it.\n- **needs-info** — they're not saying yes or no; they need something from us first (pricing, a clarification, proof, a different contact). The ball is in our court.\n\n## How to decide\n- Read intent, not just politeness. \"Thanks, this is interesting, but...\" is usually not-interested or needs-info depending on the \"but\".\n- When genuinely ambiguous, prefer **needs-info** over guessing interested/not — it routes to a human-shaped next step instead of a premature send.\n- Detect explicit opt-outs and ALWAYS classify them not-interested, regardless of tone.\n\n## Output\nReturn a compact result with exactly these fields:\n- `label`: one of interested | not-interested | needs-info\n- `confidence`: low | medium | high\n- `reason`: one sentence citing the signal in their reply.\n- `next_step`: one concrete recommended action (e.g. \"send the personalized first message\", \"draft a reply answering their pricing question\", \"mark not-interested and stop outreach\", \"promote to a deal and start onboarding\").\n\nDo not take the action — only recommend it. Every send remains proposal-gated and operator-reviewed."
+      },
+      {
+        "name": "summarize-thread",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Condense a mail or Telegram thread into the key points plus the open questions. Pure know-how — no tools.",
+        "code": "# Summarize Thread\n\nYou are condensing a communication thread (mail or Telegram) so the operator can grasp it in seconds and pick up where it left off. Accuracy and brevity both matter — a summary that hides an open question is worse than none.\n\n## Inputs you are given\n- The full thread, oldest to newest.\n- Light client/lead context (who the parties are).\n\n## What to produce\n1. **TL;DR** — one or two sentences: what this thread is about and where it stands right now.\n2. **Key points** — 3–6 bullets of the substance: decisions made, commitments given (by us and by them), facts established, dates/numbers that matter. Attribute who said what when it's load-bearing.\n3. **Open questions / awaiting** — the things still unresolved: what we're waiting on from them, what they're waiting on from us, any unanswered question. Be explicit about whose court the ball is in.\n4. **Recommended next step** — one line, only if obvious from the thread.\n\n## Rules\n- Only state what's in the thread. Never infer commitments that weren't made.\n- Preserve specifics — exact dates, amounts, names — don't blur them into \"soon\" or \"some\".\n- If the thread is short, keep the summary shorter than the thread; don't pad.\n\n## Output\nReturn the four sections above as plain markdown. No preamble."
+      },
+      {
+        "name": "extract-action-items",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Turn a thread (mail/Telegram) into a list of concrete, assignable tasks. Pure know-how — no tools.",
+        "code": "# Extract Action Items\n\nYou are turning a communication thread into a clean list of concrete tasks the team can act on. A good action item is unambiguous about WHAT and WHO; a vague one (\"follow up\") is useless.\n\n## Inputs you are given\n- The full thread (mail or Telegram).\n- Client/lead context and who's on our side.\n\n## How to extract\n1. Read the whole thread, then pull out every commitment, request, and unresolved decision that requires someone to DO something.\n2. Phrase each as an imperative starting with a verb: \"Send the revised proposal\", \"Confirm the launch date with the client\", \"Draft the onboarding doc\".\n3. Assign an owner where the thread makes it clear (us vs the client vs a named person). If unclear, mark owner as `unassigned`.\n4. Capture a due date / timeframe ONLY if the thread states or strongly implies one — never invent deadlines.\n5. Note a one-clause source so the operator can trace it back (\"client asked for pricing in last message\").\n\n## Rules\n- One task per item — split compound asks (\"send the deck and book a call\") into two.\n- Don't manufacture tasks the thread doesn't support. If there are no action items, say so plainly.\n- Keep client-side and our-side tasks distinct so the operator sees what we owe vs what we're waiting on.\n\n## Output\nReturn a list where each item has: `task` (imperative), `owner` (us | client | named person | unassigned), `due` (date/timeframe or null), `source` (one clause). These will be proposed as task entities linked to the client — every write stays proposal-gated."
+      },
+      {
+        "name": "client-brief",
+        "kind": "instruction",
+        "scope": "pod",
+        "description": "Assemble a client's context — who they are, the engagement, recent activity — at the start of an agent turn so the agent acts with full grounding. Pure know-how — no tools.",
+        "code": "# Client Brief\n\nYou are assembling a fast, accurate briefing on a client at the START of a turn, so everything you do next (drafting a reply, planning work, answering the operator) is grounded in who this client actually is. Think of it as reading the file before the meeting.\n\n## Inputs you are given\n- The client entity (name, company, the engagement, status).\n- Recent activity: latest messages across their channels, recent tasks/deals, recent notes.\n- Any stored preferences or facts about how they like to work.\n\n## What to assemble\n1. **Who they are** — client/company name, the relationship (deal stage or active engagement), and the one-line of what we do for them.\n2. **Where things stand** — the current state of the engagement: what's in flight, what's blocked, what's recently shipped or decided.\n3. **Recent activity** — the last few meaningful touchpoints (a mail, a Telegram exchange, a meeting), newest first, each one clause.\n4. **Open items** — what we owe them and what we're waiting on (pull from open tasks / unresolved threads).\n5. **How to work with them** — known preferences: tone, channel, cadence, sensitivities (e.g. \"prefers async\", \"wants weekly updates\", \"don't loop in X\").\n\n## Rules\n- Only state what the pod actually knows — never fabricate engagement details or preferences.\n- Lead with what's most decision-relevant for the turn ahead; cut stale or irrelevant history.\n- Keep it scannable — the agent reads this in one pass before acting.\n\n## Output\nReturn the five sections as compact markdown. This is the agent's grounding for the turn; it is not shown to the client."
+      }
+    ],
+    "provides": [],
+    "playbooks": [
+      {
+        "name": "Lead Outreach",
+        "description": "Flow 1 — Lead acquisition via LinkedIn outreach from an imported list. The agent works the list one lead at a time, each step proposal-gated and operator-reviewed.",
+        "goalTemplate": "Work a list of imported leads into qualified conversations via LinkedIn. For each lead: (1) find their LinkedIn profile via Unipile profile search; (2) send a connection request (proposal-gated); (3) wait for acceptance (delay / scheduled re-check); (4) on acceptance, use the draft-outreach skill to write a personalized, non-salesy first message from the lead's profile + our agency pitch, and propose it for the operator to review and send; (5) on reply, use qualify-reply to classify interest and recommend the next step — if interested, promote the lead to a deal/client and trigger the client-onboarding flow. Every outbound action stays proposal-gated and reversible.",
+        "params": [
+          {
+            "name": "leadSource",
+            "label": "Lead source",
+            "type": "text",
+            "required": false,
+            "description": "Where this batch of leads came from (e.g. the monthly CSV name or the campaign angle) — used to ground the outreach."
+          }
+        ],
+        "inputStrategy": {
+          "kind": "entity-list",
+          "description": "Bound to a list of lead entities (e.g. imported from a monthly CSV); the agent iterates one lead per cycle."
+        },
+        "channelSpec": {
+          "kind": "session",
+          "description": "Runs in the lead-outreach session; outreach drafts and qualification post into the session for review."
+        },
+        "expectedOutputs": [
+          {
+            "kind": "entity",
+            "profileSlug": "person",
+            "description": "LinkedIn profiles matched and enriched as person entities."
+          },
+          {
+            "kind": "note",
+            "description": "Connection requests and sent first messages recorded for the activity timeline."
+          },
+          {
+            "kind": "deal",
+            "description": "Interested leads promoted to deals for the onboarding flow."
+          }
+        ],
+        "schedule": null,
+        "executor": "is-agent",
+        "status": "draft"
+      },
+      {
+        "name": "Client Onboarding",
+        "description": "Flow 3 — One command (a won deal, or /link-client) sets up the whole client context. Idempotent: re-running ensures the pieces exist without duplicating them. Every creation is proposal-gated.",
+        "goalTemplate": "Onboard a client into a complete working context. Steps: (1) ensure the client ENTITY exists (create it from the deal/name if absent); (2) ensure the client ROOM + threads exist — a client-comms thread for inbound mail/Telegram and a team+AI thread for work; (3) start a per-client SESSION bound to the client (instantiate with subjectId = the client entity) as the hub linking their mail/Drive/tasks/messages; (4) attach the DEFAULT automations for this client (e.g. draft-reply on inbound mail, intro message on first channel creation) — opt-in per client; (5) link the client's Google DRIVE folder (create + share if absent) via the gdrive tool; (6) link the client's MAIL (the dedicated per-engagement address); (7) PIN the client context to the channel — the Drive link and a client-brief (use the client-brief skill) so every turn starts grounded. Each step is proposal-gated and reversible; re-running is idempotent.",
+        "params": [
+          {
+            "name": "clientName",
+            "label": "Client name",
+            "type": "text",
+            "required": true,
+            "description": "The client to onboard (used to find-or-create the client entity)."
+          }
+        ],
+        "inputStrategy": {
+          "kind": "entity",
+          "description": "Bound to a single client entity (the subject); the session is instantiated with this client as subjectId."
+        },
+        "channelSpec": {
+          "kind": "client-room",
+          "description": "Sets up the client's room with a client-comms thread (inbound mail/Telegram) and a team+AI thread (work)."
+        },
+        "expectedOutputs": [
+          {
+            "kind": "entity",
+            "profileSlug": "client",
+            "description": "The client entity, ensured."
+          },
+          {
+            "kind": "channel",
+            "description": "The client room + client-comms and team+AI threads."
+          },
+          {
+            "kind": "note",
+            "description": "Pinned client context: Drive link + client-brief."
+          }
+        ],
+        "schedule": null,
+        "executor": "is-agent",
+        "status": "draft"
+      }
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/apify.capability.json

@@ -0,0 +1,265 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "apify",
+    "name": "Apify — Web Scraping",
+    "description": "Find and run any Apify actor to collect data from public web pages and social posts, then bring the results into your workspace. Public data only; it cannot read private or saved posts. Needs an Apify API token.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "apify",
+    "name": "Apify — Actor Platform",
+    "description": "Full Apify actor-platform access: discover marketplace actors, inspect any actor's real input schema, run any actor generically, plus a convenience skill for the common case (read one public social post by URL). Everything verified against Apify's public API docs (store search, actor/build metadata, sync run, dataset items), not guessed. GOTCHA: this is NOT a Unipile substitute and NOT a private-saved-posts fetcher — Apify scrapes PUBLIC pages only; there is no reliable, ToS-compliant way to read a user's own saved/bookmarked posts on Instagram or TikTok (neither platform exposes that via official API, and cookie-based scraping of private data is fragile and ToS-risky — deliberately NOT implemented). Scheduling recurring actor runs is deliberately NOT implemented here either — use Synap's own automation/playbook scheduling instead of duplicating Apify's scheduler; this capability stays focused on discovery + on-demand execution. Apify actor ids with a `/` are addressed with `~` in the URL path (owner~actor-name) per Apify's REST convention; all metadata endpoints (store, actor, build) wrap results in a top-level `data` object, but run-sync-get-dataset-items returns a bare array — handled per-skill. PRECONDITION: an Apify account with an API token (Console -> Settings -> Integrations -> Personal API tokens).",
+    "params": [
+      {
+        "name": "apifyToken",
+        "label": "Apify API token",
+        "type": "text",
+        "required": true,
+        "description": "The Apify API token (Console -> Settings -> Integrations -> Personal API tokens). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "apifyTokenSecret",
+        "name": "{{name}} Apify API token",
+        "value": "{{apifyToken}}",
+        "type": "api_key",
+        "description": "Apify API token for the apify_api connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "apify_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Apify REST API (https://api.apify.com/v2). The applier injects the vaulted API token into the Authorization header as `Bearer <token>`; its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "apifyTokenSecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.apify.com/v2",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "apify_search_actors",
+        "intent": "search_external",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Searches the Apify actor marketplace by keyword/category so an agent can discover the right actor instead of guessing an id. No cost, no side effects. Args: { search?: string, category?: string, limit?: number (default 10, max 50) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "search": "string?",
+          "category": "string?",
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "apify_api",
+          "method": "GET",
+          "pathTemplate": "/store",
+          "query": {
+            "search": "{{search}}",
+            "category": "{{category}}",
+            "limit": "{{limit}}"
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 10,
+              "clampMin": 1,
+              "clampMax": 50
+            }
+          },
+          "responseShape": {
+            "collectionPath": "data.items",
+            "collectionAs": "actors"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "apify_get_actor_schema",
+        "intent": "fetch_record",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Fetches one actor's real input schema (field names, types, descriptions, required flags) so an agent knows exactly what to pass to apify_run_actor, instead of guessing. No cost, no side effects (2 metadata GETs, no actor run). Args: { actorId: string (from apify_search_actors, or owner/actor-name) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "actorId": "string"
+        },
+        "code": "// Fetch an actor's real input schema via its latest tagged build.\n// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. callProvider resolves apify_api by NAME and injects\n// the vaulted token. Apify metadata endpoints wrap results in a top-level\n// `data` object (verified against Apify's API docs).\nconst actorIdRaw = String(args?.actorId ?? '').trim();\nif (!actorIdRaw) throw new Error('apify_get_actor_schema: actorId is required');\nconst actorId = actorIdRaw.replace(/\\//g, '~');\n\nconst actorRes = await callProvider('apify_api', 'GET', `/actors/${actorId}`);\nconst actor = actorRes?.body?.data ?? actorRes?.data ?? actorRes;\nconst buildId = actor?.taggedBuilds?.latest?.buildId;\nif (!buildId) throw new Error(`apify_get_actor_schema: no latest build found for actor \"${actorIdRaw}\" — check the actorId is correct`);\n\nconst buildRes = await callProvider('apify_api', 'GET', `/actors/${actorId}/builds/${buildId}`);\nconst build = buildRes?.body?.data ?? buildRes?.data ?? buildRes;\nconst inputSchema = build?.actorDefinition?.input ?? null;\n\nreturn {\n  actorId: actorIdRaw,\n  name: actor?.name ?? null,\n  title: actor?.title ?? null,\n  description: actor?.description ?? null,\n  inputSchema,\n};",
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "apify_run_actor",
+        "intent": "run_external_job",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Runs ANY Apify actor by id with arbitrary input and returns its results (proposal-gated — billed external run). Use apify_search_actors to find an actor and apify_get_actor_schema to see what input it takes first. Writes nothing: it returns the items, and the caller decides what to keep. Args: { actorId: string, input?: object (actor-specific, see apify_get_actor_schema) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "actorId": "string",
+          "input": "object?"
+        },
+        "code": "// Run any Apify actor synchronously and return its dataset items.\n// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. callProvider resolves apify_api by NAME and injects\n// the vaulted token. run-sync-get-dataset-items returns a BARE array (not\n// wrapped in `data`, unlike the metadata endpoints) — verified against Apify's\n// API docs.\nconst actorIdRaw = String(args?.actorId ?? '').trim();\nif (!actorIdRaw) throw new Error('apify_run_actor: actorId is required');\nconst actorId = actorIdRaw.replace(/\\//g, '~');\nconst input = (args?.input && typeof args.input === 'object') ? args.input : {};\n\nconst res = await callProvider('apify_api', 'POST', `/actors/${actorId}/run-sync-get-dataset-items`, input);\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, actorId: actorIdRaw };\n}\nconst payload = res?.body ?? res;\nconst items = Array.isArray(payload) ? payload : [];\n\n// Writes nothing: the run is billed, so its result must come back whole. A\n// caller (or a specific verb like capture_social_post) decides what to keep.\nreturn { success: true, actorId: actorIdRaw, itemCount: items.length, items };"
+      },
+      {
+        "name": "apify_list_actor_runs",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Lists past runs of one actor (status, dataset id, timestamps) — use with apify_get_dataset_items to pull results from a specific past run after the fact. No cost, no side effects. Args: { actorId: string, status?: string (e.g. SUCCEEDED), limit?: number (default 10) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "actorId": "string",
+          "status": "string?",
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "apify_api",
+          "method": "GET",
+          "pathTemplate": "/actors/{{actorId}}/runs",
+          "paramMapping": {
+            "actorId": {
+              "encode": "uri"
+            }
+          },
+          "query": {
+            "status": "{{status}}",
+            "limit": "{{limit}}",
+            "desc": "true"
+          },
+          "responseShape": {
+            "collectionPath": "data.items",
+            "collectionAs": "runs"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "apify_get_dataset_items",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Fetches the result items of one dataset (from apify_list_actor_runs' defaultDatasetId, or any dataset id) — the way to pull results from a PAST run without re-running the actor. No cost, no side effects. Args: { datasetId: string, limit?: number (default 50) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "datasetId": "string",
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "apify_api",
+          "method": "GET",
+          "pathTemplate": "/datasets/{{datasetId}}/items",
+          "paramMapping": {
+            "datasetId": {
+              "encode": "uri"
+            },
+            "limit": {
+              "default": 50,
+              "clampMin": 1,
+              "clampMax": 500
+            }
+          },
+          "query": {
+            "limit": "{{limit}}",
+            "clean": "true"
+          }
+        },
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "capture_social_post",
+        "intent": "read_webpage",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Reads one public Instagram post, reel or carousel, or one TikTok video, from its link: the caption, the author, the date, every picture and the video, and the like, comment and view counts. It saves nothing by itself. Public posts only: a private or deleted post comes back as blocked. It runs on YOUR Apify account, and Apify bills each run, retries included. Instagram's and TikTok's terms forbid automated collection; you are responsible for using it. Args: { url: string, withVideo?: boolean (TikTok only: also download the video file — off unless the person picks it; Apify may bill more per item) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "url": "string",
+          "withVideo": "boolean?"
+        },
+        "urls": [
+          "instagram.com/p/*",
+          "instagram.com/reel/*",
+          "instagram.com/reels/*",
+          "instagram.com/tv/*",
+          "tiktok.com/@*/video/*",
+          "vm.tiktok.com/*",
+          "vt.tiktok.com/*"
+        ],
+        "code": "// A READER: one public Instagram post/reel/carousel or TikTok video by URL,\n// read through an Apify actor's synchronous run, returned in the UrlRead shape\n// (@synap-core/types/url-read). It writes nothing: the pod's read door stamps\n// `via`, normalizes the result and keeps it (the Library item is the one home\n// of a kept post).\n// Executor wraps this body as (async (args, context) => { <code> }); use args\n// directly and `return`. callProvider(tool, method, path, body?) resolves the\n// apify_api tool by NAME, injects the vaulted token as Authorization: Bearer\n// <token>, and uses the tool's config.baseUrl = https://api.apify.com/v2.\n// Apify actor ids with a '/' use '~' in the URL path (owner~actor-name).\n// The URLs accepted here are exactly the verb's declared `urls` (a catalog\n// test runs this body against them).\nconst url = String(args?.url ?? '').trim();\nif (!url) return { status: 'failed', sourceUrl: url, error: 'capture_social_post: url is required' };\n\nlet parsed = null;\ntry { parsed = new URL(url); } catch (_) { parsed = null; }\nconst scheme = parsed ? parsed.protocol.toLowerCase() : '';\nconst host = parsed ? parsed.hostname.toLowerCase().replace(/^www\\./, '') : '';\nconst path = parsed ? parsed.pathname : '';\n\n// The vendor is sent the URL as PARSED (what the checks above saw), never the\n// raw string: WHATWG drops tabs/newlines, so the two can differ.\nlet platform, actorId, body;\nif ((scheme === 'https:' || scheme === 'http:') && host === 'instagram.com' && /^\\/(p|reel|reels|tv)\\/[^/]+(\\/|$)/.test(path)) {\n  platform = 'instagram';\n  actorId = 'apify~instagram-scraper';\n  body = { directUrls: [parsed.href], resultsType: 'posts' };\n} else if ((scheme === 'https:' || scheme === 'http:') && ((host === 'tiktok.com' && /^\\/@[^/]+\\/video\\/[^/]+(\\/|$)/.test(path)) || ((host === 'vm.tiktok.com' || host === 'vt.tiktok.com') && /^\\/[^/]+(\\/|$)/.test(path)))) {\n  platform = 'tiktok';\n  actorId = 'clockworks~tiktok-scraper';\n  // The video file is downloaded only when the person picked \"with video\"\n  // (`withVideo`): the actor bills more per item for it.\n  body = { postURLs: [parsed.href], shouldDownloadVideos: args?.withVideo === true };\n} else {\n  return {\n    status: 'blocked',\n    sourceUrl: url,\n    blocked: { reason: 'unsupported', detail: 'Reads only public instagram.com/p, /reel, /reels and /tv links, and tiktok.com/@user/video, vm.tiktok.com and vt.tiktok.com links.' },\n  };\n}\n\n// An Apify HTTP / auth / quota / run failure is NOT caught: it propagates like\n// every other Apify verb's, so the executor keeps its failure class (re-auth,\n// retry later) and the read door maps it to a retryable failure.\nconst res = await callProvider('apify_api', 'POST', `/actors/${actorId}/run-sync-get-dataset-items`, body);\nif (res?.proposed === true) {\n  return { status: 'failed', sourceUrl: url, error: 'The Apify run is waiting for approval; nothing was read yet.', proposed: true, proposalId: res?.proposalId ?? null };\n}\nif (typeof res?.status === 'number' && res.status >= 400) {\n  throw new Error(`capture_social_post: the Apify run answered HTTP ${res.status}`);\n}\nconst payload = res?.body ?? res;\nconst items = Array.isArray(payload) ? payload : [];\nconst item = items[0];\n\n// Not there, or not public. The actors return an empty dataset, or one item\n// carrying `error` / `errorDescription`, for a private, deleted or missing post.\n// \"Missing\" is checked first: the Instagram actor's \"Empty or private data\"\n// cannot tell the two apart, and a deleted post is the likelier reading.\nconst MISSING = /not.?found|no.?items|empty|deleted|unavailable|does not exist|404|removed/i;\nconst PRIVATE = /private|restricted|login/i;\nif (!item || typeof item !== 'object') {\n  return { status: 'blocked', sourceUrl: url, blocked: { reason: 'not_found', detail: 'Apify returned nothing for this link: the post may be deleted, private or region-locked.' } };\n}\nconst itemError = [item.error, item.errorDescription, item.errorMessage].filter((x) => typeof x === 'string' && x).join(': ');\nif (itemError) {\n  if (MISSING.test(itemError)) return { status: 'blocked', sourceUrl: url, blocked: { reason: 'not_found', detail: itemError } };\n  if (PRIVATE.test(itemError)) return { status: 'blocked', sourceUrl: url, blocked: { reason: 'private', detail: itemError } };\n  // Any other actor error is a run failure, not a fact about the post.\n  throw new Error(`capture_social_post: Apify could not read this post: ${itemError}`);\n}\n\nconst isUrl = (u) => typeof u === 'string' && /^https?:\\/\\//i.test(u);\nconst num = (n) => (typeof n === 'number' && Number.isFinite(n) ? n : undefined);\nconst firstLine = (s) => (typeof s === 'string' ? s.split('\\n').map((l) => l.trim()).find(Boolean) : undefined);\nconst media = [];\nconst seen = new Set();\nconst add = (m) => {\n  if (!isUrl(m.url) || seen.has(m.kind + ' ' + m.url)) return;\n  seen.add(m.kind + ' ' + m.url);\n  const entry = { url: m.url, kind: m.kind, order: media.length };\n  if (m.role) entry.role = m.role;\n  if (num(m.width)) entry.width = m.width;\n  if (num(m.height)) entry.height = m.height;\n  if (num(m.durationSec)) entry.durationSec = m.durationSec;\n  media.push(entry);\n};\n\nlet read;\nif (platform === 'instagram') {\n  // apify~instagram-scraper's dataset: caption, ownerUsername, ownerFullName,\n  // timestamp, url, type (Image | Video | Sidecar), displayUrl (always an\n  // image, even for a reel), videoUrl, videoDuration, dimensionsWidth/Height,\n  // images (every image of a carousel) and childPosts (each carousel slide,\n  // with its own displayUrl / videoUrl), likesCount, commentsCount,\n  // videoViewCount / videoPlayCount.\n  const children = Array.isArray(item.childPosts) ? item.childPosts.filter((c) => c && typeof c === 'object') : [];\n  const slideImages = children.length ? children.map((c) => c.displayUrl) : Array.isArray(item.images) ? item.images : [];\n  // The cover: the post's own still. In a carousel it is the first slide, so it\n  // is listed once, as that slide.\n  if (!slideImages.includes(item.displayUrl)) {\n    add({ url: item.displayUrl, kind: 'image', role: 'cover', width: item.dimensionsWidth, height: item.dimensionsHeight });\n  }\n  add({ url: item.videoUrl, kind: 'video', width: item.dimensionsWidth, height: item.dimensionsHeight, durationSec: item.videoDuration });\n  if (children.length) {\n    for (const c of children) {\n      add({ url: c.displayUrl, kind: 'image', role: 'slide', width: c.dimensionsWidth, height: c.dimensionsHeight });\n      add({ url: c.videoUrl, kind: 'video', role: 'slide', width: c.dimensionsWidth, height: c.dimensionsHeight, durationSec: c.videoDuration });\n    }\n  } else {\n    for (const u of slideImages) add({ url: u, kind: 'image', role: 'slide' });\n  }\n  const author = item.ownerUsername || item.ownerFullName || undefined;\n  read = {\n    canonicalUrl: isUrl(item.url) ? item.url : undefined,\n    title: firstLine(item.caption)?.slice(0, 120),\n    author,\n    authorUrl: item.ownerUsername ? `https://www.instagram.com/${item.ownerUsername}/` : undefined,\n    text: typeof item.caption === 'string' && item.caption.trim() ? item.caption : undefined,\n    publishedAt: typeof item.timestamp === 'string' ? item.timestamp : undefined,\n    fields: { platform, likes: num(item.likesCount), comments: num(item.commentsCount), views: num(item.videoViewCount) ?? num(item.videoPlayCount) },\n  };\n} else {\n  // clockworks~tiktok-scraper's dataset: text, createTimeISO, webVideoUrl (the\n  // post page), authorMeta { name, profileUrl }, videoMeta { coverUrl,\n  // downloadAddr, width, height, duration }, mediaUrls (stored video files,\n  // when the actor downloads them), diggCount, commentCount, playCount.\n  const meta = item.videoMeta && typeof item.videoMeta === 'object' ? item.videoMeta : {};\n  add({ url: meta.coverUrl ?? meta.originalCoverUrl, kind: 'image', role: 'cover', width: meta.width, height: meta.height });\n  const videoFile = (Array.isArray(item.mediaUrls) ? item.mediaUrls.find(isUrl) : undefined) ?? meta.downloadAddr;\n  add({ url: videoFile, kind: 'video', width: meta.width, height: meta.height, durationSec: meta.duration });\n  const am = item.authorMeta && typeof item.authorMeta === 'object' ? item.authorMeta : {};\n  read = {\n    canonicalUrl: isUrl(item.webVideoUrl) ? item.webVideoUrl : undefined,\n    title: firstLine(item.text)?.slice(0, 120),\n    author: am.name || am.nickName || undefined,\n    authorUrl: isUrl(am.profileUrl) ? am.profileUrl : am.name ? `https://www.tiktok.com/@${am.name}` : undefined,\n    text: typeof item.text === 'string' && item.text.trim() ? item.text : undefined,\n    publishedAt: typeof item.createTimeISO === 'string' ? item.createTimeISO : undefined,\n    fields: { platform, likes: num(item.diggCount), comments: num(item.commentCount), views: num(item.playCount) },\n  };\n}\nfor (const k of Object.keys(read.fields)) if (read.fields[k] === undefined) delete read.fields[k];\nfor (const k of Object.keys(read)) if (read[k] === undefined) delete read[k];\nreturn { status: 'ok', sourceUrl: url, ...read, media: media.slice(0, 12) };",
+        "metadata": {
+          "readOnly": true
+        }
+      },
+      {
+        "name": "apify_linkedin_profile",
+        "intent": "enrich_entity",
+        "kind": "code",
+        "scope": "pod",
+        "category": "enrichment",
+        "description": "Enriches ONE person from a PUBLIC LinkedIn profile URL via the Apify actor curious_coder/linkedin-profile-scraper, and returns normalized fields { jobTitle, city, country, bio, company, email, phone, website } where the actor provides them (billed external run). Also returns scrapedName (the profile's full name) SEPARATELY at the top level — NOT mapped into properties, since the name is the entity title, not a person property. Read-only for the pod — returns data; the caller decides whether to write it (mirrors the CRM's useEnrich enrichLinkedIn). Args: { url: string (a linkedin.com/in/ profile URL) }.",
+        "requires": [
+          "apify_api"
+        ],
+        "executionMode": "async",
+        "timeoutSeconds": 120,
+        "parameters": {
+          "url": "string"
+        },
+        "code": "// Enrich a person from a public LinkedIn profile URL via an Apify actor's\n// synchronous run. Executor wraps this body as (async (args, context) => { <code> });\n// use args directly and `return`. callProvider(tool, method, path, body?) resolves\n// the apify_api tool by NAME, injects the vaulted token as Authorization: Bearer\n// <token>, and uses config.baseUrl = https://api.apify.com/v2. Apify actor ids\n// with a '/' use '~' in the URL path (owner~actor-name). Field map is DEFENSIVE:\n// the actor (curious_coder/linkedin-profile-scraper) output shape drifts across\n// runs/plans, so each field tries its most likely key(s) and is skipped (never\n// thrown) when absent. Confirmed actor keys: headline/jobTitle, occupation,\n// summary, geoLocationName/geoCountryName, companyName, positions[0].companyName,\n// firstName/lastName, publicIdentifier, pictureUrl. email/phone only appear when\n// the actor's findContacts option is enabled (not set here) — mapped defensively\n// in case a future run includes them.\nconst url = String(args?.url ?? '').trim();\nif (!url) throw new Error('apify_linkedin_profile: url is required (a public linkedin.com/in/ profile URL)');\nif (!/linkedin\\.com\\/in\\//i.test(url)) throw new Error('apify_linkedin_profile: url must be a linkedin.com/in/ profile URL');\n\nconst actorId = 'curious_coder~linkedin-profile-scraper';\nconst input = { profileUrls: [{ url }], maxResults: 1 };\n\nconst res = await callProvider('apify_api', 'POST', `/actors/${actorId}/run-sync-get-dataset-items`, input);\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null, url };\n}\nconst payload = res?.body ?? res;\nconst items = Array.isArray(payload) ? payload : [];\nconst data = items[0];\nif (!data) throw new Error('apify_linkedin_profile: no data returned — the profile may be private, region-locked, or the URL malformed');\n\nconst mapped = {};\nif (data.jobTitle) mapped.jobTitle = data.jobTitle;\nelse if (data.headline) mapped.jobTitle = data.headline;\nelse if (data.occupation) mapped.jobTitle = data.occupation;\n\nif (typeof data.location === 'string' && data.location) mapped.city = data.location;\nelse if (data.location?.city) mapped.city = data.location.city;\nelse if (data.geoLocationName) mapped.city = data.geoLocationName;\n\nif (typeof data.location === 'object' && data.location?.country) mapped.country = data.location.country;\nelse if (data.geoCountryName) mapped.country = data.geoCountryName;\nelse if (data.countryCode) mapped.country = data.countryCode;\n\nif (data.summary) mapped.bio = data.summary;\nelse if (data.about) mapped.bio = data.about;\n\nconst company = data.companyName\n  ?? (Array.isArray(data.experiences) ? data.experiences[0]?.company : undefined)\n  ?? (Array.isArray(data.positions) ? data.positions[0]?.companyName : undefined);\nif (company) mapped.company = company;\n\nif (data.email) mapped.email = data.email;\nelse if (data.emailAddress) mapped.email = data.emailAddress;\nelse if (data.contactInfo?.email) mapped.email = data.contactInfo.email;\n\nif (data.phone) mapped.phone = data.phone;\nelse if (Array.isArray(data.phoneNumbers) && data.phoneNumbers[0]) mapped.phone = data.phoneNumbers[0];\nelse if (data.contactInfo?.phone) mapped.phone = data.contactInfo.phone;\n\nconst website = data.website\n  ?? data.personalWebsite\n  ?? (Array.isArray(data.contactInfo?.websites) ? data.contactInfo.websites[0] : undefined);\nif (website) mapped.website = website;\n\nconst joinedName = [data.firstName, data.lastName].filter(Boolean).join(' ').trim();\nconst scrapedName = data.fullName || joinedName || undefined;\n\nreturn { matched: Object.keys(mapped).length > 0, fields: Object.keys(mapped).length, url, scrapedName, ...mapped };"
+      }
+    ],
+    "provides": [
+      "search_external",
+      "fetch_record",
+      "run_external_job",
+      "list_records",
+      "read_webpage",
+      "enrich_entity"
+    ]
+  },
+  "dependencies": []
+}

package/capabilities/apollo.capability.json

@@ -0,0 +1,120 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "apollo",
+    "name": "Apollo — People & Company Enrichment",
+    "description": "Look up people and companies in Apollo.io and get clean fields back: email, phone, job title, LinkedIn, industry, company size. Read-only; nothing is created unless you choose to. Needs an Apollo API key.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "apollo",
+    "name": "Apollo — People & Company Enrichment",
+    "description": "B2B enrichment via the Apollo.io API (base https://api.apollo.io/api/v1) using API-key auth. Stores the Apollo API key in the vault, registers one HTTP API tool that authenticates with the `x-api-key` header (raw key, NO Bearer prefix — Apollo's auth scheme, verified against synap-backend's ApolloProvider), and seeds three READ-ONLY enrichment/search skills that return NORMALIZED keys ({ email, phone, jobTitle, linkedinUrl, city, country, company, industry, companySize, website, description }) so an agent (or a radar/CRM playbook) gets clean fields instead of Apollo's raw shape. apollo_enrich_person (POST people/match) is a `code` skill because Apollo nests the phone under `person.phone_numbers[0].sanitized_number` — an array flatten a declarative scalar map can't express. apollo_enrich_company (POST organizations/enrich) is a `code` skill because Apollo keys the endpoint on `domain`: a name-only company must OMIT domain (a declarative body map would emit `domain: \"\"`, which Apollo mis-matches), and the org's own name is deliberately not echoed back as a redundant `company` prop. apollo_search_people (POST mixed_people/search) is a `code` skill (not declarative) DELIBERATELY: the governance-name lint treats a declarative POST as a write, which would mislabel a `search`-named verb; a code skill POSTing to a `/search`-suffixed path is correctly recognized read-only (same reason Exa's search is code). All three are reads with no external side effect — they never create entities; the caller decides what to do with the returned data (mirrors the CRM's useEnrich, which takes the mapped result and files its own governed proposal). GOTCHA: Apollo's people-search often returns a locked placeholder email (email_not_unlocked@domain.com) rather than a real address — pass it through as-is; unlocking is a separate billed action deliberately NOT implemented here. PRECONDITION: an Apollo account with an API key (Settings -> Integrations -> API, an Apollo master API key). Pass it as `apolloApiKey`.",
+    "params": [
+      {
+        "name": "apolloApiKey",
+        "label": "Apollo API key",
+        "type": "text",
+        "required": true,
+        "description": "The Apollo.io API key (Settings -> Integrations -> API). Stored server-encrypted in the vault; never persisted in the template."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "apolloApiKeySecret",
+        "name": "{{name}} Apollo API key",
+        "value": "{{apolloApiKey}}",
+        "type": "api_key",
+        "description": "Apollo.io API key for the apollo_api connector."
+      }
+    ],
+    "tools": [
+      {
+        "name": "apollo_api",
+        "kind": "api",
+        "description": "Authenticated HTTP access to the Apollo.io REST API (https://api.apollo.io/api/v1). The applier injects the vaulted API key into the `x-api-key` header (raw key, no prefix — Apollo's auth scheme, NOT Bearer); its credentialRef is remapped to the runtime vault://<id> at apply time.",
+        "credentialRef": "apolloApiKeySecret",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "https://api.apollo.io/api/v1",
+          "auth": {
+            "in": "header",
+            "name": "x-api-key",
+            "prefix": ""
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "apollo_enrich_person",
+        "intent": "enrich_entity",
+        "kind": "code",
+        "scope": "pod",
+        "category": "enrichment",
+        "description": "Enriches ONE person via Apollo's people/match and returns normalized contact fields { email, phone, jobTitle, linkedinUrl, city, country, company }. Read-only, no side effects (returns data; the caller decides whether to write it). Pass whatever you know — more signals = better match. Args: { name?: string (full name, split into first/last), firstName?: string, lastName?: string, email?: string, company?: string (organization name) }.",
+        "requires": [
+          "apollo_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 45,
+        "parameters": {
+          "name": "string?",
+          "firstName": "string?",
+          "lastName": "string?",
+          "email": "string?",
+          "company": "string?"
+        },
+        "code": "// Enrich a single person via Apollo people/match. Executor wraps this body as\n// (async (args, context) => { <code> }); use args directly and `return`.\n// callProvider('apollo_api','POST','/people/match',body) resolves the apollo_api\n// tool by NAME and injects the vaulted key as `x-api-key: <key>` (config.auth).\n// people/match returns { person: {...} }; Apollo nests the phone under\n// person.phone_numbers[0].sanitized_number — the array flatten this code exists\n// for (mirrors synap-app CRM useEnrich enrichPerson).\nlet firstName = String(args?.firstName ?? '').trim();\nlet lastName = String(args?.lastName ?? '').trim();\nif (!firstName && !lastName) {\n  const parts = String(args?.name ?? '').trim().split(/\\s+/).filter(Boolean);\n  firstName = parts[0] ?? '';\n  lastName = parts.slice(1).join(' ');\n}\nconst email = String(args?.email ?? '').trim();\nconst company = String(args?.company ?? '').trim();\n\nconst payload = {};\nif (firstName) payload.first_name = firstName;\nif (lastName) payload.last_name = lastName;\nif (email) payload.email = email;\nif (company) payload.organization_name = company;\nif (Object.keys(payload).length === 0) throw new Error('apollo_enrich_person: provide at least a name/firstName, email, or company to match on');\n\nconst res = await callProvider('apollo_api', 'POST', '/people/match', payload);\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null };\n}\nconst body = res?.body ?? res;\nconst person = (body && typeof body === 'object' && body.person) ? body.person : (body ?? {});\n\nconst mapped = {};\nif (person.email) mapped.email = person.email;\nconst phone = Array.isArray(person.phone_numbers) ? person.phone_numbers[0]?.sanitized_number : undefined;\nif (phone) mapped.phone = phone;\nif (person.title) mapped.jobTitle = person.title;\nif (person.linkedin_url) mapped.linkedinUrl = person.linkedin_url;\nif (person.city) mapped.city = person.city;\nif (person.country) mapped.country = person.country;\nconst history = Array.isArray(person.employment_history) ? person.employment_history[0]?.organization_name : undefined;\nif (history && !company) mapped.company = history;\n\nreturn { matched: Object.keys(mapped).length > 0, fields: Object.keys(mapped).length, ...mapped };"
+      },
+      {
+        "name": "apollo_enrich_company",
+        "intent": "enrich_entity",
+        "kind": "code",
+        "scope": "pod",
+        "category": "enrichment",
+        "description": "Enriches ONE company via Apollo's organizations/enrich and returns normalized firmographic fields { industry, companySize, website, description, linkedinUrl, country }. Read-only, no side effects (returns data; the caller decides whether to write it). A `code` skill (not declarative) DELIBERATELY: Apollo keys this endpoint on `domain`, so a name-only call must OMIT domain entirely — a declarative body map would send `domain: \"\"` (interpolateDeep doesn't prune empty scalars), which Apollo mis-matches. It also does NOT echo organization.name back as a `company` prop: the caller is a company entity that already owns its name as its title, so returning `company` would file a dead self-referential write (mirrors synap-app CRM useEnrich, whose company field set has no `company`). Prefer `domain` (Apollo's primary key for this endpoint); `name` is a best-effort fallback. Args: { domain?: string (e.g. acme.com — no scheme), name?: string (company name) }.",
+        "requires": [
+          "apollo_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 45,
+        "parameters": {
+          "domain": "string?",
+          "name": "string?"
+        },
+        "code": "// Enrich ONE company via Apollo organizations/enrich. Executor wraps this body\n// as (async (args, context) => { <code> }); use args directly and `return`.\n// callProvider('apollo_api','POST','/organizations/enrich',body) resolves the\n// apollo_api tool by NAME and injects the vaulted key as `x-api-key: <key>`.\n// Build the payload omitting empties: Apollo keys this endpoint on `domain`, so a\n// name-only company (no website) must NOT send `domain: \"\"` (a declarative body\n// map would, and Apollo mis-matches on it). organization.name is deliberately NOT\n// mapped back — the caller's company entity already owns its name as its title;\n// echoing `company` would file a dead self-referential prop write.\nconst domain = String(args?.domain ?? '').trim().replace(/^https?:\\/\\//, '').replace(/\\/.*$/, '');\nconst name = String(args?.name ?? '').trim();\nconst payload = {};\nif (domain) payload.domain = domain;\nif (name) payload.name = name;\nif (Object.keys(payload).length === 0) throw new Error('apollo_enrich_company: provide a domain (preferred) or a company name to match on');\n\nconst res = await callProvider('apollo_api', 'POST', '/organizations/enrich', payload);\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null };\n}\nconst body = res?.body ?? res;\nconst org = (body && typeof body === 'object' && body.organization) ? body.organization : (body ?? {});\n\nconst mapped = {};\nif (org.industry) mapped.industry = org.industry;\nif (org.estimated_num_employees) mapped.companySize = org.estimated_num_employees;\nif (org.website_url) mapped.website = org.website_url;\nif (org.short_description) mapped.description = org.short_description;\nif (org.linkedin_url) mapped.linkedinUrl = org.linkedin_url;\nif (org.country) mapped.country = org.country;\n\nreturn { matched: Object.keys(mapped).length > 0, fields: Object.keys(mapped).length, ...mapped };"
+      },
+      {
+        "name": "apollo_search_people",
+        "intent": "find_people",
+        "kind": "code",
+        "scope": "pod",
+        "description": "Searches Apollo's people database (mixed_people/search) and returns a normalized list of prospects [{ name, email, jobTitle, linkedinUrl, city, country, company }]. Read-only, no side effects — a discovery primitive a lead-gen playbook composes (search, then resolve-or-create deduplicated entities). NOTE: Apollo often returns a locked placeholder email (email_not_unlocked@domain.com) in search results — passed through as-is; unlocking is a separate billed step not implemented here. Args: { query?: string (keywords), titles?: string[] (job titles, e.g. ['CEO','Head of Growth']), locations?: string[] (e.g. ['France','San Francisco']), page?: number (default 1), perPage?: number (default 10, max 100) }.",
+        "requires": [
+          "apollo_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 45,
+        "parameters": {
+          "query": "string?",
+          "titles": "array?",
+          "locations": "array?",
+          "page": "number?",
+          "perPage": "number?"
+        },
+        "code": "// Search people via Apollo mixed_people/search. Executor wraps this body as\n// (async (args, context) => { <code> }); use args directly and `return`.\n// callProvider('apollo_api','POST','/mixed_people/search',body) injects the\n// vaulted key as `x-api-key: <key>`. Response = { people: [...], contacts: [...] }.\n// A code skill (not declarative) on purpose: a declarative POST is classified a\n// write by the governance-name lint, which would mislabel this `search` verb;\n// a code POST to a /search path is correctly recognized read-only (Exa precedent).\n// Build the body omitting empty optionals — Apollo rejects empty enum values.\nconst pageN = Number(args?.page);\nconst page = Number.isFinite(pageN) ? Math.max(1, Math.trunc(pageN)) : 1;\nconst perN = Number(args?.perPage);\nconst perPage = Number.isFinite(perN) ? Math.max(1, Math.min(100, Math.trunc(perN))) : 10;\n\nconst body = { page, per_page: perPage };\nif (typeof args?.query === 'string' && args.query.trim()) body.q_keywords = args.query.trim();\nif (Array.isArray(args?.titles) && args.titles.length) body.person_titles = args.titles;\nif (Array.isArray(args?.locations) && args.locations.length) body.person_locations = args.locations;\n\nconst res = await callProvider('apollo_api', 'POST', '/mixed_people/search', body);\nif (res?.proposed === true) {\n  return { success: false, proposed: true, proposalId: res?.proposalId ?? null };\n}\nconst payload = res?.body ?? res;\nconst rows = [\n  ...(Array.isArray(payload?.people) ? payload.people : []),\n  ...(Array.isArray(payload?.contacts) ? payload.contacts : []),\n];\nconst results = rows.map((p) => ({\n  name: (p?.name ?? [p?.first_name, p?.last_name].filter(Boolean).join(' ')) || null,\n  email: p?.email ?? null,\n  jobTitle: p?.title ?? null,\n  linkedinUrl: p?.linkedin_url ?? null,\n  city: p?.city ?? null,\n  country: p?.country ?? null,\n  company: p?.organization_name ?? p?.organization?.name ?? null,\n}));\nreturn { query: (typeof args?.query === 'string' ? args.query.trim() : null), page, count: results.length, results };"
+      }
+    ],
+    "provides": [
+      "enrich_entity",
+      "find_people"
+    ]
+  },
+  "dependencies": []
+}