leads-cli 0.1.0__py3-none-any.whl

company_discovery/bundled_skills/company-discovery-operator/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: company-discovery-operator
+description: Validate, execute, inspect, rerun, and explain Company Discovery CLI runs from an existing company_search_spec.json. Use when a user asks an agent to run company discovery, find companies from a prepared spec, inspect a discovered domain, export a run, or summarize selected, reserve, and rejected company results. Do not rewrite the ICP or work on contacts.
+---
+
+# Operate Company Discovery
+
+Run company discovery from an existing spec without silently changing it.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- Company specs normally live in `specs/companies/`; validate the exact spec path before running.
+- Company discovery artifacts are saved under `runs/<company-discover-id>/` with `selected.csv`,
+  `reserve.csv`, `rejected.csv`, `summary.md`, and `run.json`.
+- Config lives in `config/config.toml`; secrets live in `config/secrets.toml`; never expose secret
+  values.
+- The memory database is `data/company_memory.db`; treat CLI output and saved artifacts as the
+  normal interface.
+- Backups are under `backups/`; CLI diagnostics are in `logs/leads.log`; installed skill metadata
+  is under `skills/`.
+- Useful setup/maintenance commands: `leads init`, `leads version`, `leads doctor`,
+  `leads update --check`, `leads migrate --check`, and `leads skills status`.
+
+## New discovery
+
+1. Locate the requested `company_search_spec.json`.
+2. Run `leads companies validate-spec --spec <path>`.
+3. Report material open modes shown by validation: national geography, no size filter, or no custom exclusions.
+4. State the novelty policy before running: `unused_memory` searches unused memory first,
+   `only_new` bypasses memory candidates and suppresses known domains, and `full_memory` permits
+   reuse of previously selected companies. If omitted, the policy is `unused_memory`.
+5. For multi-vertical specs, report the balance mode and treat each vertical as an independent memory and external-search lane.
+6. Report the external search budget before running. If omitted, use the normalized defaults:
+   `external_search.exa_searches = 8` and `external_search.results_per_search = 5`.
+7. Run `leads companies discover --spec <path>`. Add `--verbose` only when detailed queries and candidate decisions help diagnose the run. Before launching the command, set a large tool-window timeout, around 10 minutes, so live discovery can finish without being cut off.
+8. Let the command finish. Do not launch a duplicate while the original process is active.
+9. Read the final counts and Markdown summary path.
+10. Summarize memory reuse, known-domain suppression for `only_new`, external-search volume,
+   selected/reserve/rejected counts, per-vertical outcomes, and any shortfall.
+11. Present the results with:
+   - one compact count line for all buckets;
+   - one table for `selected`;
+   - one table for `reserve`.
+   Do not show `rejected` rows by default unless the user asks, or unless there are no useful
+   results and the failure reasons are the main thing that matters.
+12. Keep the default tables compact and systematic. Use these columns when they are available:
+   `Company | Domain | Vertical | State | Size | Fit | Source | Notes`
+13. Show at most about 15 rows per table by default. If there are more, say that additional rows
+   are available in the exported artifacts.
+
+Discovery stops after saving and reporting its run ID. Never start enrichment through a discovery
+flag. When the user also requests enrichment, finish discovery first and pass its saved run ID to
+the separate enrichment workflow.
+
+## Follow-up operations
+
+- Inspect a run with `leads companies show-run <run-id>`.
+- Inspect one domain with `leads companies inspect <run-id> --domain <domain>`.
+- Regenerate artifacts with `leads companies export <run-id>`.
+- Repeat the exact prior spec and its novelty policy using `leads companies rerun <run-id>`.
+
+## Guardrails
+
+- Do not edit or replace the spec unless the user asks to change the ICP.
+- Do not hide a missing constraint or selected-count shortfall.
+- Do not describe reserve companies as confirmed selections.
+- Explain deterministic hygiene rejections separately from LLM ICP judgments when relevant.
+- Treat the saved run and artifacts as authoritative; do not infer companies from terminal snippets alone.
+- Never expose API keys or raw environment values.

