@agentled/cli 0.8.2 → 0.8.4

package/skills/agentled-content/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: agentled-content
+version: 0.2.2
+description: Use when drafting, revising, or planning content from authenticated AgentLed workspace context or a caller-selected local root.
+category: content
+allowedApps: kg
+allowedActions: kg.read-text, kg.read-list, kg.get-rows-by-ids, kg.upsert-rows
+relevanceKeywords: content, draft, editorial, brand, workspace template
+---
+
+# AgentLed Content
+
+The user's explicit content goal is the instruction for this turn and takes precedence over starter suggestions. AgentLed supplies authenticated workspace context and allowed tool bindings; no local root is required. Hermes supplies a caller-selected root and its tool bindings.
+
+## AgentLed host boundary
+
+In AgentLed, use only authenticated current workspace context, knowledge, files, and allowed tools or actions. Never borrow context from another workspace. Load only company facts, brand guidance, editorial rules, or a named brief relevant to the explicit content goal; do not require a local root. Tool availability is advisory, not authority, and unavailable tools are not a reason to withhold useful grounded output. Use only tools and actions the host allows, and treat every external or durable action as separately gated.
+
+## Hermes host boundary
+
+Hermes supplies a caller-selected root and its tool bindings. Do not discover a root. Do not load global context. Do not select a nested root. Do not search sibling roots or infer context from another customer, brand, or repository.
+
+Hermes-only optional guidance is available in [references/context.md](references/context.md), [tools.md](tools.md), and [templates/workspace](templates/workspace). AgentLed execution does not require or receive these relative files.
+
+## Request-led path
+
+1. Start from the explicit content goal.
+2. Load only context relevant to that goal.
+3. Ask at most the smallest necessary clarification when a missing answer prevents a useful result; otherwise produce the useful draft or review now.
+4. Research only when it helps the requested result or the user asks for it. Never claim research or source verification that did not run.
+5. When the user asked to keep, save, or prepare the result and the AgentLed host grants the existing private Knowledge tools, reuse the relevant workspace list, upsert the result with a stable identity, and read it back. This same-workspace private result save does not require a separate confirmation; never invent a list, schema, saved state, or link.
+6. Return the draft or review, material assumptions, any verified private result link, and any evidence gap plainly.
+
+If required context or a tool is missing, begin with `Partial result:`, preserve any useful grounded output, and give one recovery step.
+
+## Optional starters
+
+If no content goal is present, offer this short optional menu without choosing a default:
+
+- Draft or revise an announcement, email, article, or other requested format.
+- Turn an existing note or idea into a useful content draft.
+- Prepare a LinkedIn draft for review.
+
+## Repeatability boundary
+
+Ordinary drafting or revision creates no workflow. Create or propose a workflow only after the user explicitly asks to make the process repeatable. A possible future cadence is not an explicit repeatability request.
+
+## Separate action boundaries
+
+Private same-workspace persistence of the requested result follows the host's existing Knowledge permission. Publishing, scheduling, sending, provider connection, changing durable preferences, asset generation, and credit spend are separate explicit and approval-gated actions. Approval for one action grants no authority for another. Do not perform any of them automatically while drafting or revising.
+
+Acme and Northstar in the optional Hermes templates are synthetic fixtures, not live accounts. One-off requests remain one-off and do not alter durable brand preferences.

package/skills/agentled-content/references/context.md

@@ -0,0 +1,21 @@
+# Selective context loading
+
+Load only context relevant to the explicit goal.
+
+## AgentLed host
+
+Use the authenticated workspace context, knowledge, and files AgentLed exposes for the current workspace. Load only the company facts, brand guidance, editorial rules, or named brief needed for the request. Do not require or infer a local root.
+
+## Hermes host
+
+Use only the caller-selected root.
+
+1. Read `AGENTS.md` for local operating rules.
+2. Read `company.md` only when company or product facts matter.
+3. Read the selected brand's `brand.md` only when voice or explicitly requested durable preferences matter.
+4. Read `content/guidelines.md` only for relevant editorial constraints.
+5. Read `first-task.md` or another named brief only when it scopes the request.
+
+Do not discover another root, load global context, select a nested root, search sibling roots, or borrow facts, preferences, or audience claims from another brand.
+
+If needed context is absent, begin with `Partial result:`, state the gap, make only a bounded assumption when safe, and give one recovery step.

package/skills/agentled-content/templates/workspace/AGENTS.md

@@ -0,0 +1,5 @@
+# Content workspace
+
+This portable template supports local drafting only. Work in the selected root and load only context relevant to the current request.
+
+External sends, publishing, feedback submission, paid generation, and account changes require separate explicit approval. Do not treat a draft as permission to act.

package/skills/agentled-content/templates/workspace/brand.md

@@ -0,0 +1,15 @@
+# Selected brand preferences
+
+Choose one selected brand before changing durable preferences.
+
+## Acme
+
+- Voice: practical, direct, and encouraging.
+- Preferred proof: a concrete workflow example.
+
+## Northstar
+
+- Voice: measured, analytical, and concise.
+- Preferred proof: a source-backed observation.
+
+Keep Acme and Northstar preferences separate. Update only the selected brand after an explicit durable-preference request. One-off requests do not change durable preferences.

package/skills/agentled-content/templates/workspace/company.md

@@ -0,0 +1,11 @@
+# Company fixture
+
+## Acme
+
+Acme is a synthetic B2B operations software company. Its example audience is small teams that need a clear, practical way to coordinate recurring work.
+
+## Northstar
+
+Northstar is a synthetic research studio. Its example audience is leaders who value concise, evidence-backed decisions.
+
+Use these fixtures only to test local drafting structure. Replace them with verified selected-root context before presenting customer-specific claims.

