@usecoil/skill-claude 0.1.2 → 0.1.3

package/README.md

@@ -7,7 +7,7 @@ installed CLI and installs the compatible `@usecoil/cli` package when
 `coil` is not already available:
 
 ```bash
-npx --yes @usecoil/skill-claude@0.1.2 --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.2",
+  "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.2"
+    "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.2
+  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.2
+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
@@ -124,6 +124,18 @@ 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
@@ -193,6 +205,23 @@ coil --profile prod recipe-runs retry <run-id> --json
 
 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
 
 ```bash

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,6 +26,20 @@ 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
@@ -76,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
 
@@ -130,6 +164,17 @@ under `error.details.human_action`.
 | 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

@@ -53,6 +53,23 @@ 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 |
@@ -146,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. |
 
@@ -225,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.