company_discovery/bundled_skills/company-discovery-operator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Company Discovery Operator"
+  short_description: "Run and explain company discovery searches"
+  default_prompt: "Use $company-discovery-operator to run this company discovery spec and summarize the results."

company_discovery/bundled_skills/company-enrichment-operator/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: company-enrichment-operator
+description: Enrich company profiles from a completed Company Discovery run. Use when a user asks to enrich selected or reserve companies, continue from discovery to enrichment, retrieve company phone/address/independence, inspect enrichment evidence, refresh stale enrichment facts, or export ready/review/blocked company results. This skill operates on companies only, never contacts.
+---
+
+# Operate Company Enrichment
+
+Consume a completed discovery run. Do not ask the user to restate its ICP or reconstruct input from
+`selected.csv`; the database record is authoritative.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- Company discovery runs live at `runs/<company-discover-id>/`.
+- Company enrichment artifacts live at
+  `runs/<company-discover-id>/enrich/<company-enrich-id>/` with `enriched.csv`, `review.csv`,
+  `blocked.csv`, `summary.md`, and `run.json`.
+- The database is `data/company_memory.db`; use `leads companies show-run`,
+  `show-enrichment`, and inspect commands before direct DB inspection.
+- Config is in `config/config.toml`; secrets are in `config/secrets.toml`; never expose secret
+  values.
+- Backups are under `backups/`; CLI diagnostics are in `logs/leads.log`; installed skill metadata
+  is under `skills/`; specs live under `specs/companies/` and `specs/contacts/`.
+- Useful setup/maintenance commands: `leads init`, `leads version`, `leads doctor`,
+  `leads update --check`, `leads migrate --check`, and `leads skills status`.
+
+## Standard workflow
+
+1. Identify the discovery run ID. Default to its `selected` bucket.
+2. Run `leads companies show-run <discovery-run-id>` when its status or result count is unclear.
+3. Explain that name, domain, vertical, geography, employee estimate, and ownership type are retained
+   from discovery. Enrichment targets LinkedIn company profile, phone, complete address, and
+   independence.
+4. Run `leads companies enrich <discovery-run-id>`.
+5. Read the final counts and artifact path. Report inherited facts, memory reuse, website retrieval,
+   fallback searches, and ready/review/blocked totals.
+   The returned enrichment run ID is random and prefixed, like `company-enrich-a1b2c3d4e5f6`.
+6. Treat `enriched.csv` as the clean deliverable, `review.csv` as unresolved work, `blocked.csv` as
+   conflicts, and `run.json` as the provenance and decision trace.
+7. Present the results with:
+   - one compact count line for all outcomes;
+   - one table for `ready`;
+   - one table for `review`.
+   Do not show `blocked` rows by default unless the user asks, or unless there are no useful
+   results and the blocking reasons are what the user needs next.
+8. Keep the default tables compact and systematic. Use these columns when they are available:
+   `Company | Domain | Vertical | Phone | City | State | LinkedIn | Independence | Outcome | Notes`
+9. Show at most about 15 rows per table by default. If there are more, say that additional rows
+   are available in the exported artifacts.
+
+For a new search followed by enrichment, always use two separate commands:
+
+```bash
+leads companies discover --spec <spec-path>
+leads companies enrich <discovery-run-id>
+```
+
+Wait for discovery to finish and use the exact run ID it returns. Never represent enrichment as a
+discovery option.
+
+## Options
+
+- Use `--bucket reserve` only when the user asks to enrich reserve companies.
+- Use `--limit N` for an explicitly bounded run.
+- Use `--refresh contact` to refetch LinkedIn, phone, and location.
+- Use `--refresh independence` to rerun only the parent/franchise check.
+- Use `--refresh all` to ignore all fresh enrichment memory.
+- Use `--allow-unknown-independence` only when the user accepts complete contact profiles whose
+  independence could not be proven. Without it, those companies go to review.
+
+## Follow-up operations
+
+- Show a run with `leads companies show-enrichment <company-enrich-id>`.
+- Inspect provenance and trace with
+  `leads companies inspect-enrichment <company-enrich-id> --domain <domain>`.
+- Regenerate artifacts with `leads companies export-enrichment <company-enrich-id>`.
+
+## Guardrails
+
+- Never treat `private`, `privately held`, LLC, partnership, or corporation as proof of independence.
+- Explicit franchise, parent, subsidiary, division, or acquisition evidence blocks the company.
+- If the discovery spec lists `family_owned` under `exclude.structured.ownership_signals`, explicit
+  family-owned evidence blocks the company as a fit conflict. Without that requested exclusion,
+  family-owned remains valid positive evidence of independence.
+- Absence of franchise language is not proof; unresolved independence remains `unknown`.
+- Never merge address pieces from separate offices. The selected address must be one complete block
+  and, for state-scoped discovery, must be in the inherited state.
+- Save only LinkedIn company profiles under `/company/`. Never save personal profiles, jobs, posts,
+  or search pages. Prefer links found directly on the official company website.
+- Do not silently replace discovery facts. Report identity, geography, and fit conflicts.
+- Do not refresh employee data during the default pass; discovery already supplied it.
+- Never expose API keys or raw environment values.

