@sellable/mcp 0.1.0

package/skills/building-gtm-tables/references/brief-to-blueprint.md

@@ -0,0 +1,334 @@
+# Brief To Blueprint
+
+Use this recipe to show the reasoning trace before the final JSON. The user
+does not need every internal detail, but the agent should be able to explain why
+each column exists and how it is wired.
+
+## TOC
+
+- [Decomposition recipe](#decomposition-recipe)
+- [Example 1: Rank my prospect list against my ICP](#example-1-rank-my-prospect-list-against-my-icp)
+- [Example 2: Enrich + score + send invite to top-scoring prospects](#example-2-enrich--score--send-invite-to-top-scoring-prospects)
+- [Example 3: Enrich + score + generate approved campaign messages](#example-3-enrich--score--generate-approved-campaign-messages)
+- [Example 4: Pull each prospect's last LinkedIn post and summarize it](#example-4-pull-each-prospects-last-linkedin-post-and-summarize-it)
+
+## Decomposition recipe
+
+1. Identify row inputs. Ask what each row already has: LinkedIn URL, email,
+   company domain, raw JSON, campaign offer id, message text, or post URL.
+2. Pick enrichment recipe. Most prospect-fit workflows use a `http_request`
+   column named "Enrich Prospect" with endpoint `/api/v4/enrich-prospect`.
+3. Pick scoring criteria. If the goal includes ranking, filtering, or deciding
+   who deserves action, add `score_icp_mcp` with a natural-language rubric.
+4. Pick action/generation columns. Use LinkedIn action types for outreach,
+   Generate Message for campaign-attached production messages, and AI Column for
+   custom research/summarization/classification.
+5. Wire dependencies explicitly. Every downstream column's `inputMapping`
+   references the producer by id, and every edge mirrors the dependency.
+6. Treat Enrich Prospect as the baseline producer for Sellable-specific
+   prospect context. `score_icp_mcp.inputMapping.enrichedProspectId` and
+   `generate_message.inputMapping.enrichedProspectId` should point to the
+   `http_request` column named "Enrich Prospect" unless the user says an
+   enriched prospect id already exists.
+
+## Example 1: Rank my prospect list against my ICP
+
+User ask: "Rank my prospect list against my ICP. I have LinkedIn URLs and want a
+score for each row."
+
+Reasoning trace:
+
+- Step 1: row has `linkedin_url`, so the seed input is a `linkedin_url` column.
+- Step 2: ICP judgment needs title, company, seniority, and profile context, so
+  add Enrich Prospect as `http_request` with `/api/v4/enrich-prospect`.
+- Step 3: ranking is required, so add `score_icp_mcp` with user-readable criteria.
+- Step 4: no action or message generation is requested, so stop after scoring.
+- Step 5: wire `score_icp_mcp.inputMapping.enrichedProspectId` to the
+  `enrich_prospect` column id; mirror that as an edge.
+
+Final JSON:
+
+```json
+{
+  "columns": [
+    {
+      "id": "linkedin_url",
+      "type": "linkedin_url",
+      "name": "LinkedIn URL",
+      "config": {}
+    },
+    {
+      "id": "enrich_prospect",
+      "type": "http_request",
+      "name": "Enrich Prospect",
+      "config": {
+        "method": "POST",
+        "endpoint": "/api/v4/enrich-prospect",
+        "body": "{\"linkedinUrl\":\"{{LinkedIn URL}}\"}"
+      },
+      "inputMapping": { "linkedinUrl": "linkedin_url" }
+    },
+    {
+      "id": "score_icp_mcp",
+      "type": "score_icp_mcp",
+      "name": "ICP Score",
+      "config": {
+        "rubric": [
+          "Matches the named buyer persona.",
+          "Company size and segment match the ICP.",
+          "Profile evidence shows ownership of the relevant problem."
+        ]
+      },
+      "inputMapping": { "enrichedProspectId": "enrich_prospect" }
+    }
+  ],
+  "edges": [
+    { "from": "linkedin_url", "to": "enrich_prospect", "via": "linkedinUrl" },
+    {
+      "from": "enrich_prospect",
+      "to": "score_icp_mcp",
+      "via": "enrichedProspectId"
+    }
+  ]
+}
+```
+
+## Example 2: Enrich + score + send invite to top-scoring prospects
+
+User ask: "Enrich this list, score everyone, and send a LinkedIn invite only to
+top-scoring prospects."
+
+Reasoning trace:
+
+- Step 1: row has `linkedin_url`, so use it as the seed and action target.
+- Step 2: score quality depends on profile/company facts, so add Enrich
+  Prospect as `http_request`.
+- Step 3: the action threshold needs a numeric score, so add `score_icp_mcp` and set
+  the rubric from the user's ICP.
+- Step 4: user asked for invites, so add `send_invite`.
+- Step 5: wire enrichment to score, wire LinkedIn URL to invite, and gate invite
+  with `{{score_icp_mcp.result.score}} >= 70`.
+
+Final JSON:
+
+```json
+{
+  "columns": [
+    {
+      "id": "linkedin_url",
+      "type": "linkedin_url",
+      "name": "LinkedIn URL",
+      "config": {}
+    },
+    {
+      "id": "enrich_prospect",
+      "type": "http_request",
+      "name": "Enrich Prospect",
+      "config": {
+        "method": "POST",
+        "endpoint": "/api/v4/enrich-prospect",
+        "body": "{\"linkedinUrl\":\"{{LinkedIn URL}}\"}"
+      },
+      "inputMapping": { "linkedinUrl": "linkedin_url" }
+    },
+    {
+      "id": "score_icp_mcp",
+      "type": "score_icp_mcp",
+      "name": "ICP Score",
+      "config": {
+        "rubric": [
+          "Decision-maker or strong influencer for outbound/GTM tooling.",
+          "Company has an active sales-led or founder-led growth motion.",
+          "Evidence suggests urgency around pipeline quality."
+        ]
+      },
+      "inputMapping": { "enrichedProspectId": "enrich_prospect" }
+    },
+    {
+      "id": "send_invite",
+      "type": "send_invite",
+      "name": "Invite",
+      "config": { "actionConfig": { "actionType": "INVITE" } },
+      "inputMapping": { "linkedinUrl": "linkedin_url" },
+      "runCondition": "{{score_icp_mcp.result.score}} >= 70"
+    }
+  ],
+  "edges": [
+    { "from": "linkedin_url", "to": "enrich_prospect", "via": "linkedinUrl" },
+    {
+      "from": "enrich_prospect",
+      "to": "score_icp_mcp",
+      "via": "enrichedProspectId"
+    },
+    { "from": "linkedin_url", "to": "send_invite", "via": "linkedinUrl" },
+    { "from": "score_icp_mcp", "to": "send_invite", "via": "runCondition" }
+  ]
+}
+```
+
+## Example 3: Enrich + score + generate approved campaign messages
+
+User ask: "For qualified prospects, enrich the profile, score fit, and generate
+the campaign message."
+
+Reasoning trace:
+
+- Step 1: row has `linkedin_url`; the campaign-backed table also has or can
+  receive a `campaign_offer_id`.
+- Step 2: both ICP scoring and message generation need rich prospect context, so
+  add Enrich Prospect as `http_request`.
+- Step 3: add `score_icp_mcp` for the qualification threshold.
+- Step 4: add `generate_message` for the production message-generation flow.
+- Step 5: wire both `score_icp_mcp.inputMapping.enrichedProspectId` and
+  `generate_message.inputMapping.enrichedProspectId` to `enrich_prospect`.
+
+Final JSON:
+
+```json
+{
+  "columns": [
+    {
+      "id": "linkedin_url",
+      "type": "text",
+      "name": "LinkedIn URL",
+      "config": {}
+    },
+    {
+      "id": "campaign_offer_id",
+      "type": "text",
+      "name": "Campaign Offer ID",
+      "config": {}
+    },
+    {
+      "id": "enrich_prospect",
+      "type": "http_request",
+      "name": "Enrich Prospect",
+      "config": {
+        "inputMapping": {
+          "method": { "value": "POST" },
+          "endpoint": { "value": "/api/v4/enrich-prospect" },
+          "body": { "value": "{\"linkedinUrl\":\"{{LinkedIn URL}}\"}" }
+        }
+      },
+      "inputMapping": { "linkedinUrl": "linkedin_url" }
+    },
+    {
+      "id": "score_icp_mcp",
+      "type": "score_icp_mcp",
+      "name": "ICP Score",
+      "config": {
+        "rubric": [
+          {
+            "checkName": "buyer_fit",
+            "criterion": "Prospect matches the target buyer profile.",
+            "description": "Role, seniority, and company context match the ICP.",
+            "reason": "Message generation should focus on qualified buyers.",
+            "isRequiredCheck": "true",
+            "allowPartialCredit": "true"
+          }
+        ]
+      },
+      "inputMapping": { "enrichedProspectId": "enrich_prospect" }
+    },
+    {
+      "id": "generate_message",
+      "type": "generate_message",
+      "name": "Generate Message",
+      "config": {},
+      "inputMapping": {
+        "campaignOfferId": "campaign_offer_id",
+        "enrichedProspectId": "enrich_prospect"
+      },
+      "runCondition": "{{ICP Score.score}} >= 70"
+    }
+  ],
+  "edges": [
+    { "from": "linkedin_url", "to": "enrich_prospect", "via": "linkedinUrl" },
+    {
+      "from": "enrich_prospect",
+      "to": "score_icp_mcp",
+      "via": "enrichedProspectId"
+    },
+    {
+      "from": "campaign_offer_id",
+      "to": "generate_message",
+      "via": "campaignOfferId"
+    },
+    {
+      "from": "enrich_prospect",
+      "to": "generate_message",
+      "via": "enrichedProspectId"
+    },
+    {
+      "from": "score_icp_mcp",
+      "to": "generate_message",
+      "via": "runCondition"
+    }
+  ]
+}
+```
+
+## Example 4: Pull each prospect's last LinkedIn post and summarize it
+
+User ask: "For every prospect, pull their recent LinkedIn activity and summarize
+the most relevant post in one line."
+
+Reasoning trace:
+
+- Step 1: row has `linkedin_url`; the row may also have a text instruction for
+  what relevance means.
+- Step 2: no ICP score is requested; enrichment may be unnecessary if the AI
+  prompt can search from the LinkedIn URL directly.
+- Step 3: no scoring criteria are needed.
+- Step 4: use `ai_column` because the task is custom research and summarization.
+- Step 5: wire the LinkedIn URL and optional prompt text to the AI column so
+  missing seed data is visible during verification.
+
+Final JSON:
+
+```json
+{
+  "columns": [
+    {
+      "id": "linkedin_url",
+      "type": "linkedin_url",
+      "name": "LinkedIn URL",
+      "config": {}
+    },
+    {
+      "id": "research_focus",
+      "type": "text",
+      "name": "Research Focus",
+      "config": {}
+    },
+    {
+      "id": "linkedin_post_summary",
+      "type": "ai_column",
+      "name": "LinkedIn Post Summary",
+      "config": {
+        "aiConfig": {
+          "modelName": "google/gemini-3.1-flash-lite-preview",
+          "systemPrompt": "Use only observable public LinkedIn activity.",
+          "userPrompt": "Find recent LinkedIn activity for {{LinkedIn URL}}. Focus on {{Research Focus}}. Return one concise sentence.",
+          "outputFields": [{ "name": "summary", "type": "text" }],
+          "enableWebSearch": true,
+          "maxSearchQueries": 3
+        },
+        "processing": { "autoUpdate": true }
+      },
+      "inputMapping": {
+        "linkedinUrl": "linkedin_url",
+        "focus": "research_focus"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "from": "linkedin_url",
+      "to": "linkedin_post_summary",
+      "via": "linkedinUrl"
+    },
+    { "from": "research_focus", "to": "linkedin_post_summary", "via": "focus" }
+  ]
+}
+```

package/skills/building-gtm-tables/references/column-type-catalog.md

@@ -0,0 +1,318 @@
+# Column Type Catalog
+
+Display names in this catalog are sourced from
+`getColumnTypeConfig(type).displayName`. Do not paraphrase them.
+
+## TOC
+
+- [Lead Data](#lead-data)
+- [Enrichment](#enrichment)
+- [Scoring](#scoring)
+- [LinkedIn Actions](#linkedin-actions)
+- [Generation](#generation)
+- [Data & Logic](#data--logic)
+
+## Lead Data
+
+### Select
+
+- type: `select`
+- displayName: `Select`
+- category: Lead Data
+- inputs: `options` required text, comma-separated list of allowed values.
+- outputs: selected option value.
+- when to use: Use for categorical row state such as channel, tier, or manual review labels.
+- when NOT to use: Do not use for free-form notes or generated classifications with unknown labels.
+
+### Sequence Status
+
+- type: `sequence_status`
+- displayName: `Sequence Status`
+- category: Lead Data
+- inputs: `options` required text, usually system-owned defaults.
+- outputs: current sequence state.
+- when to use: Use when a sequence pipeline needs a visible state column.
+- when NOT to use: Do not use as an action executor; it records state only.
+
+### Reply Sentiment
+
+- type: `reply_sentiment`
+- displayName: `Reply Sentiment`
+- category: Lead Data
+- inputs: `options` required text, usually interested/not_interested/out_of_office/question/neutral/negative.
+- outputs: sentiment label.
+- when to use: Use for reply triage state after messages start receiving responses.
+- when NOT to use: Do not use for ICP fit scoring; use `score_icp_mcp` for prospect fit.
+
+### Date/Time
+
+- type: `datetime`
+- displayName: `Date/Time`
+- category: Lead Data
+- inputs: none.
+- outputs: ISO-like date/time value.
+- when to use: Use for system-owned scheduling timestamps.
+- when NOT to use: Do not use to wait; use `wait` for sequence timing.
+
+### Next Action
+
+- type: `next_action_at`
+- displayName: `Next Action`
+- category: Lead Data
+- inputs: none.
+- outputs: next scheduled action timestamp.
+- when to use: Use when the sequence engine needs a visible next-action time.
+- when NOT to use: Do not hand-author this as a scoring or enrichment input.
+
+### Sent At
+
+- type: `sent_at`
+- displayName: `Sent At`
+- category: Lead Data
+- inputs: none.
+- outputs: sent timestamp.
+- when to use: Use to display when a LinkedIn action or message was sent.
+- when NOT to use: Do not use as a delay mechanism; use `wait`.
+
+### LinkedIn URL
+
+- type: `linkedin_url`
+- displayName: `LinkedIn URL`
+- category: Lead Data
+- inputs: none; user or import supplies the cell value.
+- outputs: prospect LinkedIn profile URL string.
+- when to use: Use as the canonical prospect identity input for enrichment and LinkedIn actions.
+- when NOT to use: Do not put post URLs here; use the action-specific post URL mapping.
+
+### JSON
+
+- type: `json`
+- displayName: `JSON`
+- category: Lead Data
+- inputs: none; user, import, or webhook supplies structured JSON.
+- outputs: JSON object or array.
+- when to use: Use when a row carries structured payload data.
+- when NOT to use: Do not use when a typed column with known inputs exists.
+
+### Example
+
+- type: `example_checkbox`
+- displayName: `Example`
+- category: Lead Data
+- inputs: none.
+- outputs: boolean marker for style examples.
+- when to use: Use to mark rows as AI style examples for message-generation flows.
+- when NOT to use: Do not use as a general pass/fail gate; use `checkbox`.
+
+### Inbound Webhook
+
+- type: `inbound_webhook`
+- displayName: `Inbound Webhook`
+- category: Lead Data
+- inputs: none.
+- outputs: received JSON payload and webhook metadata.
+- when to use: Use when rows are populated by external webhook events.
+- when NOT to use: Do not use for polling APIs; use `http_request`.
+
+## Enrichment
+
+### Enrich Prospect preset
+
+- type: `http_request`
+- displayName: `HTTP Request`
+- category: Enrichment preset
+- inputs: `method` POST, `endpoint` `/api/v4/enrich-prospect`, body mapped from `linkedin_url`.
+  Store body as a JSON string, matching the app UI: `{"linkedinUrl":"{{linkedin_url}}"}`.
+- outputs: root `id` (the EnrichedProspect id), profile fields, company fields, and HTTP metadata from the enrichment endpoint.
+- when to use: Use this named `http_request` column as "Enrich Prospect" before `score_icp_mcp`, Generate Message, or action routing that needs profile/company facts.
+- when NOT to use: Do not invent an `enrich_person` type; deprecated enrichment types migrate to `http_request`.
+
+## Scoring
+
+### ICP Rubric Score
+
+- type: `score_icp_mcp`
+- displayName: `MCP ICP Score`
+- category: Scoring
+- purpose: MCP-safe AI ICP scorer for new blueprints. It is separate from
+  legacy `score_icp`, which belongs to older saved tables and a different config
+  contract.
+- inputs: optional `enrichedProspectId` from Enrich Prospect; optional `linkedinUrl` fallback.
+- canonical wiring: in blueprint form use
+  `"inputMapping": { "enrichedProspectId": "enrich_prospect" }`; the commit
+  tool must materialize it as `{{Enrich Prospect.id}}` using
+  the real column id.
+- outputs: `score`, criteria-level reasoning, and fit evidence.
+- when to use: Use when the table must rank or qualify prospects against natural-language ICP criteria.
+- when NOT to use: Do not use legacy `score_icp` or the old
+  `score_icp_rubric` alias in MCP blueprints. Do not use this for
+  deterministic boolean checks; use `checkbox` or `formula`.
+
+## LinkedIn Actions
+
+### Check Open Profile
+
+- type: `is_open_profile`
+- displayName: `Check Open Profile`
+- category: LinkedIn Actions
+- inputs: required `linkedin_url`.
+- outputs: boolean open-profile decision and lookup metadata.
+- when to use: Use before selecting open-profile InMail behavior.
+- when NOT to use: Do not use to check first-degree connection; use `check_connection`.
+
+### Check Connection
+
+- type: `check_connection`
+- displayName: `Check Connection`
+- category: LinkedIn Actions
+- inputs: required `lead_linkedin_id`.
+- outputs: connection status.
+- when to use: Use before choosing DM versus invite/InMail paths.
+- when NOT to use: Do not use with raw profile URLs unless a producer resolves the LinkedIn id first.
+
+### LinkedIn Action
+
+- type: `action`
+- displayName: `LinkedIn Action`
+- category: LinkedIn Actions
+- inputs: optional configured `actionType`.
+- outputs: action execution status and event-wait metadata.
+- when to use: Use for generic or template-driven LinkedIn action execution.
+- when NOT to use: Prefer the specialized action types below when the user asked for a specific action.
+
+### Invite
+
+- type: `send_invite`
+- displayName: `Invite`
+- category: LinkedIn Actions
+- inputs: required `linkedinUrl`; optional `connectionNote`.
+- outputs: invite send status and connection-accept wait state.
+- when to use: Use to send a LinkedIn connection request after qualification.
+- when NOT to use: Do not use for already-connected prospects; use `send_dm`.
+
+### InMail (Open Profile)
+
+- type: `send_inmail_open`
+- displayName: `InMail (Open Profile)`
+- category: LinkedIn Actions
+- inputs: required `linkedinUrl`, `subject`, and `message`.
+- outputs: open-profile InMail status and fallback metadata.
+- when to use: Use when Check Open Profile says free InMail is available.
+- when NOT to use: Do not use as the first fallback for closed profiles; use `send_inmail_closed`.
+
+### InMail (Closed Profile)
+
+- type: `send_inmail_closed`
+- displayName: `InMail (Closed Profile)`
+- category: LinkedIn Actions
+- inputs: required `linkedinUrl`, `subject`, and `message`.
+- outputs: paid InMail status and accept wait state.
+- when to use: Use when the prospect is not open-profile and paid credits are intended.
+- when NOT to use: Do not use when the outreach path should avoid paid InMail credits.
+
+### DM
+
+- type: `send_dm`
+- displayName: `DM`
+- category: LinkedIn Actions
+- inputs: required `linkedinUrl` and `message`.
+- outputs: DM send status and reply wait state.
+- when to use: Use only after the prospect is already connected.
+- when NOT to use: Do not use for cold prospects who require invite or InMail first.
+
+### View Profile
+
+- type: `view_profile`
+- displayName: `View Profile`
+- category: LinkedIn Actions
+- inputs: required `linkedinUrl`.
+- outputs: profile-view action status.
+- when to use: Use as a warm-up action before outreach.
+- when NOT to use: Do not use as a substitute for enrichment; it does not return profile data.
+
+### React & Comment
+
+- type: `react_and_comment`
+- displayName: `React & Comment`
+- category: LinkedIn Actions
+- inputs: required post URL as `linkedinUrl`, required `message`, optional `reactionType`.
+- outputs: reaction/comment action status.
+- when to use: Use when the table has a specific LinkedIn post and approved comment text.
+- when NOT to use: Do not use with profile URLs; it expects a post URL.
+
+### Wait
+
+- type: `wait`
+- displayName: `Wait`
+- category: LinkedIn Actions
+- inputs: none; duration lives in config.
+- outputs: scheduled/deferred wait state.
+- when to use: Use to pause a sequence between actions.
+- when NOT to use: Do not force-run waits during verification; pass the column id in `skipColumnIds`.
+
+## Generation
+
+### Generate Message
+
+- type: `generate_message`
+- displayName: `Generate Message`
+- category: Generation
+- inputs: required `campaignOfferId`, required `enrichedProspectId`, optional `bypassCache`.
+- canonical wiring: use the campaign-backed table's campaign offer id for
+  `campaignOfferId`, and map `enrichedProspectId` from Enrich Prospect's
+  root `id` output field, not from the whole HTTP result object.
+- outputs: generated message fields from the locked built-in flow.
+- when to use: Use when the table is attached to a campaign offer and needs the production message-generation flow.
+- when NOT to use: Do not use for ad hoc text summarization; use `ai_column`.
+
+## Data & Logic
+
+### AI Column
+
+- type: `ai_column`
+- displayName: `AI Column`
+- category: Data & Logic
+- inputs: prompt templates in `config.aiConfig.userPrompt`; no row input schema.
+- outputs: configured `outputFields`, defaulting to `response`.
+- when to use: Use as an escape hatch for custom research, summarization, or classification that does not deserve a dedicated column type.
+- when NOT to use: Do not use where a deterministic or first-party typed column exists.
+
+### Checkbox
+
+- type: `checkbox`
+- displayName: `Checkbox`
+- category: Data & Logic
+- inputs: none by default; can map from another source value.
+- outputs: boolean value.
+- when to use: Use for explicit pass/fail markers or manual review state.
+- when NOT to use: Do not use to execute logic that should be reproducible in `formula`.
+
+### Formula
+
+- type: `formula`
+- displayName: `Formula`
+- category: Data & Logic
+- inputs: required `expression`.
+- outputs: evaluated expression result.
+- when to use: Use for deterministic transformations of existing row values.
+- when NOT to use: Do not use for external calls or AI judgment.
+
+### HTTP Request
+
+- type: `http_request`
+- displayName: `HTTP Request`
+- category: Data & Logic
+- inputs: required `method`, required `endpoint`, optional `headers`, optional `body`.
+- outputs: HTTP status, response body, and metadata; Enrich Prospect also returns root `id` as the EnrichedProspect id.
+- when to use: Use for REST API calls, including the canonical "Enrich Prospect" preset at `/api/v4/enrich-prospect`.
+- when NOT to use: Do not use when a first-party typed column already handles the action.
+
+### Text
+
+- type: `text`
+- displayName: `Text`
+- category: Data & Logic
+- inputs: none; user, import, or formula-derived value supplies content.
+- outputs: string value.
+- when to use: Use for static text fields, labels, notes, URLs that are not the canonical LinkedIn URL, or intermediate values.
+- when NOT to use: Do not use as a typed action or enrichment column.