package/skills/agentled-content/templates/workspace/content/guidelines.md

@@ -0,0 +1,6 @@
+# Content guidelines
+
+- State verified facts plainly and label assumptions.
+- Match the selected brand voice without mixing preferences from another brand.
+- Keep a draft reviewable before any external action.
+- Preserve a one-off request as a one-off unless the user explicitly asks to update a durable preference.

package/skills/agentled-content/templates/workspace/first-task.md

@@ -0,0 +1,5 @@
+# First task fixture
+
+Draft a short introductory article for Acme or Northstar using only the selected fixture and the requested audience. Label assumptions and provide the draft for review.
+
+Do not generate visual assets or publish the article.

package/skills/agentled-content/templates/workspace/onboarding.md

@@ -0,0 +1,5 @@
+# Onboarding prompt
+
+For a new selected root, identify the company facts, selected brand, audience, goal, and format needed for the first draft. Keep unknowns explicit.
+
+Ask whether a preference is durable before recording it. A single draft request is not a durable-preference change.

package/skills/agentled-content/templates/workspace/tools.md

@@ -0,0 +1,5 @@
+# Drafting tools
+
+Local files and ordinary text editing are sufficient for a draft. Optional research, generation, and delivery tools are advisory only.
+
+When a requested tool is unavailable, return an honest partial result with the draft and the missing evidence. Do not create assets, spend credits, publish, or submit feedback automatically.

package/skills/agentled-content/tools.md

@@ -0,0 +1,8 @@
+# Optional tools
+
+Tools are advisory aids, not requirements or authority. Draft from available host context when it is sufficient.
+
+- Research only when it helps the requested result or the user asks for it. Never claim research, browsing, or source verification that did not run.
+- Publishing, scheduling, sending, provider connection, changing durable preferences, asset generation, and credit spend each require their own explicit request and approval.
+- Never retry a tool automatically or turn a drafting request into an external or durable action.
+- When a required source, tool, or capability is unavailable, begin with `Partial result:`, provide any useful grounded draft, name the gap, and give one recovery step.

package/skills/agentled-content-visuals/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: agentled-content-visuals
+version: 0.2.1
+description: Generate or review one useful visual from the user's explicit content brief.
+category: content
+allowedApps: openai
+allowedActions: openai.generate-image
+relevanceKeywords: visual, image, illustration, content quality, accessibility
+---
+
+# AgentLed Content Visuals
+
+Use this independent specialist only when the user asks to generate an image or needs a visual brief or candidate reviewed. In AgentLed, ground the work only in the authenticated current workspace and the relevant selected company, brand, page, or content context. Never borrow another workspace's context or invent a brand identity. In a portable host, use only the caller-selected root and context.
+
+Listing `openai` or `openai.generate-image` recommends the existing AgentLed capability; it grants no app access, provider credential, approval, billing authority, publication authority, or permission to retry. Existing AgentLed action permission, approval, and credit checks remain authoritative.
+
+When a required source, tool, or capability is unavailable, return a useful `Partial result:` and identify the missing evidence or access.
+
+## Generate one visual
+
+1. Preserve the user's explicit brief and load only the relevant selected brand, content, and material facts.
+2. Choose one supported size that fits the requested use: square, landscape, portrait, or the existing Instagram portrait preset.
+3. State the intended visual and any material assumptions before the paid action when the existing approval surface requires review.
+4. After explicit generation intent and only when current action approval and credit checks allow it, make exactly one `openai.generate-image` attempt.
+5. Return the generated image URL or artifact, useful alt text, and a concise visual-quality review covering claim fit, focal point, legibility, accessibility, and brand fit.
+
+Do not retry automatically. A second paid attempt requires fresh explicit user intent after the first result or failure is visible. If generation fails, is ambiguous, or lacks a verifiable artifact, begin with `Partial result:`, preserve the exact brief and assumptions, name the gap, and ask before another attempt.
+
+## Review a brief or candidate
+
+Apply the quality checks directly from this skill: verify that the visual supports the claim without adding an unsupported one, has a clear focal point at the intended size, keeps essential text legible, includes useful alt text, and follows the selected brand's palette and tone without copying another brand. The supplementary portable-host checklist is in [references/quality-checks.md](references/quality-checks.md); AgentLed does not require that relative file at runtime.
+
+## Separate action boundaries
+
+Image generation does not authorize publication. Do not publish, schedule, create a workflow or routine, connect a provider, or make a durable preference change as part of this skill. Each external or durable action remains a separate explicit and approval-gated decision.

package/skills/agentled-content-visuals/references/quality-checks.md

@@ -0,0 +1,9 @@
+# Visual quality checks
+
+- Does the visual support the specific claim without introducing an unsupported one?
+- Is the focal point clear at the intended viewing size?
+- Is essential text readable and is useful alt text available?
+- Does the visual follow the selected brand's palette and tone without copying another brand?
+- Is the returned URL or artifact verifiable before any publication decision?
+
+If any input or capability is missing, begin with `Partial result:`, preserve the brief, identify the unverified check, and do not guess or retry a paid generation automatically.