company_discovery/bundled_skills/company-enrichment-operator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Company Enrichment Operator"
+  short_description: "Enrich selected companies from a discovery run"
+  default_prompt: "Use $company-enrichment-operator to enrich selected companies from this discovery run and summarize ready, review, and blocked results."

company_discovery/bundled_skills/company-search-spec-writer/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: company-search-spec-writer
+description: Turn natural-language company targeting or ICP requests into strict company_search_spec.json files for the Company Discovery CLI. Use when a user asks to find target companies, define a company ICP, prepare a company search, or translate company criteria such as vertical, geography, employee size, exclusions, and novelty into a runnable spec. Do not use for contact or person searches.
+---
+
+# Write a Company Search Spec
+
+Create one `company_search_spec.json` under the Leads workspace unless the user gives another path.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- Write company specs to `specs/companies/`, for example
+  `specs/companies/company_search_spec.json`.
+- Contact specs belong in `specs/contacts/`; do not write contact specs here.
+- Runtime config is in `config/config.toml`; secrets are in `config/secrets.toml`; never expose
+  secret values.
+- The SQLite memory DB is `data/company_memory.db`; use CLI commands rather than editing it.
+- Run artifacts are saved under `runs/`; backups are saved under `backups/`; CLI diagnostics are in
+  `logs/leads.log`; installed skill metadata lives under `skills/`.
+- Useful setup/maintenance commands: `leads init`, `leads version`, `leads doctor`,
+  `leads update --check`, `leads migrate --check`, and `leads skills status`.
+
+## Workflow
+
+1. Extract only company-level criteria the user actually supplied.
+2. Set `version` to `1` and require a positive `count`.
+3. Use `verticals` for every new spec. Add one entry per requested vertical; multiple entries mean
+   OR (separate company groups), never companies that must match every vertical.
+4. Each vertical should always use one simple shape: `key`, `label`, and optional query hints.
+   Use a lowercase stable key.
+5. Add `search_terms` only when the vertical is niche, ambiguous, or user wording needs stronger
+   search hints. Add `exclude_terms` only when a few obvious search-time negatives help reduce
+   noise. Do not invent ICP constraints.
+6. Encode broad US geography as `{"country": "US", "states": []}`. Use two-letter uppercase state codes when states are requested.
+7. Use an empty `company_size` object when no employee range was given. Never invent employee limits.
+8. Use empty arrays for omitted include/exclude criteria. When the user explicitly excludes family
+   businesses, set `exclude.structured.ownership_signals` to `["family_owned"]`. This tells enrichment
+   to block a company when official-site or corroborating evidence identifies it as family-owned.
+   Never invent this exclusion.
+9. Default `novelty_mode` to `unused_memory`. This searches memory first but excludes every company
+   that has ever been selected. Use `only_new` when the user wants external discovery only; it skips
+   memory candidates and excludes known domains returned by search. Use `full_memory` only when the
+   user explicitly permits reusing companies selected in prior runs.
+10. Default `reserve_ratio` to `0.5`; this controls output capacity, not ICP fit.
+11. Default `balance_mode` to `soft` for multiple verticals. Use `strict` only when equal caps matter more than reaching the requested count, and `none` only when distribution does not matter.
+12. Add `external_search` to every new spec. Default to `{"exa_searches": 8, "results_per_search": 5}` unless the user asks for a broader or cheaper search. `exa_searches` is the number of Exa searches per active vertical/lane; `results_per_search` is the number of Exa results requested by each search.
+13. Write JSON, then run `leads companies validate-spec --spec <spec-path>`.
+14. Fix validation errors before returning. Do not run discovery unless the user asked for it.
+
+## Contract
+
+Use this shape and omit no top-level fields except those with documented defaults:
+
+```json
+{
+  "version": 1,
+  "count": 50,
+  "verticals": [
+    {"key": "construction", "label": "Construction"},
+    {"key": "healthcare", "label": "Healthcare"}
+  ],
+  "geography": {"country": "US", "states": ["TX"]},
+  "company_size": {"employee_min": 20, "employee_max": 100},
+  "include": {"keywords": [], "subtypes": []},
+  "exclude": {
+    "keywords": [],
+    "ownership_types": [],
+    "company_patterns": [],
+    "structured": {"ownership_signals": []}
+  },
+  "novelty_mode": "unused_memory",
+  "reserve_ratio": 0.5,
+  "balance_mode": "soft",
+  "external_search": {
+    "exa_searches": 8,
+    "results_per_search": 5
+  }
+}
+```
+
+Allowed novelty values are `unused_memory`, `only_new`, and `full_memory`.
+
+- `unused_memory` (default): search memory first, but never select a company that was selected before.
+- `only_new`: do not source candidates from memory and discard external results whose domains are already known.
+- `full_memory`: search all matching memory, including companies selected in prior runs.
+Allowed balance values are `soft`, `strict`, and `none`.
+`external_search.exa_searches` may be 1-20. `external_search.results_per_search` may be
+1-100. Keep the default `8` and `5` unless the user asks to make discovery broader, narrower,
+cheaper, or more exhaustive.
+
+For a niche or ambiguous vertical, add query hints like:
+
+```json
+{
+  "key": "marine-surveying",
+  "label": "Marine Surveying",
+  "search_terms": ["marine surveying", "vessel inspection", "cargo survey"],
+  "exclude_terms": ["software", "directory", "marketplace"]
+}
+```
+
+Allowed structured ownership signals are `family_owned`, `franchise`, `parent`, `subsidiary`,
+`division`, and `acquired`. When a size bound is one-sided, include only the known bound. When
+exclusions are omitted, keep all exclusion arrays empty. Preserve the user's ambiguity instead of
+silently tightening the ICP. Old specs that still use `mode`, `seed_terms`, or `anti_terms` remain
+valid, but new specs should not emit them.

