@thirdfy/agent-cli 0.2.28 → 0.2.29

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.29] - 2026-07-18
+
+### Changed
+
+- Docs: Wave C / W6 CLI reference polish. Quick start is Path A (`personal` + `agent_wallet`); Gator lives under **User wallet authorization**; cross-links to [action inventory](./docs/action-inventory-and-compatibility.md#execution-orchestration-reference-hosted-solo-agents) and the API [CLI reference standard](https://github.com/thirdfy/thirdfy-api-v2/blob/develop/docs-dev/agents/execution-orchestration-scale/cli-reference-standard.md). Solo path does not require MetaMask delegation. Pairs with Thirdfy API **v3.12.0**.
+
 ## [0.2.28] - 2026-07-11
 
 ### Fixed

package/README.md

@@ -40,26 +40,46 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.28
+## What's new in v0.2.29
 
-- `e2e:base:simulate` Robinhood tier passes chain 4663 compatibility by using `--run-mode agent_wallet`.
+- Path A quick start and docs: hosted solo agents use `personal` + `agent_wallet`; MetaMask Gator is under User wallet authorization only.
+- Cross-links to action inventory and the API CLI reference standard (pairs with Thirdfy API v3.12.0).
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 
 ## Quick start
 
+Hosted solo agents use profile `personal` and `--run-mode agent_wallet` (Path A). Fund the managed **execution wallet**, complete venue trading setup from the catalog when needed, then preflight and run. MetaMask Gator / `delegation *` is not required on this path.
+
 ```bash
 export AGENT_API_KEY="..."
 export THIRDFY_AUTH_TOKEN="..."
 export THIRDFY_OWNER_SESSION_TOKEN="..."
 
-thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
 thirdfy-agent profile init --profile personal --json
-thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --estimated-amount-usd 25 --json
-thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --estimated-amount-usd 25 --json
-thirdfy-agent intent-status --intent-id "<intentId>" --json
+thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
+thirdfy-agent wallet list --json
+# Fund the printed execution wallet address for your target chain (not the owner login wallet).
+
+thirdfy-agent preflight \
+  --agent-api-key "$AGENT_API_KEY" \
+  --run-mode agent_wallet \
+  --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' \
+  --estimated-amount-usd 25 \
+  --json
+
+thirdfy-agent run \
+  --agent-api-key "$AGENT_API_KEY" \
+  --run-mode agent_wallet \
+  --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' \
+  --estimated-amount-usd 25 \
+  --json
 ```
 
+`personal` defaults to `agent_wallet` when `--run-mode` is omitted. Use `intent-status` only for publisher execute-intent fanout (`--run-mode thirdfy`), not for solo `agent_wallet` writes. Full golden paths: [action inventory — execution orchestration](./docs/action-inventory-and-compatibility.md#execution-orchestration-reference-hosted-solo-agents).
+
 By default, the CLI targets production (`https://api.thirdfy.com`). Use `--api-base` (or `THIRDFY_API_BASE`) only for staging/dev/custom deployments.
 
 ### Local API smoke
@@ -308,9 +328,9 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 - Managed signer execution: `wallet execute`, `wallet sign`, `wallet submit`, `agent run`
 - Profiles: `profile init`, `profile use`, `profile show`, `whoami`
 - Onboarding: `login email`, `help onboarding`, `doctor auth`, `wallet list`, `bootstrap begin`, `bootstrap complete`, `onboarding begin`, `onboarding complete`, `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`, `developer bootstrap`
-- Governance readiness: `delegation create`, `delegation activate`, `delegation status`, `credentials upsert`, `credentials status`
-- Delegation operations: `delegation show`, `delegation inspect`, `delegation revoke`
-- Delegation execution helpers: `delegation balance`, `delegation redeem`
+- User wallet authorization (Gator): `delegation create`, `delegation activate`, `delegation status`, `credentials upsert`, `credentials status`
+- Gator operations: `delegation show`, `delegation inspect`, `delegation revoke`
+- Gator execution helpers: `delegation balance`, `delegation redeem` (daily-cap caveats via `--max-usd-per-day`)
 - Account: `credits balance`
 - Console Brain: `brain sections`, `brain suggest`, `brain preflight`, `brain graduate` (read/preflight-first; see [`docs/command-reference.md`](./docs/command-reference.md))
 
@@ -326,9 +346,11 @@ Maintainers validating releases locally: `npm run validate:release-preflight`. A
 - Live action inventory in your environment: [`docs/action-inventory-and-compatibility.md`](./docs/action-inventory-and-compatibility.md)
 - Provider runbooks and provider status: [`docs/providers/index.md`](./docs/providers/index.md)
 
-## Delegation lifecycle (canonical)
+## User wallet authorization (Gator)
 
-Use `create` + `activate` as the default delegated execution lifecycle:
+Gator / ERC-7710 lives under the `delegation *` command group. Use it when a **user wallet** authorizes spend for `hybrid` or `thirdfy` (subscriber / Console / external-wallet lanes). Hosted solo agents on `personal` + `agent_wallet` skip this section.
+
+Use `create` + `activate` as the default user-authority lifecycle (`--max-usd-per-day` sets the period transfer caveat):
 
 ```bash
 thirdfy-agent delegation create \
@@ -384,7 +406,9 @@ thirdfy-agent delegation redeem \
 
 `--auth-token "$THIRDFY_AUTH_TOKEN"` remains supported for all delegation commands, but owner-session token is preferred for least-privilege owner operations.
 
-### MetaMask custodial-compatible lifecycle (new)
+### MetaMask custodial-compatible grant (Gator path only)
+
+This is still user-authority setup, not the solo `agent_wallet` demo path. Solo agents do not need MetaMask delegation.
 
 ```bash
 thirdfy-agent delegation init-custodial \
@@ -402,7 +426,7 @@ thirdfy-agent delegation custodial-grant \
 
 The CLI keeps compatibility with legacy `delegation create` + `delegation activate` during migration.
 
-`delegation show` is a direct alias to `delegation status` for gator-style operator ergonomics.
+`delegation show` is a direct alias to `delegation status` for Gator operator ergonomics.
 
 Managed easy-wallet command group:
 
@@ -431,6 +455,7 @@ Managed-self execution performs strict wallet preflight and returns deterministi
 
 ## More docs
 
+- Execution orchestration (solo `agent_wallet` reference path): [action inventory — execution orchestration](./docs/action-inventory-and-compatibility.md#execution-orchestration-reference-hosted-solo-agents); operator standard in [thirdfy-api-v2 cli-reference-standard](https://github.com/thirdfy/thirdfy-api-v2/blob/develop/docs-dev/agents/execution-orchestration-scale/cli-reference-standard.md)
 - OpenClaw CLI onboarding flow:
   [docs.thirdfy.com/documentation/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli](https://docs.thirdfy.com/documentation/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli)
 - Creator platform (agent registration and keys):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {