clawdentity 0.0.9 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdentity",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/skill-bundle/openclaw-skill/skill/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: clawdentity_openclaw_relay
-description: This skill should be used when the user asks to install or configure Clawdentity relay for OpenClaw agents and prepare them for pairing and message delivery.
-version: 0.2.0
+description: This skill should be used when the user asks to "set up Clawdentity relay", "pair two agents", "verify an agent token", "rotate API key", "refresh agent auth", "revoke an agent", "troubleshoot relay", "uninstall connector service", or needs OpenClaw relay onboarding, lifecycle management, or pairing workflows.
+version: 0.3.0
 ---
 
 # Clawdentity OpenClaw Relay Skill
 
 This skill prepares a local OpenClaw agent in a strict sequence:
-1. finish registry onboarding and generate/store API key
+1. finish registry onboarding by redeeming an invite (`clw_inv_...`) and store API key
 2. create local agent identity
 3. configure relay runtime
 4. become ready to start or accept QR pairing
 
+After setup, this skill also covers lifecycle operations: token refresh, API key rotation, agent revocation, service teardown, and token verification.
+
 Relay invite codes are not part of this flow.
 
 ## Filesystem Truth (must be used exactly)
@@ -34,20 +36,35 @@ Relay invite codes are not part of this flow.
 - Agent config: `~/.clawdentity/config.json`
 - Agent identity directory: `~/.clawdentity/agents/<agent-name>/`
 - Agent private key: `~/.clawdentity/agents/<agent-name>/secret.key`
+- Agent public key: `~/.clawdentity/agents/<agent-name>/public.key`
+- Agent identity metadata: `~/.clawdentity/agents/<agent-name>/identity.json`
+- Agent registry auth: `~/.clawdentity/agents/<agent-name>/registry-auth.json`
 - Agent AIT token: `~/.clawdentity/agents/<agent-name>/ait.jwt`
 - Peer map: `~/.clawdentity/peers.json`
 - Local selected agent marker: `~/.clawdentity/openclaw-agent-name`
 - Relay runtime config: `~/.clawdentity/openclaw-relay.json`
 - Connector assignment map: `~/.clawdentity/openclaw-connectors.json`
 
+### Pairing ephemeral files
+- QR PNG storage: `~/.clawdentity/pairing/` (auto-cleaned after 900s)
+
+### Cache files
+- Registry signing keys cache: `~/.clawdentity/cache/registry-keys.json` (1-hour TTL)
+- Certificate revocation list cache: `~/.clawdentity/cache/crl-claims.json` (15-minute TTL)
+
 ## Inputs
 
 Required for onboarding:
-- Registry onboarding invite code: `clw_inv_...` (or existing local API key)
+- Registry onboarding invite code: `clw_inv_...` (default onboarding path)
 - Local agent name
 
+Optional only for recovery/advanced operator flows:
+- Existing API key (only when user explicitly says no invite is available)
+
 Required for pairing phase (after setup):
-- Pairing QR from the other side (`clwpair1_...` inside QR image)
+- Pairing QR from the other side (`clwpair1_...` inside QR image) or inline ticket string
+
+Note: Registry operators must run `admin bootstrap` before creating invites. See `references/clawdentity-registry.md` for details.
 
 ## Tool Execution Contract (Agent)
 
@@ -58,21 +75,69 @@ Required for pairing phase (after setup):
 
 ## Command Utilization (required)
 
+### Config management
 - `clawdentity config init`
 - `clawdentity config init --registry-url <registry-url>`
 - `clawdentity config set registryUrl <registry-url>`
+- `clawdentity config set proxyUrl <proxy-url>`
+- `clawdentity config set apiKey <api-key>` (manual recovery only)
+- `clawdentity config get <key>`
+- `clawdentity config show`
+
+### Invite management
 - `clawdentity invite redeem <registry-invite-code>`
 - `clawdentity invite redeem <registry-invite-code> --registry-url <registry-url>`
-- `clawdentity config set apiKey <api-key>` (fallback only when invite is unavailable)
+- `clawdentity invite create` (admin only, see registry reference)
+- `clawdentity invite create --expires-at <iso-8601>` (admin only)
+
+### Agent identity
 - `clawdentity agent create <agent-name> --framework openclaw`
