@usecoil/skill-claude 0.1.1 → 0.1.3

package/README.md

@@ -1,11 +1,13 @@
 # Coil Claude Code Skill
 
-Installable Claude Code skill package for Coil agent workflows. It verifies the
-installed CLI and installs the compatible public `@usecoil/cli` package when
+Installable Claude Code skill package for Coil agent workflows. The command
+below is the exact install form for this immutable package. Confirm registry
+availability against the reviewed release manifest before use. It verifies the
+installed CLI and installs the compatible `@usecoil/cli` package when
 `coil` is not already available:
 
 ```bash
-npx --yes @usecoil/skill-claude@0.1.1 --base-url https://www.usecoil.com
+npx --yes @usecoil/skill-claude@0.1.3 --base-url https://www.usecoil.com
 coil config set-base-url https://www.usecoil.com --profile prod
 printf '%s' "$COIL_API_KEY" | coil auth login --profile prod --key -
 coil --profile prod agent-context --json

package/bin/install.mjs

@@ -307,6 +307,12 @@ function checkCli() {
       && fetchCount?.required === true
       && fetchCount?.minimum === 1
       && fetchCount?.maximum === 25;
+    const hasCommand = (group, name) => Array.isArray(context.commands?.[group]?.commands)
+      && context.commands[group].commands.some((command) => command?.name === name);
+    const hasLeadImport = hasCommand('leads', 'leads import');
+    const hasImportOutcomes = hasCommand('recipes', 'recipe-runs import-outcomes');
+    const hasImportedLeads = hasCommand('recipes', 'recipe-runs leads');
+    const hasNamedAgents = hasCommand('agents', 'agents list');
     const compatible = contextResult.status === 0
       && context.cli?.name === 'coil'
       && context.cli?.version === version.replace(/^v/, '')
@@ -314,7 +320,11 @@ function checkCli() {
       && hasSpendGate
       && hasStarterCap
       && Array.isArray(context.commands?.recipes?.commands)
-      && context.commands.recipes.commands.some((command) => command?.name === 'recipes run');
+      && context.commands.recipes.commands.some((command) => command?.name === 'recipes run')
+      && hasLeadImport
+      && hasImportOutcomes
+      && hasImportedLeads
+      && hasNamedAgents;
     return {
       ok: Boolean(compatible),
       present: true,
@@ -561,7 +571,7 @@ if (!cli.ok) {
 if (!cli.ok) {
   const rollbackFailed = installedCli && !rollbackCliInstall();
   const detail = cli.reason ?? (cli.version ? `Found ${cli.version}; supported versions are ${SUPPORTED_CLI_RANGE}.` : 'No coil executable was found.');
-  console.error(`Error: ${detail} Install @usecoil/cli ${PUBLIC_CLI_SPEC} from the public npm registry, or rerun with --cli-package <path-to-reviewed-tarball>.`);
+  console.error(`Error: ${detail} Install ${PUBLIC_CLI_SPEC} from the public npm registry, or rerun with --cli-package <path-to-reviewed-tarball>.`);
   if (rollbackFailed) console.error('Warning: automatic rollback of the newly installed Coil CLI failed; remove @usecoil/cli manually.');
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usecoil/skill-claude",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Claude Code skill package for Coil agent workflows",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "coilCompatibility": {
     "cli": "0.1.x",
-    "preferredVersion": "0.1.1"
+    "preferredVersion": "0.1.4"
   },
   "coilRuntime": {
     "name": "claude",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ it can do:
 
 ```bash
 if ! command -v coil >/dev/null 2>&1; then
-  npm install --global @usecoil/cli@0.1.1
+  npm install --global @usecoil/cli@0.1.4
 fi
 coil --version
 ```
@@ -77,7 +77,7 @@ The runtime-specific installer or registry handles placement; Coil operations
 always use the same public JSON CLI:
 
 ```bash
-npm install --global @usecoil/cli@0.1.1
+npm install --global @usecoil/cli@0.1.4
 coil config set-base-url https://www.usecoil.com --profile prod
 printf '%s' "$COIL_API_KEY" | coil auth login --profile prod --key -
 coil --profile prod agent-context --json