company_discovery/bundled_skills/company-search-spec-writer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Company Search Spec Writer"
+  short_description: "Turn company ICP requests into valid specs"
+  default_prompt: "Use $company-search-spec-writer to turn my company targeting request into a validated discovery spec."

company_discovery/bundled_skills/contact-discovery-operator/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: contact-discovery-operator
+description: Validate, execute, inspect, export, and explain live contact discovery from an existing contact_search_spec.json. Use when a user asks an agent to find current role-matched people at companies from a completed enrichment run or review a prior contact discovery run. Use the separate contact-enrichment-operator skill for Apollo email or phone enrichment.
+---
+
+# Operate Contact Discovery
+
+Find current people at already-enriched companies without changing the saved company scope.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- Contact specs normally live in `specs/contacts/`; validate the exact spec path before running.
+- Contact discovery artifacts live at
+  `runs/<company-discover-id>/enrich/<company-enrich-id>/contacts/<contact-discover-id>/`
+  with `accepted.csv`, `review.csv`, `rejected.csv`, `summary.md`, and `run.json`.
+- The source company enrichment run lives under
+  `runs/<company-discover-id>/enrich/<company-enrich-id>/`.
+- Config is in `config/config.toml`; secrets are in `config/secrets.toml`; never expose secret
+  values.
+- The memory database is `data/company_memory.db`; use `leads contacts show-run` and inspect
+  commands before direct DB inspection.
+- Backups are under `backups/`; CLI diagnostics are in `logs/leads.log`; installed skill metadata
+  is under `skills/`.
+- Useful setup/maintenance commands: `leads init`, `leads version`, `leads doctor`,
+  `leads update --check`, `leads migrate --check`, and `leads skills status`.
+
+## New Discovery
+
+1. Locate the requested `contact_search_spec.json`.
+2. Run `leads contacts validate-spec --spec <path>`.
+3. Confirm the source company enrichment run, bucket, optional domain subset, roles, and caps.
+4. Run `leads contacts discover --spec <path>`.
+5. Let the command finish; do not launch a duplicate while it is active.
+6. Report the contact run ID, companies loaded, memory reuse, live-web queries, and
+   accepted/review/rejected counts.
+7. Read the saved summary or `run.json` when explaining why people were accepted or held for
+   review. Terminal progress is not the authoritative record.
+8. Present the results with:
+   - one compact count line for all verdicts;
+   - one table for `accepted`;
+   - one table for `review`.
+   Do not show `rejected` rows by default unless the user asks, or unless there are no useful
+   results and the rejection reasons are the important output.
+9. Keep the default tables compact and systematic. Use these columns when they are available:
+   `Company | Contact | Title | Role Key | LinkedIn | Status | Source | Notes`
+10. Show at most about 15 rows per table by default. If there are more, say that additional rows
+   are available in the exported artifacts.
+
+The command checks fresh contact memory independently for every company and role. It searches Exa
+only for remaining per-role gaps, then verifies identity, current-company evidence, and title fit.
+
+## Follow-up Operations
+
+- Show a run with `leads contacts show-run <contact-run-id>`.
+- Inspect one person with `leads contacts inspect <contact-run-id> --person "Jane Smith"`.
+- Regenerate artifacts with `leads contacts export <contact-run-id>`.
+
+## Interpret Results
+
+- `accepted.csv`: clear identity, explicit current-company tie, and explicit requested-role match.
+- `review.csv`: plausible evidence that is not strong enough for automatic acceptance, including
+  valid matches beyond a per-company role cap.
+- `rejected.csv`: wrong company, former employee, wrong role, or ambiguous identity.
+- `run.json`: complete role decisions, evidence, source URLs, query results, and memory/live source.
+
+The CSV schema intentionally includes blank `email` and `phone` columns so later enrichment can
+fill the same client-facing shape. Never describe those blank fields as failed enrichment.
+
+## Guardrails
+
+- Do not edit the spec during execution.
+- Do not search arbitrary companies outside the source enrichment run.
+- Do not describe a review contact as confirmed.
+- Do not infer current employment from Apollo or old databases.
+- Do not silently continue into contact enrichment; invoke the separate operator workflow when the
+  user asks for email or phone data.
+- Never expose API keys or raw environment values.