package/skills/gtm-operator/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: gtm-operator
+version: 0.17.0
+description: Start from saved company context and finish a useful GTM result in one run: find and qualify 2-3 accounts, enrich likely buyers, save private work, and prepare outreach drafts before improving from feedback.
+category: gtm
+allowedApps: agentled, web-scraping, kg, hunter, clay, gmail, linkedin, dripify
+allowedActions: web-scraping.scrape, agentled.google_maps, agentled.linkedin_post_search, agentled.get-linkedin-company-from-url, agentled.get-linkedin-profile-from-url, agentled.find-linkedin-profile-url, agentled.linkedin_company_posts, agentled.linkedin_profile_posts, hunter.find-email-person-domain, hunter.get-emails-from-company-domain, kg.read-text, kg.get-rows-by-ids, kg.upsert-rows, clay.search-companies, clay.search-people, clay.get-routine-results, clay.get-query-reference, clay.send-to-webhook
+relevanceKeywords: ICP, prospect research, lead discovery, local business prospecting, qualification, enrichment, Clay, Hunter, LinkedIn, Instantly, outreach draft, GTM, feedback, automation
+---
+
+# GTM Operator
+
+Turn a company URL and a short conversation into useful GTM progress. The default is to finish one useful GTM result in the first run: understand the company, find and qualify a few real accounts, identify likely buyers, save the private result, and prepare outreach drafts. Improve from feedback after the user has something concrete to judge.
+
+Tool recommendations do not grant permission. Actual availability comes from the assigned agent, connected apps, workspace policy, credits, and approval gates. Never imply that a listed app is connected or authorized until current workspace state confirms it.
+
+## Default first conversation
+
+When onboarding or workspace context already provides a company URL, do not ask the user to repeat it.
+
+1. Read the workspace company profile and relevant knowledge such as the saved ICP when available.
+2. State one or two concrete observations about the company and continue; the user can correct them without blocking the first result.
+3. State a short draft ICP with clearly labeled assumptions. Ask at most one compact question only when a missing answer would materially change the first search.
+4. Research exactly 2-3 source-backed prospect examples. Prefer first-party company evidence and fresh public sources. Show why each might fit, the strongest evidence, the main uncertainty, and the source URLs.
+5. For every promising example, use available LinkedIn and Hunter actions to identify a likely buyer and usable contact path. Follow "Finding a contact email" below: use `hunter.get-emails-from-company-domain` as soon as a promising company domain is known, and refine a named person with `hunter.find-email-person-domain`.
+6. Save each qualified account to the workspace's `lead_generation_candidates` list with `kg.upsert-rows`, using the field and stage definitions in "Discover and qualify" below. Set the row `userKey` to the normalized company domain so re-running the search updates the same lead instead of duplicating it. Read the returned `rowId` values back with `kg.get-rows-by-ids` and verify the company, evidence, contact, stage, and next action before claiming the result was saved. Research, enrichment, private same-workspace saves, and drafts do not need action-by-action confirmation when they are part of the user's requested GTM job.
+7. Ask for one compact feedback choice, for example: "Which is closest: 1, 2, 3, or none?" Also accept natural-language corrections. Use the answer to refine the next sample without turning the conversation into a form.
+
+A first result is a small working lead sample, not a promise of a complete market. Unknown evidence is unknown, not a negative score. Use the workspace's available credits for useful actions; do not invent a smaller skill-level spend cap or pause for each routine provider call. Do not stop the run because one source fails: continue with the remaining sources and return the strongest complete result possible without exposing raw infrastructure errors as the result.
+
+## Tool recommendation from the existing stack
+
+Before recommending a new tool, briefly inspect what the user already has. Recommendations can happen immediately when the stack is obvious, or after a few turns as goals and constraints emerge. They are not a mandatory setup interview before useful work.
+
+### What to inspect
+
+- Connected integrations and authorized workspace metadata: Clay plan and capabilities, relevant tables/enrichments, existing PredictLeads use.
+- Sending readiness: chosen email sender or sequencer, warmup state, sending domain, mailbox health.
+- CRM and sync ownership: HubSpot or another CRM, who owns field mapping, whether sync is one-way or two-way.
+- LinkedIn provider: existing automation or manual workflow.
+- Budget and intended volume: monthly envelope, expected send or action count, geography.
+
+Ask only what materially changes the recommendation. Mark unknowns explicitly instead of guessing from a connected badge or empty workspace state.
+
+### How to recommend
+
+- Preserve the user's working stack. A full Clay setup may own enrichment and email; do not split a working pipeline just because another tool exists.
+- "No Clay" is a valid setup. Use available direct providers, including a connected customer-owned PredictLeads account when fresh company signals matter, and AgentLed's bounded email and LinkedIn actions.
+- Pick the smallest set that answers the question. More tools are not automatically better, and overlapping enrichment produces duplicate cost and noise.
+- Keep one owner for each send and CRM write. Reuse existing suppression, prior-contact, and duplicate checks. Avoid running the same PredictLeads enrichment both directly and through Clay. CRM sync requires explicit direction, target, field scope, and an existing supported action.
+- A setup recommendation is not a purchase, install, or connection. Confirming that a tool "would fit" never enrolls, sends, writes, or schedules.
+
+### Common stack shapes
+
+- **Full Clay:** Clay may own enrichment and email, with an optional existing LinkedIn tool. AgentLed then acts on drafts Clay already produced or on read-only context Clay surfaces.
+- **Clay enrichment + AgentLed email:** Clay handles enrichment and selected-row expansion; AgentLed handles approved email through its available provider, with optional HubSpot sync and LinkedIn context from a separate provider.
+- **No Clay:** use direct providers. AgentLed's bounded Hunter, LinkedIn, and email actions, plus a connected customer-owned PredictLeads account, can carry the full first proof without Clay. Confirm current capabilities before promising any arrangement.
+- **Missing LinkedIn access:** LinkedIn automation needs an explicit provider. If the user has no incumbent and wants automation, surface HeyReach as a candidate: verify capabilities, price, and the user's preference before recommending purchase or treating it as a default. Manual LinkedIn remains a valid next step.
+
+### Returning the recommendation
+
+Return a concise answer that names:
+
+- Current setup, including what is connected vs. merely installed.
+- Recommended division of work and the reason it fits this specific job.
+- What is missing (provider, plan tier, mailbox, budget, owner).
+- Cost or credit implications at the user's volume.
+- One next action and who approves or executes it. Useful actions include research, correcting CRM context, drafting, scheduling a follow-up, requesting an introduction, or doing nothing because no signal warrants it.
+
+Revisit the recommendation after each result or correction. A stack that worked for the first proof may not fit the next motion.
+
+### Save the agreed stack
+
+Once the user confirms the recommended division of work, persist the agreed setup as one workspace-private record so later conversations reuse it instead of reassessing from scratch.
+
+Record contract and key:
+
+- Knowledge list: `gtm-stack-agreements`, content mode `agent-record`, contract `GtmStackAgreement.v1`.
+- Required fields: `contractVersion` (always `1.0.0`), `agreementId`, `workspaceId`, `stackShape` (one of `no-clay`, `working-full-clay`, `clay-plus-agentled-email-and-hubspot`, `missing-linkedin-access`), `providerRoles` (enrichment, email, linkedin, crm — each `agentled_native`, `clay`, `customer_owned`, `separate_provider`, `manual`, `none`, or a named third-party label), `constraints` (budget envelope, intended volume, geography, approval posture), `ownership` (named provider, plan, mailbox, or owner per role), `missingPrerequisites` (provider, plan tier, mailbox, budget, owner — only the missing pieces), `nextAgreedAction` (type, owner, and approval posture), `dedupKey`, `skillVersion` (the loaded skill version), `confirmedByUser` (boolean), `confirmedAt`, `createdAt`, `updatedAt`.
+- Dedup: build `dedupKey` as the canonical string `stackShape + ':' + sorted(providerRoles)` and pass that exact value as the row `userKey` to `kg.upsert-rows` with `mergeStrategy: "merge"`. AgentLed derives the workspace- and list-bound deterministic SHA-256 row id from that `userKey`, so a re-confirmation of the same stack updates the existing row instead of creating a duplicate. A material change (different stack shape or different provider role) produces a new `dedupKey` and a new `agreementId`; the prior row is preserved, not overwritten.
+
+Write action and readback:
+
+- Write through the reviewed `kg.upsert-rows` action bound to the `gtm-stack-agreements` list; never write by direct insert, never bypass the action layer.
+- Because this record is private to the current workspace and is part of the requested GTM job, saving and reading it back does not require a separate confirmation. Never write outside the current workspace or treat a private save as permission to send externally.
+- Use the returned `rowId` with `kg.get-rows-by-ids`, then verify `agreementId`, `dedupKey`, `providerRoles`, `stackShape`, `confirmedByUser`, and `skillVersion` match what was just confirmed. If the readback is missing, the row id is wrong, or any required field does not match, treat the save as failed and tell the user the agreement is unverified.
+- Record the resulting `agreementId` in the same turn so a follow-up conversation can reference it. Never claim the stack was saved without the readback receipt.
+
+If the workspace does not allow the write, the integration's authorized scopes do not include `kg.upsert-rows` for `gtm-stack-agreements`, or the user has not yet confirmed, surface the unverified stack in the current conversation only and explain that the agreed setup will need to be reconfirmed on the next turn.
+
+## Progressive GTM ladder
+
+Advance only as the user sees useful results.
+
+### 1. Understand
+
+Use company URL, profile, products, geography, prior answers, and saved workspace context. Reflect a concrete understanding and surface only the assumptions that affect targeting.
+
+### 2. Discover and qualify
+
+Return 2-3 evidence-backed accounts per feedback round. Explain fit in plain language, privately save the useful result, enrich likely buyers, and prepare drafts in the same run. Do not create a bulk campaign, activate a workflow or routine, or send anything during the first discovery round.
+
+<!-- BEGIN GENERATED: lead-record-schema -->
+<!-- Generated from shared/services/useCases/leadRecordSchema.ts.
+     Do not edit by hand: run `node scripts/sync-lead-record-schema-to-skill.mjs`. -->
+
+Save each account as a row on the `lead_generation_candidates` list.
+
+Use these exact field names. Each surface looks its field up by the literal key,
+so a synonym is the same as leaving the field empty: writing `companyName`,
+`recommendedNextAction` or `whyTheyFit` stores real work that the user's table
+renders as a blank cell, with no error to tell you. Keep contact details as flat
+fields, never nested under an object. Extra fields are fine; these names are not
+negotiable.
+
+- `company` (required) — The account name. This is the row's title. Shown in: Company column, and the record page heading.
+- `qualificationReason` — The specific evidence that this account fits: industry, signal, buyer match. Not a generic label. Leave empty while fit is still unclear. Shown in: Record page, and the Qualified milestone.
+- `nextAction` — A specific next step for THIS company, e.g. "Draft outreach to the founder". Never a placeholder like "Follow up". Shown in: Next action column.
+- `founderEmail` — The contact's email once found. When outreach may only use public role addresses, this is the company's role address (info@, press@, hr@) rather than a person's. Leave empty rather than guessing an address. Shown in: Record page contact links.
+- `linkedinUrl` — The contact's or company's LinkedIn profile URL. Shown in: Record page contact links.
+- `draft` — The outreach draft body, once written. Drafting is not sending. Shown in: Record page "Outreach draft" block, and the Outreach drafted milestone.
+- `source` — Where the lead came from, e.g. `linkedin`, `web search`. Shown in: Source column.
+- `sourceUrl` — The exact URL the lead was found at. Shown in: Source column link.
+- `provider` — The tool or method that surfaced it, e.g. `Clay`, `Hunter`, or your own research. Shown in: Source column badge.
+- `crmState` — A short label for what actually happened to the row, e.g. `AgentLed: saved`. Never claim a CRM write that did not occur. Shown in: CRM column.
+- `lastActivityAt` — ISO timestamp of the most recent real activity on this lead. Shown in: Last activity column.
+- `outreachExecutionId` — Execution id for the outreach run, once one exists. Shown in: Engagement column.
+
+A lead's stage is the row's own `status` on the `kg.upsert-rows` envelope, not a
+field inside `rowData`. A `status` written inside `rowData` is discarded. Set it
+per row, because leads in one call are usually at different stages:
+
+- `new` — the lead is saved but not yet qualified.
+- `qualified` — qualificationReason is set and backed by evidence you actually gathered.
+- `ready_for_outreach` — a draft exists and is awaiting review.
+- `contacted` — outreach was actually sent.
+
+Never advance a stage to look further along than the work actually is.
+
+```json
+{
+  "userKey": "seedtag.com",
+  "status": "qualified",
+  "rowData": {
+    "company": "Seedtag",
+    "qualificationReason": "Madrid adtech selling privacy-first contextual advertising to advertisers and publishers; fits the outbound-heavy mid-market profile.",
+    "nextAction": "Draft outreach to George Goddard, Senior Director of Sales",
+    "founderEmail": "georgegoddard@seedtag.com",
+    "linkedinUrl": "https://www.linkedin.com/company/seedtag/",
+    "source": "web search",
+    "sourceUrl": "https://www.seedtag.com/",
+    "provider": "Hunter"
+  }
+}
+```
+
+Use `mergeStrategy: "merge"` when updating saved leads. The default overwrites
+`rowData`, so a later pass would erase fields an earlier pass just wrote.
+
+<!-- END GENERATED: lead-record-schema -->
+
+Never invent evidence to fill a field. If you cannot find an email, leave `founderEmail` empty rather than guessing one. If fit is genuinely unclear, leave `qualificationReason` empty and keep the stage at `new` — a lead that is not actually qualified must not be marked `qualified`. An honestly incomplete row is more useful than a complete-looking one built on invented facts.
+
+### 2b. Keep going after the leads are saved
+
+Saving leads is not the finish line. A table of company names with an empty
+Status and no next action is not a result the user can act on. In the same run,
+without asking permission first, take every saved lead as far as the evidence
+allows:
+
+1. **Find the buyer.** For each saved lead, identify one likely decision maker
+   and a usable contact path, then write `founderEmail` and `linkedinUrl` back
+   onto that lead's row. Leave a field empty rather than guessing a value.
+2. **Qualify honestly.** Write the specific evidence into `qualificationReason`
+   and move the stage to `qualified` only when that evidence is real, by setting
+   `status: 'qualified'` on that row's envelope. A lead you could not verify
+   stays at `new` with an honest next action.
+3. **Draft the outreach.** Write one short, evidence-specific draft per
+   qualified lead into `draft`, referencing the actual signal you found, and set
+   that row's `status` to `ready_for_outreach`. Drafting is not sending.
+4. **Set the next action.** Every row ends with a `nextAction` that names the
+   specific next step for that company. Never leave it blank or generic.
+
+Use `mergeStrategy: 'merge'` on these updates. The default overwrites `rowData`,
+so a later pass would erase the fields an earlier pass just wrote.
+
+Do each pass across all saved leads before moving to the next, so the user sees
+the whole table advance rather than one perfect row and several empty ones.
+Stop and hand back when the next step is an external write: sending the
+outreach, enrolling in a sequencer, or writing to a CRM. Those need approval.
+Everything before them is the work the user asked for.
+
+### 2c. Working from a Clay list
+
+When the workspace has Clay connected, the user's existing lists are usually the
+best starting point: they already reflect real targeting. Use
+`clay.search-companies` or `clay.search-people` to read from them. Both take a
+Clay query-mode expression beginning with `select` or `count`, not plain-language
+search text, and both are read-only, so use them without stopping to ask.
+
+An unfiltered `select from companies` works, but Clay's query grammar and field
+names are not guessable — a query built from assumed field names (e.g. `country`,
+`industry`) fails with `Unknown field` errors, and quoting the wrong way fails
+with a parse error. Before writing any FILTERED query (a `where` clause targeting
+an ICP), call `clay.get-query-reference` first. It is read-only and free, and its
+`reference` output documents the exact queryable fields and query-mode syntax.
+Do not guess field names or retry blind after a 400 from Clay; read the reference
+and build the query from it.
+
+Leads read from Clay enter the same machine as researched ones: save them to
+`lead_generation_candidates` with `provider` set to `Clay`, then run the same
+buyer, qualification, and draft passes above. Writing back into the user's Clay
+workspace with `clay.send-to-webhook`, and running a Clay routine that spends
+their Clay credits, are external writes that require approval. Offer them after
+the user has seen a result, not before.
+
+### 2d. Finding a contact email
+
+Use Hunter to find the contact email. Do not read pages one by one with web search to hunt for an address; Hunter returns every address it knows for the domain, with the pages it found each one on, in a single call.
+
+- **Default.** As soon as the company domain is known, call `hunter.get-emails-from-company-domain` once for that domain and reuse the result. When a verified person's name is known, refine that contact with `hunter.find-email-person-domain`.
+- **Public role addresses only.** When the workspace's outreach rules or company profile say outreach may use only a company's public role address (for example strict B2B rules such as Spain's LSSI art. 21 or GDPR, or "public contact, press or HR address only"), work in this mode:
+  1. Call `hunter.get-emails-from-company-domain` with `type: "generic"`. Never use a personal address in this mode, even when the search returns one.
+  2. Prefer addresses with `foundOnCompanyDomain: true`: the company publishes them itself. Use an address found only on third-party pages when no company-published one fits, and say so.
+  3. Choose by role fit, in this order: people/HR/culture (`rrhh`, `hr`, `people`, `cultura`, `talento`, `careers`), then press/communication (`prensa`, `press`, `comunicacion`), then general contact (`info`, `hola`, `hello`, `contacto`, `contact`).
+  4. Skip legal, privacy or data-protection, billing, support or customer-service, and bookings addresses unless the user explicitly allows them.
+- **Save the result.** Write the chosen address to `founderEmail` (the field the lead table and outreach read) even when it is a role address, put the page Hunter found it on in `sourceUrl`, and set `provider` to `Hunter`. Tell the user which provider found it.
+- **Nothing suitable.** If Hunter returns nothing suitable, fall back to the company's own contact, press or careers pages. Otherwise leave `founderEmail` empty and state why in `nextAction`. Never guess an address.
+
+### 2e. Keeping LinkedIn leads in their own list
+
+`lead_generation_candidates` is the email prospect list: it holds the companies and contacts that can be emailed under the workspace's outreach rules, and the email outreach tool works from it. A lead whose channel is LinkedIn does not belong there. Keep it on a separate list, `linkedin_outreach`, so the email list stays clean and the LinkedIn work has its own status.
+
+A lead's channel is LinkedIn when any of these is true:
+
+- No qualifying address exists under the workspace's rules after "Finding a contact email": none was found, or only a personal address was found where only public role addresses are allowed.
+- The contact was already approached on LinkedIn.
+- The user says the company must be approached on LinkedIn.
+
+For each such lead:
+
+1. **Save it on `linkedin_outreach`** with `kg.upsert-rows`, using the lead's normalized company domain as `userKey` and `mergeStrategy: "merge"`. If the list does not exist yet, the first upsert creates it, and its columns are the keys of the first row you write, so put every field below on that first row (an empty string for an unknown value). Use these exact field names:
+   - `company` (required): the account name.
+   - `contactName`, `contactRole`: the person to approach, when known.
+   - `linkedinUrl`: the contact's profile, or the company page when no person is known.
+   - `channelReason`: why the lead is on LinkedIn, for example "no public role address found" or "already approached on LinkedIn".
+   - `message`: the connection note or message you prepared for the user, once one exists.
+   - `lastActivityAt`: ISO timestamp of the latest real activity on this lead.
+   - `sourceRowKey`: the `userKey` of the lead's row on `lead_generation_candidates`, when it has one.
+   - `notes`: anything else worth keeping, such as an address that was found but may not be used.
+
+   The row's stage is its own `status` on the `kg.upsert-rows` envelope, as on the prospect list (a `status` inside `rowData` is discarded): `to_contact`, `request_sent`, `connected`, `messaged`, `replied` or `not_interested`. Start at `to_contact`. Move it only when the user tells you what happened or an action result proves it; never mark a request or message as sent that you did not see sent.
+2. **Keep the prospect row out of email.** The email outreach tool, `startLeadOutreach`, skips a row whose status is `contacted` and a row with no saved email address, so:
+   - Already approached on LinkedIn: set the prospect row's `status` to `contacted` and its `nextAction` to "Approached on LinkedIn - see linkedin_outreach".
+   - Not yet approached: leave `founderEmail` empty (if it holds an address that may not be used, clear it and keep it in `notes` on the `linkedin_outreach` row), set `nextAction` to "LinkedIn - see linkedin_outreach", and do not set `ready_for_outreach` or write an email `draft` on that row.
+
+   Update the prospect row with `mergeStrategy: "merge"`. Read both rows back with `kg.get-rows-by-ids` before telling the user the lead was moved.
+3. **Prepare, do not send.** Write the connection note or message for the user and save it in `message`. Do not send, connect or message on LinkedIn yourself: that needs a supported LinkedIn send action in the workspace and the user's exact approval of that text (see "Execute with approval"). Without one, hand the text to the user and track `status` from what they report back.
+
+A lead has one channel at a time. If it changes later, for example a qualifying address turns up and the user prefers email, update both rows to match instead of leaving the lead on both lists.
+
+### 3. Refine
+
+Treat user selections, rejections, corrections, exclusions, and preferred examples as targeting evidence. Update the working ICP and search criteria. Preserve corrections in the AgentLed system of record only when the current action policy permits the write.
+
+### 4. Enrich selected prospects
+
+Enrich the first 2-3 promising accounts in the initial run and refine the selected accounts after feedback, up to ten likely contacts in one bounded pass.
+
+- Use reviewed Agentled LinkedIn actions for company identity, professional profiles, posts, buyer/topic signals, and timing.
+- Use `hunter.get-emails-from-company-domain` as soon as a promising company domain is known, because it can return names, roles, and emails without a known person. When a reliable buyer name is known, use `hunter.find-email-person-domain` to refine that specific contact. Follow "Finding a contact email" for public-role-address-only outreach.
+- If a connected Clay table adds value, offer to send the selected rows to Clay after feedback. If Clay is not connected, say so and provide the connection path instead of pretending the action ran.
+- Never use arbitrary Apify actor IDs in the default path. Use the reviewed Agentled actions backed by Apify.
+- Avoid running the same enrichment through two providers. The default Hunter-and-LinkedIn instruction applies when those actions add missing evidence; if Clay already owns company or contact enrichment, do not re-run it through Hunter or LinkedIn for the same accounts unless the new data answers a question Clay cannot.
+
+### 5. Prepare one next action
+
+For selected prospects, recommend one channel and produce draft-only outreach or another approval-ready next action. State the evidence used and the uncertainty. Drafting does not authorize sending.
+
+If the user wants LinkedIn execution at scale, explain that they can connect an approved LinkedIn automation tool such as the workspace's supported integration. Do not enroll prospects, send invitations/messages, or change provider state without exact approval. Leads whose channel is LinkedIn are tracked on their own list; see "Keeping LinkedIn leads in their own list".
+
+When the chosen channel is email, pick the right tool for the stack:
+
+- If the workspace uses Clay for email, the draft and send belong to Clay's configured sequencer. AgentLed surfaces evidence and review, and the send is Clay's.
+- If the workspace prefers AgentLed to own the send, use AgentLed's reviewed email provider and produce a draft that goes through the existing approval flow. Treat Instantly as a conditional candidate for email sequencing: verify the exact feature, the workspace's geography, account access, budget, and whether AgentLed exposes a supported action for it before offering execution. A recommendation does not imply native integration readiness.
+- To email leads saved on `lead_generation_candidates` through AgentLed, call `startLeadOutreach` with their `userKey` values. It starts one approval-gated run per lead, skips leads that have no valid saved email, are already contacted or were already launched (and says why), and sends nothing until the user approves each email.
+- If the user has neither, propose the smallest setup that fits their volume and goals, and ask before changing providers.
+
+When the chosen channel is US-based website visitor identification and the workspace has meaningful US traffic, Instantly Website Visitors is a conditional candidate. Geography, tracking pixel prerequisites, and permitted use must be checked for the user's case. Treat the feature as worth evaluating, not as a universal compliance claim or a default. Installing a tracking pixel, purchasing credits, or enrolling contacts remains a separately scoped action.
+
+### 6. Execute with approval
+
+Before any email, LinkedIn action, CRM/calendar write, provider enrollment, public post, or other external write, freeze the destination, channel, copy, source prospect, and approval reference. A change invalidates the earlier approval. Reconcile ambiguous results before retrying.
+
+Approval is required for every external write, including any Clay or Instantly sequencer enrollment, HubSpot or other CRM write, LinkedIn action, provider purchase, or schedule activation. Read-only setup discovery is not authority to read arbitrary CRM or mailbox content; respect the workspace's connection scope and the integration's authorized scopes.
+
+## GTM outreach lifecycle configuration
+
+After the user has a useful saved result and draft, an operator may review a paused lifecycle configuration. Review the sender or supported sequencer, one sequence owner, reply visibility, follow-up delay and limit, stop conditions, shared per-sender daily cap, approval policy, and seller booking link. Keep the configuration unconfigured or paused until every binding is present and reviewed.
+
+- Use one sequence owner only: native AgentLed or one existing supported external sequencer. Reuse external outcomes; never schedule duplicate follow-ups beside an existing owner.
+- Reuse the existing provider message/thread correlation and reply events. Header-only evidence proves reply presence, not body classification. Missing reply visibility blocks unattended follow-up; tell the operator to connect or repair the chosen reply-tracking source before proceeding.
+- Recheck reply and suppression state immediately before a follow-up. Replies, negative replies, opt-outs, bounces, and manual stops suppress pending follow-ups. First touches and follow-ups consume the same per-sender limit. Reconcile an unknown receipt before retrying; duplicate events or retries must not duplicate outreach.
+- Keep the lead's existing outreach projection for sender, last contact, reply, next follow-up, handoff, and actual send outcome. A positive reply may set `booking_requested` with the configured seller booking link. booking_requested is not a booked meeting; booked, held, qualified, cancelled/rescheduled, and no-show remain distinct outcomes.
+- Installing this configuration does not send, enroll, call a provider, spend credits, or activate a routine. It is not automated mailbox warm-up. A controlled-recipient proof with exact authorization is required before calling the lifecycle operationally ready.
+
+### 7. Automate proven work
+
+Only after at least one useful one-off result, offer to save the proven sequence as an AgentLed workflow and, if the user wants recurrence, a paused routine with a reviewed cadence and cap. Do not activate recurrence merely because a workflow exists.
+
+## Rank, diagnose, and learn
+
+Apply these habits within the current conversation or authorized job; they do not add a setup questionnaire or require a campaign before the first useful sample.
+
+- **Rank before drafting.** Apply the workspace's exclusions first, then order the current sample or selected accounts by company fit, relevant persona, and recent evidence of need. Explain "why this account, why now?" with source URLs and signal dates; distinguish the event date from the date it was checked. Unknown stays unknown. Use the workspace's criteria, not universal weights, hiring/funding priorities, or invented scores. Keep the first sample at 2-3 accounts.
+- **Identify the weakest stage.** When asked to improve results, inspect the available evidence in order: targeting and persona, delivery health (verification, bounces, complaints), replies and messaging, then qualified opportunities and business outcomes. Name the earliest supported problem and recommend one next action. If evidence is missing, state a hypothesis and the smallest check needed; do not declare a cause, increase volume, or rewrite copy by default.
+- **Turn outcomes into one experiment.** Review a completed cohort using its dates, denominators, approved message variant, and observed replies, qualified opportunities, and business outcomes. Use the workspace's actual goal, such as qualified applications for an event. Separate observations from interpretation and attribution from causation. Recommend one variable to change in the next cohort and how to judge it; keep the current cohort unchanged. Small or incomplete samples mean insufficient evidence, not a winner. Preserve account history, corrections, and opt-outs through existing authorized records. Report: observed result, uncertainty, next change, success measure. A recommendation does not launch an experiment or change targeting, drafts, schedules, or workspace records.
+
+## Close every turn with the next step
+
+Lead the work; do not leave the user to work out what comes next. End each turn with the single most useful next action, phrased as an offer the user can accept with "yes", and name its exact scope in counts and names. For example:
+
+- "3 companies now have a public address: Acme, Globex, Initech. Shall I draft their emails into the approval list?"
+- "4 drafts are waiting for your approval in the outreach approval list."
+- "35 companies still need an address. Shall I research the next 6 with Hunter?"
+
+Offer it as a clickable chip. In the app chat, call `suggest_chat_actions` once, at the end of the turn, with 1-3 chips:
+
+- The first chip is the recommended next step. Its `label` is 2-4 words ("Draft 3 emails"). Its `prompt` is the exact request the click sends, with the same scope as the offer ("Draft emails for the 3 companies with a public address: Acme, Globex, Initech").
+- Add a second or third chip only for a real alternative the user is likely to pick instead (for example "Research 6 more companies"), never to fill the row. Do not add `Run on a schedule` or `Save for later`: recurrence is offered under "Automate proven work" once a one-off result is proven.
+- Keep one short closing sentence that names the same step, so the offer still reads where buttons do not show (email, Slack, WhatsApp, Signal, Telegram). On those channels end with that sentence and do not call the tool.
+
+Rules for the offer and its chips:
+
+- On "yes" or a chip click, do exactly what was offered, within the approval boundaries already in force. A send still needs the user's explicit approval of each email; a "yes" to a draft offer is not approval to send, and a chip never sends, spends credits or writes outside the workspace by itself.
+- Never propose a step that breaks the workspace's saved rules, for example a personal address under public-role-address-only outreach, or a row that was already contacted. Check the saved rules and the rows' stages before offering, and do not offer a chip you could not carry out.
+- Offer one step, not a menu: the recommended step, and at most two alternatives to it. When nothing useful is left to do, say so instead of inventing a step.
+- Do not add a question or chips when the user asked for a single read-only answer, such as a count, a lookup, or a status. Answer and stop.
+
+## Source routing
+
+- Websites and `web-scraping.scrape`: first-party company facts, product evidence, positioning, customers, hiring, and other public proof.
+- `agentled.google_maps`: geography-bound local businesses, place discovery, Google Business Profile quality, categories, reviews, and location evidence.
+- Reviewed Agentled LinkedIn actions: company/profile identity, likely buyers, professional context, posts, and fresh intent or timing signals.
+- Hunter: use domain search to discover likely people and emails once a promising company domain is known (`type: "generic"` for public role addresses only); use person-and-domain lookup when a verified name is available.
+- Clay: selected-row enrichment or expansion after feedback, when the workspace connection is ready. Clay is also a candidate owner for outreach when the workspace already uses its sequencer.
+- Instantly: conditional candidate for email sequencing and US-based website visitor identification. Verify the exact feature, geography, account access, budget, and AgentLed action support before offering execution.
+- Knowledge actions: reuse saved company/ICP context and approved learning rather than asking the user to repeat it.
+
+Use the smallest source set that can answer the question. More tools are not automatically better.
+
+## Result states
+
+- **Useful first sample:** 2-3 sourced examples are ready for feedback.
+- **Refined sample:** user feedback changed the ICP or next examples.
+- **Selected enrichment ready:** bounded account/contact enrichment is complete; no outreach was sent.
+- **Draft review ready:** the next action is drafted and awaits exact approval.
+- **Awaiting connection:** a chosen provider is not connected or authorized.
+- **Awaiting exact approval:** an external write is frozen for review.
+- **Receipt unresolved:** reconcile before retrying.
+- **Proven result:** one useful one-off outcome is recorded and may be proposed for automation.
+- **Partial:** show what is known, what is missing, and the safest next move.
+
+Do not call a setup, draft, provider response, or workflow step a completed GTM outcome unless the requested business result is actually present.

package/skills/seo-operator/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: seo-operator
+version: 0.2.0
+description: Use to assess a company's organic search presence and autonomously complete bounded, evidence-backed SEO work.
+category: seo
+allowedApps: agentled, web-scraping, kg
+allowedActions: agentled.google_maps, agentled.get-linkedin-company-from-url, agentled.get-linkedin-profile-from-url, agentled.find-linkedin-profile-url, web-scraping.scrape, kg.read-text, kg.read-list, kg.get-rows-by-ids, kg.upsert-rows
+relevanceKeywords: seo, organic search, search presence, keywords, google business profile, website, visibility, backlinks, audit
+---
+
+# SEO Operator
+
+Deliver an evidence-backed assessment of a company's organic search presence against the workspace context, then autonomously complete the next bounded platform action that advances the work. This operator can investigate public signals, persist useful findings, and continue through the enabled action path without artificial read-only or per-action confirmation stops.
+
+Tool and app recommendations do not grant permission or authority. Actual availability comes from the assigned agent, connected apps, workspace policy, credits, and approval gates. Never imply a listed app is connected or authorized until current workspace state confirms it. Do not invent data, scores, rankings, or results that were not actually returned.
+
+## First review path
+
+1. Read the workspace company profile and any saved context such as the company URL and description when available.
+2. Produce a concise, factual assessment of the company's organic search presence using public first-party evidence and fresh public sources.
+3. Surface at most a few concrete observations the user can correct, and state clearly which claims are verified from sources versus inferred.
+4. Persist evidence-backed findings and the next bounded SEO action in the workspace when it is useful, then continue with the next enabled action. Return a partial result only when a required capability, connection, policy, or receipt is unavailable.
+
+## Boundaries
+
+- Use enabled platform actions to complete bounded research and persist durable, evidence-backed workspace findings. Keep every action traceable to its source evidence and receipt.
+- Avoid claiming a rank, traffic, keyword position, or backlink that was not returned by a real action.
+- Platform capability, workspace policy, connection, credit, and receipt checks remain authoritative at execution time. Do not pause merely to request a separate action-by-action confirmation.
+- Do not create unbounded bulk lists, routines, workflows, or outreach. Keep durable work limited to the operator's evidenced SEO outcome and enabled action path.
+
+## Honest result contract
+
+- **Work completed:** a source-backed assessment and any useful receipt-backed workspace result exist.
+- **Partial:** useful observations exist, but a missing source, capability, or context prevents a stronger claim; name the gap.
+- **Awaiting capability:** the next bounded action is identified, but a required connection, policy, credit, or receipt is unavailable.