@@ -98,6 +98,44 @@ other runtimes may use their own secret manager. Do not add `COIL_ORG_ID`.
 - Diagnostics and errors go to stderr.
 - Global flags: `--profile`, `--base-url`, `--json`, `--output-version`.
 
+## Human action handoffs
+
+When a raw Coil API success response includes `meta.human_action`, or a blocked
+API error includes `error.details.human_action`, relay the returned action to
+the user. In CLI `--json` success output, object results and V2 list envelopes
+expose the same action as a top-level `human_action` field. The V1 automations
+result list keeps its array shape and adds `human_action` to the matching item.
+CLI errors preserve it under
+`error.details.human_action`. State whether it is required or recommended,
+include the exact `url` verbatim, and use its human-readable `label`. Do not
+say only “go to the dashboard,” fabricate a URL, or direct draft review to the
+public `/recipes` concept pages. If no specific recipe ID is available, use the
+server-approved `/dashboard/recipes/review` queue. Treat opening the URL as
+navigation only; the destination still authenticates and authorizes the human.
+
+Older Actor Lab responses may also contain `approval_url`. Preserve and relay
+that server-provided URL when present, while preferring the standardized
+`human_action` object for machine reasoning.
+
+Automation handoffs use the server-provided absolute `/automations` URL. After
+an agent creates or validates a draft, relay the required publication action
+verbatim: the human org admin must review and publish the draft. If a run or
+result has `reconciliation_required`, relay the required reconciliation action
+verbatim and do not retry the webhook. A policy-review action means a human
+must decide the governance policy; it is not an instruction to weaken policy.
+
+Provider integration status is a specific success-envelope case. When the
+current credential-scoped `execution_readiness` contains a `blocked` scope,
+`GET /api/integrations/{provider}` returns the same required Coil action at
+`meta.human_action` and the temporary compatibility alias `data.human_action`.
+The current CLI promotes one copy to top-level `human_action`; older clients
+that unwrap `data` still retain the alias. Relay the Coil `url` verbatim even
+when `execution_readiness[].actionUrl` is `null`. A non-null provider
+`actionUrl` is a separate safe external provider-authorization link. Do not
+invent, rewrite, or treat either URL as approval or authority. Automatic
+`open`, `half_open`, `degraded`, `ready`, and `unknown` states do not require
+this handoff.
+
 ## Common Workflows
 
 ### Orient
@@ -112,6 +150,24 @@ coil --profile prod auth status --json
 
 Use the server-derived activation state before starting a new workspace flow. Provider-backed runs require a healthy saved connection and explicit spend confirmation.
 
+`coil activation status --json` may include a server-provided `human_action`.
+State whether it is required or recommended and relay its absolute `url`
+verbatim. Do not map `nextAction` to a guessed dashboard route. `start_run`
+still needs explicit provider-spend confirmation; a human-action URL is only
+navigation and does not grant approval or authority.
+
+Machine recipe creation, draft updates, and template installation return a required
+`human_action` for the specific `/dashboard/recipes/{recipeId}` detail surface.
+Successful machine validation of a draft returns the same action. Relay its
+absolute `url` verbatim. A machine publish `403` preserves the scoped action in
+`error.details.human_action` when the draft exists; do not treat the URL as
+approval or authority.
+
+For `recipes create --json`, preserve every returned recipe field and relay the
+top-level `human_action` when the server provides it. If the response contains
+only `data` or omits valid metadata, report the unchanged recipe result. Never
+infer or fabricate a dashboard URL or human action.
+
 ```bash
 coil --profile prod activation status --json
 coil --profile prod marketplace templates --json
@@ -147,7 +203,24 @@ coil --profile prod recipe-runs cancel <run-id> --json
 coil --profile prod recipe-runs retry <run-id> --json
 ```
 
-Publication and ambiguous-effect reconciliation require a human organization admin. Retry/cancel behavior follows the durable run state returned by the API.
+Publication and ambiguous-effect reconciliation require a human organization admin. If a run has an unresolved provider effect, relay the server-provided `human_action.url` from the view/wait/watch state (or `error.details.human_action` from a machine reconcile denial) verbatim. The URL opens `/dashboard/recipe-runs/{runId}` for evidence review; it is navigation only and does not prove provider acceptance or authorize a decision. Retry/cancel behavior follows the durable run state and `next_actions`, not the presence of a URL.
+
+### Lead-list imports
+
+```bash
+coil --profile prod --json leads import ./prospects.csv --mapping '{"Work email":"email"}' --admission-key import-september-001
+coil --profile prod recipe-runs view <run-id> --json
+coil --profile prod recipe-runs import-outcomes <run-id> --outcome rejected --json
+coil --profile prod recipe-runs leads <run-id> --json
+```
+
+Imports accept at most 2,000 data rows and 2 MiB of CSV input. Use header
+mapping for ambiguous columns and a stable admission key when a retry could be
+uncertain. A `202` response means durable admission, not terminal success. Do
+not report completion until the run is terminal and its outcomes and attributed
+leads have been inspected. Rejected-row PII is not printed. Successful inputs
+are scrubbed after completion; failed or cancelled normalized replay data is
+retained for up to 30 days. The original CSV is never stored.
 
 ### Scrapes
 
@@ -175,6 +248,14 @@ coil --profile prod leads emails <scrape-id>
 
 API-key agents can create draft automations. Human org admins publish drafts after validation.
 