+- `clawdentity agent create <agent-name> --framework openclaw --ttl-days <days>`
 - `clawdentity agent inspect <agent-name>`
+- `clawdentity agent auth refresh <agent-name>`
+- `clawdentity agent revoke <agent-name>`
+
+### API key lifecycle
+- `clawdentity api-key create`
+- `clawdentity api-key list`
+- `clawdentity api-key revoke <api-key-id>`
+
+### OpenClaw relay setup
 - `clawdentity openclaw setup <agent-name>`
-- `clawdentity connector start <agent-name>`
-- `clawdentity connector service install <agent-name>` (optional)
+- `clawdentity openclaw setup <agent-name> --transform-source <path>`
+- `clawdentity openclaw setup <agent-name> --openclaw-dir <path> --openclaw-base-url <url>`
+
+### OpenClaw diagnostics
 - `clawdentity openclaw doctor`
-- `clawdentity openclaw relay test` (auto-selects when one peer exists)
+- `clawdentity openclaw doctor --peer <alias>`
+- `clawdentity openclaw doctor --json`
+- `clawdentity openclaw relay test`
+- `clawdentity openclaw relay test --peer <alias> --hook-token <token> --json`
+- `clawdentity openclaw relay test --session-id <id> --message <text>`
+
+### Connector runtime
+- `clawdentity connector start <agent-name>`
+- `clawdentity connector start <agent-name> --proxy-ws-url <url>`
+- `clawdentity connector start <agent-name> --openclaw-hook-token <token>`
+- `clawdentity connector service install <agent-name>`
+- `clawdentity connector service install <agent-name> --platform <auto|launchd|systemd>`
+- `clawdentity connector service uninstall <agent-name>`
+- `clawdentity connector service uninstall <agent-name> --platform <auto|launchd|systemd>`
+
+### Pairing
 - `clawdentity pair start <agent-name> --qr`
+- `clawdentity pair start <agent-name> --qr --qr-output <path>`
+- `clawdentity pair start <agent-name> --qr --owner-pat <token> --proxy-url <url> --ttl-seconds <seconds>`
 - `clawdentity pair confirm <agent-name> --qr-file <path>`
+- `clawdentity pair confirm <agent-name> --ticket <clwpair1_...>`
+- `clawdentity pair confirm <agent-name> --ticket <clwpair1_...> --proxy-url <url>`
+
+### Token verification
+- `clawdentity verify <tokenOrFile>`
+
+### Admin (registry operators only)
+- `clawdentity admin bootstrap --bootstrap-secret <secret>`
+- `clawdentity admin bootstrap --bootstrap-secret <secret> --display-name <name> --api-key-name <name> --registry-url <url>`
 
 ## Journey (strict order)
 
@@ -84,7 +149,9 @@ Required for pairing phase (after setup):
 - If `--invite-code` appears, treat CLI as outdated and upgrade before continuing:
   - `npm install -g clawdentity@latest`
 - Confirm local agent name.
-- Confirm either existing API key or `clw_inv_...`.
+- Check local API key status with `clawdentity config get apiKey`.
+- If API key is missing, ask for onboarding invite `clw_inv_...` and continue with invite redeem.
+- Do not ask for raw API key unless the user explicitly says invite is unavailable.
 - Confirm OpenClaw path/base URL only if non-default.
 - Do not ask for pairing inputs before onboarding is complete.
 
@@ -97,8 +164,9 @@ Required for pairing phase (after setup):
 - If needed, run with `--registry-url`.
 
 4. Finish onboarding and generate API key.
-- If API key already exists locally, continue.
-- Else run `clawdentity invite redeem <clw_inv_...>`.
+- Preferred path: run `clawdentity invite redeem <clw_inv_...>`.
+- If local API key already exists and user explicitly wants to reuse it, continue without redeem.
+- Use `config set apiKey` only as a manual recovery path when user cannot provide invite.
 - Confirm output shows:
   - `Invite redeemed`
   - API key token printed once
@@ -107,6 +175,7 @@ Required for pairing phase (after setup):
 
 5. Create local OpenClaw agent identity.
 - Run `clawdentity agent create <agent-name> --framework openclaw`.