company_discovery/bundled_skills/contact-discovery-operator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Contact Discovery Operator"
+  short_description: "Run and explain live contact discovery"
+  default_prompt: "Use $contact-discovery-operator to run this contact discovery spec and summarize the results."

company_discovery/bundled_skills/contact-enrichment-operator/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: contact-enrichment-operator
+description: Enrich accepted live-web contact discoveries with Apollo email and phone data, inspect provider mismatches, and export outreach-ready results. Use when a user asks to find contact details, emails, or phone numbers for people in a completed contact discovery run, rerun Apollo enrichment, or review a prior contact enrichment run.
+---
+
+# Operate Contact Enrichment
+
+Use Apollo only after contact discovery has established the person's identity, current company,
+and requested-role fit.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- Contact discovery artifacts live under
+  `runs/<company-discover-id>/enrich/<company-enrich-id>/contacts/<contact-discover-id>/`.
+- Contact enrichment artifacts live under
+  `runs/<company-discover-id>/enrich/<company-enrich-id>/contacts/<contact-discover-id>/enrich/<contact-enrich-id>/`
+  with `ready.csv`, `review.csv`, `blocked.csv`, `summary.md`, and `run.json`.
+- Config is in `config/config.toml`; secrets are in `config/secrets.toml`; never expose API keys or
+  webhook values.
+- The memory database is `data/company_memory.db`; use `leads contacts show-run`,
+  `show-enrichment`, and inspect commands before direct DB inspection.
+- Backups are under `backups/`; CLI diagnostics are in `logs/leads.log`; installed skill metadata
+  is under `skills/`; specs live under `specs/companies/` and `specs/contacts/`.
+- Useful setup/maintenance commands: `leads init`, `leads version`, `leads doctor`,
+  `leads update --check`, `leads migrate --check`, and `leads skills status`.
+
+## Configure Apollo
+
+Require `APOLLO_API_KEY`.
+
+For the default email-and-phone flow, also require a public HTTPS `APOLLO_WEBHOOK_URL`; Apollo's
+phone and waterfall enrichment are asynchronous. Never print either environment value.
+
+If no webhook endpoint is available, run email-only enrichment with `--no-phone`.
+
+## Run Enrichment
+
+1. Identify the completed `contact-discover-<id>` requested by the user.
+2. Run `leads contacts show-run <contact-run-id>` to confirm scope and accepted count.
+3. Run `leads contacts enrich <contact-run-id>` for email and phone.
+4. Use `--no-phone` only when the user wants email-only enrichment or no webhook is configured.
+5. Use `--refresh` only when the user explicitly wants to ignore fresh 14-day Apollo memory.
+6. Report the contact enrichment run ID and ready/review/blocked counts.
+7. Read `summary.md` or `run.json` before explaining mismatches.
+8. Present the results with:
+   - one compact count line for all outcomes;
+   - one table for `ready`;
+   - one table for `review`.
+   Do not show `blocked` rows by default unless the user asks, or unless there are no useful
+   results and the blocking reasons are what the user needs next.
+9. Keep the default tables compact and systematic. Use these columns when they are available:
+   `Company | Contact | Title | Email | Phone | Status | Apollo Match | Notes`
+10. Show at most about 15 rows per table by default. If there are more, say that additional rows
+   are available in the exported artifacts.
+
+The command enriches accepted contacts only. It batches up to 10 people per Apollo request, polls
+asynchronous request IDs, and saves `contact-enrich-<id>` below the source contact run.
+
+## Follow-Up Operations
+
+- Show a run: `leads contacts show-enrichment <contact-enrich-id>`
+- Inspect a person: `leads contacts inspect-enrichment <run-id> --person "Jane Smith"`
+- Regenerate artifacts: `leads contacts export-enrichment <run-id>`
+
+## Interpret Results
+
+- `ready.csv`: identity matches and a work channel is supported by the target company domain.
+- `review.csv`: identity is credible, but Apollo company data, email domain, or channel context is
+  stale or ambiguous.
+- `blocked.csv`: no credible Apollo identity match or no usable email/phone was returned.
+- `run.json`: discovery snapshot, Apollo metadata, raw provider record, deterministic checks,
+  flags, and outcome.
+
+Apollo never overrides the live-web company, title, LinkedIn URL, or role. A stale Apollo employer
+is a review signal, not proof that discovery was wrong.
+
+## Guardrails
+
+- Do not enrich review or rejected discovery contacts automatically.
+- Do not describe review rows as outreach-ready.
+- Do not use personal email addresses without explicit human review.
+- Do not expose API keys, webhook secrets, or raw environment values.
+- Do not retry failed paid requests blindly; inspect the stored run and provider error first.

