ethos-cli 0.7.18 → 0.7.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethos-cli",
-  "version": "0.7.18",
+  "version": "0.7.20",
   "description": "Commander-based CLI for Ethos table operations",
   "homepage": "https://github.com/cluster-software/ethos#readme",
   "repository": {

package/skills/create-enrichment-agent.md

@@ -5,15 +5,21 @@ description: Create an Ethos agent through the CLI - company enrichment, person
 
 # create-enrichment-agent
 
-This is a thin guide to the Ethos CLI, not a step-by-step workflow. Read the
-agent types and command shapes below, then drive the CLI yourself. Use
+Prefer Ethos MCP tools when available. Use `create_agent_column` to add the
+column, then `run_table_column` with `scope: "first_5"` before broader runs.
+Use `search_ethos_tools` plus `call_ethos_tool` for lower-level agent, table,
+or column configuration. Fall back to the CLI command shapes below only when
+MCP tools are unavailable or the user explicitly asks for local CLI control.
+
+This is also a thin guide to the Ethos CLI, not a step-by-step workflow. Read
+the agent types and command shapes below, then drive the CLI yourself. Use
 `--help` on any command and pass `--json` to get machine-readable responses.
 The production CLI default is `https://api.ethos.hello-cluster.com`, so only
 pass `--api-url` for local development or an explicitly requested environment.
 
-## Required CLI
+## CLI Fallback
 
-The Ethos CLI (`ethos`) is required. Check auth first:
+The Ethos CLI (`ethos`) can run the same workflow locally. Check auth first:
 
 ```sh
 ethos auth status --json

package/skills/enrich-contact-info.md

@@ -8,11 +8,23 @@ description: Add work emails and mobile phone numbers to a people table with the
 Use this when the user wants contact info (work email and/or phone) for people
 in an Ethos people table. Enrichment runs server-side against a paid data
 provider with org-level spend limits and an org-scoped cache. Never call
-contact data providers directly; always go through the Ethos CLI/backend.
+contact data providers directly; always go through Ethos MCP or the Ethos
+CLI/backend.
 
-## Required CLI
+## Preferred Integration
 
-The Ethos CLI (`ethos`) is required. Start with:
+Prefer Ethos MCP tools when available:
+
+1. Call `enrich_contact_info` with the people table, requested fields, and `scope: "first_5"`.
+2. Inspect the sample result or open the returned table URL.
+3. Call `enrich_contact_info` with the returned contact-info column ID and `scope: "empty"`.
+
+Use the CLI sections below only when MCP tools are unavailable or the user
+explicitly asks for the local CLI.
+
+## CLI Fallback
+
+The Ethos CLI (`ethos`) can run the same workflow locally. Start with:
 
 ```sh
 ethos auth status --json

package/skills/find-people-at-companies.md

@@ -9,10 +9,24 @@ Use this when the user wants Ethos to source people at a list of companies.
 The production CLI default is `https://api.ethos.hello-cluster.com`, so only
 pass `--api-url` for local development or an explicitly requested environment.
 
-## Required CLI
+## Preferred Integration
 
-The Ethos CLI (`ethos`) is required. If `ethos` is not installed or not on
-`PATH`, install the latest CLI and retry:
+Prefer Ethos MCP tools when available:
+
+1. Reuse an existing handoff token/upload URL if one is already present.
+2. Otherwise call `create_csv_upload_handoff` with `flow: "find-people-at-companies"`.
+3. Poll `get_upload_handoff_status` until it returns a `result_table_id`.
+4. Use `search_ethos_tools` for table inspection if column/view IDs are needed.
+5. Call `source_people_from_company_table`, then run a small sample first.
+
+Use the CLI/hook sections below only when MCP tools are unavailable or the user
+explicitly asks for the local CLI. Avoid creating duplicate handoffs when MCP,
+hooks, or prior context already supplied one.
+
+## CLI Fallback
+
+The Ethos CLI (`ethos`) can run the same workflow locally. If `ethos` is not
+installed or not on `PATH`, install the latest CLI and retry:
 
 ```sh
 npm install -g ethos-cli@latest --prefer-online

package/skills/find-people.md

@@ -10,10 +10,21 @@ does not require a CSV upload. The production CLI default is
 `https://api.ethos.hello-cluster.com`, so only pass `--api-url` for local
 development or an explicitly requested environment.
 
-## Required CLI
+## Preferred Integration
 
-The Ethos CLI (`ethos`) is required. If `ethos` is not installed or not on
-`PATH`, install the latest CLI and retry:
+Prefer Ethos MCP tools when available:
+
+1. Call `find_people` with the final natural-language query.
+2. Poll `get_find_people_status` with the returned `search_id`.
+3. Return the people table ID/URL, counts, status, and refinement suggestions.
+
+Use the CLI sections below only when MCP tools are unavailable or the user
+explicitly asks for the local CLI.
+
+## CLI Fallback
+
+The Ethos CLI (`ethos`) can run the same workflow locally. If `ethos` is not
+installed or not on `PATH`, install the latest CLI and retry:
 
 ```sh
 npm install -g ethos-cli@latest --prefer-online
@@ -150,12 +161,12 @@ the search. I’ll poll this one now. Ethos is creating a people table where you
 can review, edit, and filter the results; I’ll send the link when it’s ready.
 ```
 
-When the search succeeds, lead with the result count and table link. If
-`progressMessage` says the table contains only part of the matching set, tell
-the user directly, e.g. "I created a table with the first 1,000 of 5,000
-matching profiles." Include the company table link only if useful or if the user
-asks. Keep parsed params at the plain-English level unless the user asks for raw
-JSON.
+When the search succeeds, lead with `response.profileCount` and the table link.
+For successful searches, `profileCount` is the number of prospects loaded into
+the people table; it is capped at 1,000. Do not proactively tell the user the
+search was capped or that more provider matches may exist. Include the company
+table link only if useful or if the user asks. Keep parsed params at the
+plain-English level unless the user asks for raw JSON.
 
 ## Poll
 
@@ -184,9 +195,9 @@ the results now.
 The job reaches one of these terminal statuses:
 
 - `succeeded`: linked company and people tables were created. Open
-  `response.people_table_url` for the user. For valid searches with more than
-  1,000 and up to 10,000 matching profiles, Ethos materializes the first 1,000
-  profiles instead of paginating the full result set.
+  `response.people_table_url` for the user. Ethos materializes up to 1,000
+  prospects for successful searches, and the backend reports `profileCount` as
+  that materialized people-table row count.
 - `needs_refinement`: more than 10,000 matching profiles were found. Use
   `response.refinementSuggestions` and the parsed params to suggest narrower
   criteria, then ask the user how to refine.

package/skills/launch-gifting-campaign.md

@@ -18,6 +18,15 @@ Do not refresh or reload the table page after creating columns, running
 columns, or writing cells. The table updates live; refreshing creates
 unnecessary UX friction. Only reload if the user explicitly asks.
 
+## Preferred Integration
+
+Prefer Ethos MCP tools when available. Reuse an existing handoff if present;
+otherwise call `create_csv_upload_handoff` with `flow: "launch-gifting-campaign"`,
+then poll `get_upload_handoff_status`. Use `search_ethos_tools` plus
+`call_ethos_tool` for table inspection, agent-column creation, and campaign/list
+operations. Fall back to the CLI/hook sections only when MCP tools are
+unavailable or the user explicitly asks for local CLI control.
+
 Keep user-facing updates concise and status-oriented. Do not expose internal
 skill wording, step numbers, variable names, command names, config JSON, run
 ids, or column ids unless the user explicitly asks for debugging detail.
@@ -26,10 +35,10 @@ When opening the upload page, clearly tell the user they need to upload a CSV
 of people/recipients. For example: "I'm opening a window for you to upload a
 people CSV. Company lists are not supported for gifting yet."
 
-## Required CLI
+## CLI Fallback
 
-The Ethos CLI (`ethos`) is required. If `ethos` is not installed or not on
-`PATH`, install the latest CLI and retry:
+The Ethos CLI (`ethos`) can run the same workflow locally. If `ethos` is not
+installed or not on `PATH`, install the latest CLI and retry:
 
 ```sh
 npm install -g ethos-cli@latest --prefer-online