+- Optionally add `--ttl-days <days>` to control token lifetime.
 - Run `clawdentity agent inspect <agent-name>`.
 
 6. Configure relay setup.
@@ -115,45 +184,129 @@ Required for pairing phase (after setup):
 - Add optional:
   - `--openclaw-dir <path>`
   - `--openclaw-base-url <url>`
+  - `--transform-source <path>` (custom relay transform location)
 - Verify output contains self-setup completion, OpenClaw config path, and relay runtime path.
 
 7. Start connector runtime.
 - Run `clawdentity connector start <agent-name>`.
+- For non-default proxy: add `--proxy-ws-url <url>`.
+- Connector auto-loads hook token from `openclaw-relay.json` when `--openclaw-hook-token` is not provided.
 - Optional persistent mode: `clawdentity connector service install <agent-name>`.
 
 8. Validate readiness.
 - Run `clawdentity openclaw doctor`.
+- Use `--json` for machine-readable output.
+- Use `--peer <alias>` to validate a specific peer exists after pairing.
+- Doctor check IDs and remediation:
+
+| Check ID | Validates | Remediation on Failure |
+|----------|-----------|----------------------|
+| `config.registry` | `registryUrl` and `apiKey` in config | `clawdentity config init` or `config set registryUrl` / `config set apiKey` |
+| `state.selectedAgent` | Agent marker at `~/.clawdentity/openclaw-agent-name` | `clawdentity openclaw setup <agent-name>` |
+| `state.credentials` | `ait.jwt` and `secret.key` exist and non-empty | `clawdentity agent create <agent-name>` or `agent auth refresh <agent-name>` |
+| `state.peers` | Peers config valid; requested `--peer` alias exists | `clawdentity pair start` / `pair confirm` (optional until pairing) |
+| `state.transform` | Relay transform artifacts in OpenClaw hooks dir | Reinstall skill package or `openclaw setup <agent-name>` |
+| `state.hookMapping` | `send-to-peer` hook mapping in OpenClaw config | `clawdentity openclaw setup <agent-name>` |
+| `state.hookToken` | Hooks enabled with token in OpenClaw config | `clawdentity openclaw setup <agent-name>` then restart OpenClaw |
+| `state.openclawBaseUrl` | OpenClaw base URL resolvable | `clawdentity openclaw setup <agent-name> --openclaw-base-url <url>` |
+
 - At this point the agent is ready to start pairing or accept pairing.
 
 9. Pairing phase (separate from onboarding).
 - Initiator: `clawdentity pair start <agent-name> --qr`
-- Responder: `clawdentity pair confirm <agent-name> --qr-file <path>`
+  - Optional overrides: `--owner-pat <token>`, `--proxy-url <url>`, `--ttl-seconds <seconds>`, `--qr-output <path>`
+  - Owner PAT defaults to configured API key when `--owner-pat` is omitted.
+- Responder (two mutually exclusive paths):
+  - QR path: `clawdentity pair confirm <agent-name> --qr-file <path>`
+  - Inline ticket path: `clawdentity pair confirm <agent-name> --ticket <clwpair1_...>`
+  - Cannot provide both `--qr-file` and `--ticket` simultaneously.
+  - Add `--proxy-url <url>` to override responder proxy.
 - Pair confirm auto-saves peer DID/proxy mapping locally from QR ticket metadata.
 - Confirm pairing success, then run `clawdentity openclaw relay test`.
 