company_discovery/bundled_skills/contact-enrichment-operator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Contact Enrichment Operator"
+  short_description: "Enrich discovered contacts safely with Apollo"
+  default_prompt: "Use $contact-enrichment-operator to enrich accepted contacts from a contact discovery run with Apollo."

company_discovery/bundled_skills/contact-search-spec-writer/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: contact-search-spec-writer
+description: Convert natural-language requests for people at previously enriched companies into a validated contact_search_spec.json for the Leads CLI. Use when a user asks to find managers, owners, estimators, project managers, or other current employees across all or selected companies from a company enrichment run. Do not run discovery or add Apollo enrichment settings.
+---
+
+# Write Contact Search Specs
+
+Create one strict JSON input for `leads contacts discover`.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- Write contact specs to `specs/contacts/`, for example
+  `specs/contacts/contact_search_spec.json`.
+- Company specs belong in `specs/companies/`; do not write company ICP specs here.
+- Contact specs reference completed company enrichment runs stored under
+  `runs/<company-discover-id>/enrich/<company-enrich-id>/`.
+- Config is in `config/config.toml`; secrets are in `config/secrets.toml`; never expose secret
+  values.
+- The memory database is `data/company_memory.db`; use CLI commands rather than editing it.
+- Backups are under `backups/`; CLI diagnostics are in `logs/leads.log`; installed skill metadata
+  is under `skills/`.
+- Useful setup/maintenance commands: `leads init`, `leads version`, `leads doctor`,
+  `leads update --check`, `leads migrate --check`, and `leads skills status`.
+
+## Workflow
+
+1. Identify the completed company enrichment run that supplies the companies.
+2. Default to its `ready` companies. Use `review` or `all` only when the user explicitly wants
+   companies that were not fully ready.
+3. Resolve company scope:
+   - omit `domains` or use `[]` for every company in the chosen bucket;
+   - use root domains for a requested subset;
+   - never invent domains that are absent from the enrichment run.
+4. Convert every requested role into a stable snake_case key and a focused list of title labels.
+5. Default `max_per_company` to `1`. Increase it only when the user requests multiple people per
+   company or the role naturally needs broader coverage.
+6. Keep `current_only` and `require_role_match` true unless the user explicitly requests looser
+   research.
+7. Write JSON, then run `leads contacts validate-spec --spec <spec-path>`.
+8. Correct validation errors before handing the spec to the discovery operator.
+
+## Contract
+
+```json
+{
+  "version": 1,
+  "company_source": {
+    "enrichment_run_id": "company-enrich-a1b2c3d4e5f6",
+    "bucket": "ready",
+    "domains": []
+  },
+  "roles": [
+    {
+      "key": "project_manager",
+      "labels": ["project manager", "senior project manager"],
+      "max_per_company": 1
+    }
+  ],
+  "company_limit": null,
+  "contact_limit": null,
+  "current_only": true,
+  "require_role_match": true,
+  "memory_freshness_days": 30
+}
+```
+
+## Role Rules
+
+- Keep synonyms semantically close. Do not put `owner`, `estimator`, and `project manager` under
+  one broad `manager` role.
+- Preserve distinct user requests as distinct role objects.
+- Use observed business titles, not department keywords alone.
+- If “manager” is genuinely ambiguous and context does not resolve it, ask which management role
+  they mean before creating the file.
+
+## Guardrails
+
+- JSON is the canonical format; do not produce YAML.
+- Do not include company-discovery ICP fields such as state, vertical, size, or exclusions. The
+  company enrichment run already defines company scope.
+- Do not add email, phone, Apollo, or contact-enrichment settings.
+- Do not silently include company enrichment review rows.
+- Never expose API keys or environment values.