+Creation and successful draft validation may return a required `human_action`
+with an absolute `/automations` URL. Tell the user that the draft is ready but
+requires human admin review and publication, and relay `human_action.url`
+verbatim. A machine publish attempt returns the same structured action in the
+403 error details. When run or result state is `reconciliation_required`, the
+same operations URL is a required human reconciliation handoff; never infer a
+URL from a status string or replay the ambiguous webhook.
+
 ```bash
 coil --profile prod automations create --name "Enrich leads" --webhook-url "https://hooks.example.com/enrich" --input-fields email,company_name --scope global --json
 coil --profile prod automations list --status draft --json --output-version 2

package/skill/references/api-endpoints.md

@@ -11,6 +11,12 @@ Content-Type: application/json
 
 Coil organization API keys (`ak_...`) are accepted by agent-compatible routes.
 
+Coil first-party credentials authenticate durable named agents. The agent ID is
+the machine actor ID; the credential ID identifies only one credential.
+Existing credentials were identity-preserving backfilled. Credential
+administration requires a human organization admin, and permanent credential
+plaintext is returned only once.
+
 ## Auth and Context
 
 | Method | Path | Notes |
@@ -20,12 +26,31 @@ Coil organization API keys (`ak_...`) are accepted by agent-compatible routes.
 | DELETE | `/api/auth/api-keys/{id}` | Revokes a Coil organization API key for human org admins. |
 | POST | `/api/auth/verify-key` | Verifies a Coil organization API key without exposing it. |
 
+Named-agent management is human-admin only:
+
+| Method | Path | CLI |
+| --- | --- | --- |
+| GET | `/api/agents` | `coil agents list --json` |
+| POST | `/api/agents` | `coil agents create --name ... --json` |
+| GET | `/api/agents/{id}` | `coil agents view <agent-id> --json` |
+| POST | `/api/agents/{id}/setup` | `coil agents setup <agent-id> --runtime ... --profile ... --json` |
+| POST | `/api/agents/{id}/credentials` | `coil agents issue-credential <agent-id> --json` |
+| DELETE | `/api/agents/{id}/credentials/{credentialId}` | `coil agents revoke-credential <agent-id> <credential-id> --json` |
+
+`--replace` changes the generated local setup command. It does not revoke an
+existing credential. Replacement credentials keep the same durable agent ID.
+
 CLI discovery wrapper:
 
 ```bash
 coil agent-context --json
 ```
 
+When a response requires or recommends a human web handoff, the API returns a
+typed `human_action` in success `meta` or blocked error `details`, and the CLI
+preserves it in JSON output. Agents must relay the exact URL and its required
+or recommended state. The URL does not grant authority or imply approval.
+
 ## Activation, Marketplace, and Recipes
 
 | Method | Path | CLI |
@@ -71,6 +96,20 @@ Machine callers can create scrapes. Admin-gated destructive routes require a hum
 | PATCH | `/api/leads/bulk` | `coil leads bulk-update --ids ... --fields '{...}' --json` |
 | POST | `/api/export/csv` | `coil leads export <scrape-id> [--filter/--view/--ids] [--output]` |
 | GET | `/api/leads/emails?scrapeId={id}` | `coil leads emails <scrape-id>` |
+| POST | `/api/leads/import` | `coil --json leads import <file> [--mapping ...] [--admission-key ...]` |
+| GET | `/api/recipe-runs/{id}/import-outcomes` | `coil recipe-runs import-outcomes <run-id> --outcome rejected --json` |
+| GET | `/api/recipe-runs/{id}/leads` | `coil recipe-runs leads <run-id> --json` |
+
+Lead-list imports accept at most 2,000 data rows and 2 MiB of CSV input. The
+CLI maps supported headers before admission; use `--mapping` for ambiguous
+headers and a stable `--admission-key` when a retry may be uncertain. A `202`
+response means durable admission, not terminal success. Inspect
+`coil recipe-runs view`, `coil recipe-runs import-outcomes`, and
+`coil recipe-runs leads` and wait for a terminal run state before reporting
+completion. The API is organization-scoped, does not retain the original CSV,
+and does not print rejected-row PII. Successful inputs are scrubbed after
+completion; failed or cancelled normalized replay data is retained for up to
+30 days.
 
 ## Automations
 
@@ -95,6 +134,12 @@ Machine callers can create scrapes. Admin-gated destructive routes require a hum
 
 API-key callers create draft automations. Publishing, deletion, and policy changes require a human org admin session. Automation result links are deliberately narrow traceability records for delivery evidence; they are not a generic metadata surface.
 
+Draft creation/validation, unresolved automation run/result reads, and exact
+admission replays of unresolved runs may include
+`meta.human_action` with the absolute `/automations` review or reconciliation
+URL. Machine publication and reconciliation attempts preserve the same action
+under `error.details.human_action`.
+
 ## Settings, Preferences, Members
 
 | Method | Path | CLI |
@@ -119,6 +164,17 @@ API-key callers create draft automations. Publishing, deletion, and policy chang
 | GET | `/api/integrations/smartlead/campaigns/sequences?campaignId={id}` | `coil smartlead sequences --campaign <id> --json` |
 | POST | `/api/integrations/smartlead/send` | `coil smartlead send <scrape-id> --campaign <id> --json` |
 
+`GET /api/integrations/{provider}` includes current credential-scoped
+`execution_readiness`. For a `blocked` scope, the response returns one
+server-generated absolute Coil operator URL at canonical `meta.human_action`
+and the temporary compatibility alias `data.human_action`. Relay that Coil URL
+verbatim even when `execution_readiness[].actionUrl` is `null`. The CLI exposes
+one top-level `human_action` in JSON and an explicit text-mode URL. A safe,
+non-null `execution_readiness[].actionUrl` remains a separate provider-side
+authorization link and must not be rewritten or treated as Coil approval.
+`open`, `half_open`, `degraded`, `ready`, and `unknown` states do not include a
+required human action.
+
 ## Feedback
 
 | Method | Path | CLI |

package/skill/references/api-fields.md

@@ -32,6 +32,44 @@ Use `--json --output-version 2` on list commands when possible:
 }
 ```
 