+10. Post-pairing verification.
+- Run `clawdentity verify <path-to-ait.jwt>` to confirm the local agent token is valid.
+- Verify output shows token status, expiry, and no revocation.
+- Run `clawdentity openclaw doctor --peer <alias>` to confirm the new peer is visible.
+- Run `clawdentity openclaw relay test` to confirm end-to-end message delivery.
+- Note: `relay test` runs preflight doctor checks before sending the probe.
+
+## Lifecycle Management
+
+### Token expiry recovery
+1. Run `clawdentity agent auth refresh <agent-name>`.
+2. Restart connector: `clawdentity connector start <agent-name>` (or reinstall service).
+3. Verify with `clawdentity agent inspect <agent-name>` to confirm new expiry.
+
+### API key rotation
+1. Create new key: `clawdentity api-key create`.
+2. Save new key: `clawdentity config set apiKey <new-api-key-token>`.
+3. Revoke old key: `clawdentity api-key revoke <old-api-key-id>`.
+4. Verify with `clawdentity config get apiKey`.
+
+### Agent decommission
+1. Revoke agent: `clawdentity agent revoke <agent-name>`.
+2. Revocation is idempotent; repeat calls are safe.
+3. CRL propagation may lag up to 15 minutes for verifiers using cached CRL.
+
+### Service teardown
+1. Uninstall service: `clawdentity connector service uninstall <agent-name>`.
+2. Idempotent; safe to run even if service was already removed.
+3. Use `--platform <auto|launchd|systemd>` to target a specific platform.
+
+### Token verification
+- Verify any AIT: `clawdentity verify <tokenOrFile>`.
+- Accepts raw JWT string or file path containing the token.
+- Uses cached registry keys (1h TTL) and CRL (15min TTL).
+- Exit code 1 on verification failure or revocation.
+
 ## Required Question Policy
 
 Ask only when missing:
 - local agent name
-- onboarding invite (`clw_inv_...`) when API key is absent
+- onboarding invite (`clw_inv_...`) unless user explicitly requests API-key recovery path
 - non-default OpenClaw path/base URL
-- pairing QR image path for confirm
+- pairing QR image path or ticket string for confirm
 
 Do not ask for relay invite codes.
 Do not ask for `clawd1_...` values.
+Do not state that API key is required before invite redeem.
+Do not suggest switching endpoints unless user explicitly asks for endpoint changes.
 
 ## Failure Handling
 
+### Connector errors
+- `404` on outbound endpoint: connector not running. Restart with `clawdentity connector start <agent-name>`.
+- `409` on outbound: peer snapshot stale. Rerun `clawdentity openclaw setup <agent-name>` then restart connector.
+- `CLI_CONNECTOR_MISSING_AGENT_MATERIAL`: agent credentials missing. Rerun `clawdentity agent create <agent-name>` or `clawdentity agent auth refresh <agent-name>`.
+
+### Pairing errors
+- `pair start` 401 (`PROXY_PAIR_OWNER_PAT_INVALID`): owner PAT is invalid or expired. Rotate API key or provide valid `--owner-pat`.
+- `pair start` 403 (`PROXY_PAIR_OWNER_PAT_FORBIDDEN`): owner PAT does not control initiator agent DID.
+- `pair confirm` 404 (`PROXY_PAIR_TICKET_NOT_FOUND`): ticket is invalid or expired. Request a new ticket from initiator.
+- `pair confirm` 410 (`PROXY_PAIR_TICKET_EXPIRED`): ticket has expired. Request a new ticket.
+- `CLI_PAIR_CONFIRM_INPUT_CONFLICT`: cannot provide both `--ticket` and `--qr-file`. Use one path only.
+- `CLI_PAIR_PROXY_URL_REQUIRED`: proxy URL could not be resolved. Run `clawdentity config set proxyUrl <url>`.
+
+### Setup errors
+- `405 Method Not Allowed` on hook path: rerun `clawdentity openclaw setup <agent-name>` and restart OpenClaw.
+- `CLI_OPENCLAW_MISSING_AGENT_CREDENTIALS` or `CLI_OPENCLAW_EMPTY_AGENT_CREDENTIALS`: agent credentials missing or empty. Rerun `agent create` or `agent auth refresh`.
+
+### Credential expiry
+- Agent AIT expired: run `clawdentity agent auth refresh <agent-name>` then restart connector.
+- API key invalid (401 on registry calls): rotate with `api-key create` then `config set apiKey`.
+
+### General recovery
 - Report exact missing file/value.
 - Fix only failing input/config.
 - Keep connector running while testing relay delivery.
-- If `405 Method Not Allowed` appears on hook path, rerun setup and restart OpenClaw.
 - Re-run `openclaw doctor`, then `openclaw relay test`.
 
 ## Bundled Resources
 
 | File | Purpose |
 |------|---------|
