@usecoil/skill-claude 0.1.0 → 0.1.2

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.0 --base-url https://www.usecoil.com
+npx --yes @usecoil/skill-claude@0.1.2 --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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usecoil/skill-claude",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Claude Code skill package for Coil agent workflows",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "coilCompatibility": {
     "cli": "0.1.x",
-    "preferredVersion": "0.1.0"
+    "preferredVersion": "0.1.2"
   },
   "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.0
+  npm install --global @usecoil/cli@0.1.2
 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.0
+npm install --global @usecoil/cli@0.1.2
 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,32 @@ 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.
+
 ## Common Workflows
 
 ### Orient
@@ -112,6 +138,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 +191,7 @@ 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.
 
 ### Scrapes
 
@@ -175,6 +219,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

@@ -26,6 +26,11 @@ CLI discovery wrapper:
 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 |
@@ -95,6 +100,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 |

package/skill/references/api-fields.md

@@ -32,6 +32,27 @@ 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.
+
 ## Scrape
 
 | Field | Type | Notes |
@@ -149,12 +170,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 |