company_discovery/bundled_skills/contact-search-spec-writer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Contact Search Spec Writer"
+  short_description: "Turn contact requests into validated JSON specs"
+  default_prompt: "Use $contact-search-spec-writer to create a contact discovery spec from my request."

company_discovery/bundled_skills/leads-update-operator/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: leads-update-operator
+description: Safely guide updates for the Leads CLI, bundled agent skills, local database schema, and workspace backups.
+---
+
+# Operate Leads Updates
+
+Use this skill when a user asks to update, upgrade, repair, or check the installed Leads tool.
+
+## Workspace And CLI
+
+Use `leads doctor` or `leads version` to confirm the workspace root. The root contains
+`backups/`, `config/`, `data/`, `logs/`, `runs/`, `skills/`, and `specs/`.
+
+- `config/config.toml` stores non-secret settings; `config/secrets.toml` stores API keys and
+  webhook secrets; `config/runtime.json` stores schema, skill, and install metadata.
+- `data/company_memory.db` is the SQLite memory DB.
+- `runs/` stores discovery, enrichment, contact discovery, and contact enrichment artifacts.
+- `specs/companies/` and `specs/contacts/` store agent-created spec files.
+- `backups/` stores migration and reset backups.
+- `logs/leads.log` stores CLI diagnostics; it is not run evidence and should not be summarized as
+  a lead result.
+- `skills/` stores bundled skill copies and install metadata. Use `leads skills ...` commands
+  instead of manually editing installed skill files.
+
+Core commands to know: `leads init`, `leads version`, `leads doctor`, `leads config show`,
+`leads skills status`, `leads skills install`, `leads skills reinstall`, `leads update --check`,
+`leads migrate --check`, and `leads migrate --apply`.
+
+## Safe Update Flow
+
+1. Run `leads update --check` first.
+2. Prefer `leads update --check --json` when you need exact fields for an explanation.
+3. Report CLI, skill bundle, and database schema changes separately.
+4. Explain whether a backup or migration is required.
+5. If migration is required, run `leads migrate --check` or `leads migrate --check --json` and
+   explain the migration action, backup path behavior, and risk summary.
+6. Ask the user before applying structural database changes.
+7. Only run `leads migrate --apply` after explicit user approval. Use a large tool-window timeout,
+   around 10 minutes, so backup and migration work can finish.
+8. Do not assume a migration is harmless just because the command exists.
+
+## Interpretation
+
+- `cli_update_required` means the installed package version differs from the release manifest.
+- `skills_update_required` means bundled agent skills should be reinstalled or synced.
+- `migration_required` means the local schema and release manifest disagree, or the release
+  explicitly requires migration.
+- `backup_required` means the update plan expects a database backup before structural work.
+- `confirmation_required` means the agent should pause and get explicit user approval.
+- `leads migrate --check` is read-only and reports the local DB migration action.
+- `leads migrate --apply` creates a timestamped backup before supported structural changes and
+  refuses unknown migration paths.
+
+## Guardrails
+
+- Do not run destructive database operations from a plain update request.
+- Do not hide skill updates inside a generic success message.
+- Do not delete runs, specs, logs, backups, or the database unless the user explicitly confirms.
+- Never expose API keys or raw secret values from the workspace config.

company_discovery/bundled_skills/leads-update-operator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Leads Update Operator"
+  short_description: "Check and explain safe Leads updates"
+  default_prompt: "Use $leads-update-operator to run leads update --check, explain CLI, skill, and database changes separately, and ask before applying structural changes."