-| `references/clawdentity-protocol.md` | Peer-map schema, pairing contract, connector handoff envelope, runtime failure mapping |
+| `references/clawdentity-protocol.md` | Peer-map schema, pairing contract, connector handoff envelope, proxy URL resolution, pairing error codes, cache files, peer alias derivation |
+| `references/clawdentity-registry.md` | Admin bootstrap, API key lifecycle, agent revocation, auth refresh |
 
-Directive: read the reference file before troubleshooting relay contract or connector handoff failures.
+Directive: read the reference files before troubleshooting relay contract, connector handoff failures, or registry/admin operations.

package/skill-bundle/openclaw-skill/skill/references/clawdentity-protocol.md

@@ -20,11 +20,17 @@ Define the exact runtime contract used by `relay-to-peer.mjs`.
 ### Clawdentity files
 - `~/.clawdentity/config.json`
 - `~/.clawdentity/agents/<agent-name>/secret.key`
+- `~/.clawdentity/agents/<agent-name>/public.key`
+- `~/.clawdentity/agents/<agent-name>/identity.json`
+- `~/.clawdentity/agents/<agent-name>/registry-auth.json`
 - `~/.clawdentity/agents/<agent-name>/ait.jwt`
 - `~/.clawdentity/peers.json`
 - `~/.clawdentity/openclaw-agent-name`
 - `~/.clawdentity/openclaw-relay.json`
 - `~/.clawdentity/openclaw-connectors.json`
+- `~/.clawdentity/pairing/` (ephemeral QR PNG storage, auto-cleaned after 900s)
+- `~/.clawdentity/cache/registry-keys.json` (1-hour TTL, used by `verify`)
+- `~/.clawdentity/cache/crl-claims.json` (15-minute TTL, used by `verify`)
 
 ## Setup Input Contract
 
@@ -173,3 +179,77 @@ Relay fails when:
 - local connector outbound request fails (network/other non-2xx)
 
 Error messages should include file/path context but never print secret content.
+
+## Proxy URL Resolution
+
+CLI resolves proxy URL in this order (first non-empty wins):
+
+1. `--proxy-url` flag (explicit override)
+2. `CLAWDENTITY_PROXY_URL` environment variable
+3. `proxyUrl` from `~/.clawdentity/config.json`
+4. Derived from `registryUrl` using hostname mapping
+5. Error: `CLI_PAIR_PROXY_URL_REQUIRED`
+
+### Hostname mapping (registry to proxy)
+
+| Registry hostname | Proxy hostname |
+|-------------------|---------------|
+| `registry.clawdentity.com` | `proxy.clawdentity.com` |
+| `dev.registry.clawdentity.com` | `dev.proxy.clawdentity.com` |
+| `dev.registry.<domain>` | `dev.proxy.<domain>` |
+| `registry.<domain>` | `proxy.<domain>` |
+| `localhost:8788` | `localhost:8787` |
+| `127.0.0.1:8788` | `127.0.0.1:8787` |
+| `host.docker.internal:8788` | `host.docker.internal:8787` |
+
+If registry hostname does not match any pattern, derivation returns undefined and resolution falls through to error.
+
+Recovery: `clawdentity config set proxyUrl <url>`.
+
+## Pairing Error Codes
+
+### `pair start` errors
+
+| HTTP Status | Error Code | Meaning |
+|-------------|-----------|---------|
+| 401 | `PROXY_PAIR_OWNER_PAT_INVALID` | Owner PAT is invalid or expired |
+| 403 | `PROXY_PAIR_OWNER_PAT_FORBIDDEN` | Owner PAT does not control initiator agent DID |
+| — | `CLI_PAIR_AGENT_NOT_FOUND` | Agent ait.jwt or secret.key missing/empty |
+| — | `CLI_PAIR_START_OWNER_PAT_REQUIRED` | Owner PAT not provided and no API key configured |
+| — | `CLI_PAIR_PROXY_URL_REQUIRED` | Proxy URL could not be resolved |
+| — | `CLI_PAIR_START_INVALID_TTL` | ttlSeconds must be a positive integer |
+| — | `CLI_PAIR_INVALID_PROXY_URL` | Proxy URL is invalid |
+| — | `CLI_PAIR_REQUEST_FAILED` | Unable to connect to proxy URL |
+
+### `pair confirm` errors
+
+| HTTP Status | Error Code | Meaning |
+|-------------|-----------|---------|
+| 404 | `PROXY_PAIR_TICKET_NOT_FOUND` | Pairing ticket is invalid or expired |
+| 410 | `PROXY_PAIR_TICKET_EXPIRED` | Pairing ticket has expired |
+| — | `CLI_PAIR_CONFIRM_TICKET_REQUIRED` | Either --ticket or --qr-file is required |
+| — | `CLI_PAIR_CONFIRM_INPUT_CONFLICT` | Cannot provide both --ticket and --qr-file |
+| — | `CLI_PAIR_CONFIRM_TICKET_INVALID` | Pairing ticket is invalid |
+| — | `CLI_PAIR_CONFIRM_QR_FILE_NOT_FOUND` | QR file not found |
+| — | `CLI_PAIR_CONFIRM_QR_NOT_FOUND` | No pairing QR code found in image |
+
+## Cache Files
+
+| Path | TTL | Used By |
+|------|-----|---------|
+| `~/.clawdentity/cache/registry-keys.json` | 1 hour | `verify` command — cached registry signing public keys |
+| `~/.clawdentity/cache/crl-claims.json` | 15 minutes | `verify` command — cached certificate revocation list |
+
+Cache is populated on first `verify` call and refreshed when TTL expires. Stale cache is used as fallback when registry is unreachable.
+
+## Peer Alias Derivation
+
+When `pair confirm` saves a new peer, alias is derived automatically:
+
+1. Parse peer DID to extract ULID component.
+2. Take last 8 characters of ULID, lowercase: `peer-<last8>`.
+3. If alias already exists in `peers.json` for a different DID, append numeric suffix: `peer-<last8>-2`, `peer-<last8>-3`, etc.
+4. If peer DID already exists in `peers.json`, reuse existing alias (no duplicate entry).
+5. Fallback alias is `peer` if DID is not a valid agent DID.
+
+Alias validation: `[a-zA-Z0-9._-]`, max 128 characters.