+## Human action
+
+API success envelopes may include `meta.human_action`; blocked errors may
+include the same object at `error.details.human_action`:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `kind` | `approval`/`review`/`reconciliation`/`operator_intervention` | Human handoff category. |
+| `required` | boolean | Whether the human action is required to continue. |
+| `label` | string | Short human-readable action description. |
+| `url` | absolute HTTP(S) URL | Server-provided navigation URL. It is not a bearer token or approval capability. |
+| `resource_type` | string/null | Optional Coil resource type. |
+| `resource_id` | string/null | Optional resource identifier. |
+
+The CLI preserves this action as a top-level `human_action` field for object
+JSON results and V2 list envelopes. The V1 automations result list keeps its
+array shape and adds `human_action` to the matching item. Text mode prints the
+URL explicitly. Do not invent
+one when the server does not return it. Legacy Actor Lab `approval_url` remains
+available during the compatibility window.
+
+### Provider integration status
+
+`GET /api/integrations/{provider}` reports the current credential-scoped
+`execution_readiness` records. If a current scope is `blocked`, the raw API
+success envelope contains the same `Human action` object at both
+`meta.human_action` (canonical) and `data.human_action` (temporary compatibility
+alias for clients that unwrap `data`). The current CLI exposes one copy as
+top-level `human_action` in JSON and prints its label and URL explicitly in
+text mode.
+
+`execution_readiness[].actionUrl` remains the separately validated provider
+authorization URL and may be `null`; it must not be copied into the Coil
+action. Relay the absolute Coil URL verbatim even when the provider URL is
+`null`. Only `blocked` requires this operator handoff. `open`, `half_open`,
+`degraded`, `ready`, and `unknown` retain automatic retry or reconciliation
+semantics and do not advertise required human intervention.
+
 ## Scrape
 
 | Field | Type | Notes |
@@ -125,8 +163,8 @@ Supported operators include equality, contains, empty/not-empty, booleans, and d
 | `scrape_id` | string/null | Required for scrape-scoped automation. |
 | `status` | `draft`/`published`/`disabled` | API-key agents create drafts. |
 | `created_by_actor_type` | `human`/`machine` | Actor attribution. |
-| `created_by_actor_id` | string | User ID or API key ID. |
-| `created_by_actor_name` | string/null | API key display name when available. |
+| `created_by_actor_id` | string | User ID or durable Coil agent ID. |
+| `created_by_actor_name` | string/null | Durable agent display name when available. |
 | `published_by_user_id` | string/null | Human admin publisher. |
 | `published_at` | ISO string/null | Publication timestamp. |
 
@@ -149,12 +187,18 @@ Create payload:
 | `id` | string | UUID. |
 | `automation_id` | string | Parent automation. |
 | `lead_id` | string | Processed lead. |
-| `status` | `pending`/`running`/`success`/`error` | Delivery state. |
+| `status` | `pending`/`running`/`success`/`error`/`cancelled`/`reconciliation_required` | Delivery state. `reconciliation_required` is ambiguous provider delivery and requires a human action; it is never a retry instruction. |
 | `result` | string/null | Webhook response or summary. |
 | `error_message` | string/null | Failure detail. |
 | `created_at` | ISO string | Creation timestamp. |
 | `updated_at` | ISO string | Last status update. |
 
+When automation creation or draft validation requires publication, or an
+automation run/result requires reconciliation, the API returns
+`meta.human_action` (or `error.details.human_action` for a blocked request).
+The URL is an absolute, secret-free `/automations` navigation URL. Relay it
+verbatim; opening it does not grant approval or change policy.
+
 ## Automation Result Link
 
 | Field | Type | Notes |
@@ -198,5 +242,9 @@ Settings are stored in org-scoped JSON. Common keys:
 ## Agent Caveats
 
 - API-key agents currently behave as org members, not org admins.
+- A first-party credential authenticates a durable named agent. Credential IDs and agent IDs are separate; existing credentials were identity-preserving backfilled.
+- Browser credential checking does not update `last_used_at` and does not prove that an external agent runtime is connected.
+- Replacement uses temporary credential overlap and explicit old-credential revocation.
+- Clerk organization API keys remain a separate compatibility path.
 - Admin-gated actions include destructive scrape/automation operations, automation policy management, and automation publishing.
 - Prefer `coil feedback` for platform friction discovered while operating Coil.