@usecoil/skill-claude 0.1.2 → 0.1.4

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.4 --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.2",
+  "version": "0.1.4",
   "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.5"
   },
   "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.5
 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.5
 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

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
@@ -130,6 +150,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.