package/skill-bundle/openclaw-skill/skill/references/clawdentity-registry.md

@@ -0,0 +1,175 @@
+# Clawdentity Registry Operations Reference
+
+## Purpose
+
+Document registry-side CLI commands that are outside the core relay setup journey: admin bootstrap, API key lifecycle, agent revocation, and auth refresh.
+
+## Admin Bootstrap
+
+Bootstrap creates the first admin human and API key on a fresh registry. This is a prerequisite before any invites can be created.
+
+### Command
+
+```
+clawdentity admin bootstrap --bootstrap-secret <secret>
+```
+
+### Flags
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--bootstrap-secret <secret>` | Yes | One-time bootstrap secret configured on registry server |
+| `--display-name <name>` | No | Admin display name |
+| `--api-key-name <name>` | No | Admin API key label |
+| `--registry-url <url>` | No | Override registry URL |
+
+### Expected Output
+
+```
+Admin bootstrap completed
+Human DID: did:claw:human:01H...
+API key name: <name>
+API key token (shown once):
+<token>
+API key saved to local config
+```
+
+### Error Codes
+
+| Error Code | Meaning |
+|------------|---------|
+| `ADMIN_BOOTSTRAP_DISABLED` | Bootstrap is disabled on the registry |
+| `ADMIN_BOOTSTRAP_UNAUTHORIZED` | Bootstrap secret is invalid |
+| `ADMIN_BOOTSTRAP_ALREADY_COMPLETED` | Admin already exists; bootstrap is one-time |
+| `ADMIN_BOOTSTRAP_INVALID` | Request payload is invalid |
+| `CLI_ADMIN_BOOTSTRAP_SECRET_REQUIRED` | Bootstrap secret was not provided |
+| `CLI_ADMIN_BOOTSTRAP_INVALID_REGISTRY_URL` | Registry URL is invalid |
+| `CLI_ADMIN_BOOTSTRAP_REQUEST_FAILED` | Unable to connect to registry |
+| `CLI_ADMIN_BOOTSTRAP_CONFIG_PERSISTENCE_FAILED` | Failed to save admin credentials locally |
+
+### Behavioral Notes
+
+- One-time operation: succeeds only on first call per registry.
+- Automatically persists `registryUrl` and `apiKey` to local config.
+- Registry must have `BOOTSTRAP_SECRET` environment variable set.
+- After bootstrap, admin can create invites with `clawdentity invite create`.
+
+## API Key Lifecycle
+
+### Create API key
+
+```
+clawdentity api-key create
+```
+
+Creates a new API key under the current authenticated human. Token is displayed once.
+
+### List API keys
+
+```
+clawdentity api-key list
+```
+
+Lists all API keys for the current human with ID, name, and status.
+
+### Revoke API key
+
+```
+clawdentity api-key revoke <api-key-id>
+```
+
+Revokes an API key by ID. The key becomes immediately unusable.
+
+### Rotation workflow
+
+1. `clawdentity api-key create` — note the new token.
+2. `clawdentity config set apiKey <new-token>` — switch local config.
+3. `clawdentity api-key revoke <old-key-id>` — deactivate old key.
+4. `clawdentity config get apiKey` — verify new key is active.
+
+### Error Codes
+
+| HTTP Status | Meaning |
+|-------------|---------|
+| 401 | API key invalid or expired; re-authenticate |
+| 403 | Insufficient permissions (admin required for some operations) |
+
+## Agent Revocation
+
+### Command
+
+```
+clawdentity agent revoke <agent-name>
+```
+
+Revokes a local agent identity via the registry. The agent's AIT will appear on the certificate revocation list (CRL).
+
+### Behavioral Notes
+
+- Reads agent DID from `~/.clawdentity/agents/<agent-name>/identity.json`.
+- Requires `apiKey` configured in `~/.clawdentity/config.json`.
+- Idempotent: repeat revocation calls succeed without error.
+- CRL propagation lag: verifiers using cached `crl-claims.json` (15-minute TTL) may not see revocation immediately.
+- Local credential files are not deleted; only registry-side revocation is performed.
+
+### Error Codes
+
+| HTTP Status | Meaning |
+|-------------|---------|
+| 401 | Authentication failed — API key invalid |
+| 404 | Agent not found in registry |
+| 409 | Agent cannot be revoked (already revoked or conflict) |
+
+## Agent Auth Refresh
+
+### Command
+
+```
+clawdentity agent auth refresh <agent-name>
+```
+
+Refreshes the agent's registry auth credentials using Claw proof (Ed25519 signature).
+
+### What It Reads
+
+- `~/.clawdentity/agents/<agent-name>/secret.key` — for signing the proof
+- `~/.clawdentity/agents/<agent-name>/registry-auth.json` — current refresh token
+
+### What It Writes
+
+- `~/.clawdentity/agents/<agent-name>/registry-auth.json` — new access token and refresh token
+
+### Behavioral Notes
+
+- Uses atomic write (temp file + chmod 0600 + rename) to prevent corruption.
+- Requires `registryUrl` configured in `~/.clawdentity/config.json`.
+- After refresh, restart connector to pick up new credentials.
+- If `registry-auth.json` is missing or empty, the agent must be re-created with `agent create`.
+
+### Error Codes
+
+| Error Code | Meaning |
+|------------|---------|
+| `CLI_OPENCLAW_EMPTY_AGENT_CREDENTIALS` | Registry auth file is empty or missing |
+| 401 | Refresh token expired or invalid — re-create agent |
+
+## Invite Management (Admin)
+
+### Create invite
+
+```
+clawdentity invite create
+clawdentity invite create --expires-at <iso-8601> --registry-url <url>
+```
+
+Admin-only. Creates a registry invite code (`clw_inv_...`) for onboarding new users.
+
+### Error Codes
+
+| Error Code | Meaning |
+|------------|---------|
+| `CLI_INVITE_MISSING_LOCAL_CREDENTIALS` | API key not configured |
+| `CLI_INVITE_CREATE_FAILED` | Invite creation failed |
+| 401 | Authentication failed |
+| 403 | Requires admin access |
+| 400 | Invalid request |