@finchtech/cli 0.3.3 → 0.3.5

package/README.md

@@ -4,6 +4,8 @@ Install the public npm package with `npm install -g @finchtech/cli`, then run `f
 
 The Finch Agent CLI stores wallet keys, AgentCLI Session bearers, and MCP grant bearers only in an owner-only `FINCHTECH_HOME`, which defaults to `~/.finchtech`; secrets are never accepted as command arguments or emitted to stdout.
 
+For an existing private key, run `finch wallet use --file <PATH>` on a fresh installation, then `finch login --help` to choose an authentication chain. The file must contain a single 0x-prefixed 32-byte hex private key and have owner-only permissions. First import is offline and makes that wallet current. `finch wallet create` generates a new identity instead. An existing Account switch requires login and remote revocation before changing the current wallet. Incomplete wallet files require recovery from backup; residual local authorization requires restoring the original wallet or explicitly clearing local authorization with `finch logout --local`.
+
 `finch logout` revokes Account-bound remote authority before removing local Session and grant state. If invalid, corrupt, or legacy Session metadata prevents that flow, `finch logout --local` performs an explicit offline reset of only `session/` and `grants/`. It makes no network request and reports `remoteRevoked: false`; it remains available while an irreversible recovery is pending and preserves profiles, registered wallets, transaction journals, and recovery records so the user can log in again and run the recorded recovery command. Ordinary logout and wallet switching remain blocked until that recovery completes.
 
 CLI-authored EVM addresses accept canonical lowercase or valid EIP-55 input and are normalized to lowercase before request validation and transport. Invalid mixed-case and uppercase forms are rejected. Remote responses and Remote MCP plans remain strictly lowercase so normalization cannot change signed or hashed plan bytes.
@@ -22,11 +24,13 @@ The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `m
 
 `finch site open` creates a sixty-second one-use handoff from the active AgentCLI Session and opens the exact configured Finch origin in the local default Browser. `finch site login <REQUEST_URL>` binds a website-created five-minute request once, then opens the same confirmation page. Both commands require the wallet, CLI, and graphical Browser on the user's machine. A launch failure returns `BROWSER_OPEN_FAILED` without printing the secret completion URL. The Browser receives only a normal seven-day Finch Web Session; wallet signing, broadcast, and market confirmation remain local CLI actions.
 
-`finch mcp doctor` is read-only. It verifies that the active CLI authority, AgentCLI Session, local wallet, MCP challenge, OAuth metadata, and source-controlled persistent-Harness manifest agree. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI does not configure or launch Codex and never reads Harness OAuth material. During the Harness's native OAuth flow, the authorization page supplies an exact `finch mcp authorize <REQUEST_TOKEN>` command. The versioned base64url token carries the original OAuth request without shell metacharacters so Windows package-manager and Volta launchers cannot split it; the CLI decodes it before applying the existing origin, callback, state, and scope checks. That command uses only the active local AgentCLI Session and opens the verified callback without returning its one-use code. It never uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
+`finch mcp doctor` is read-only. It returns a `checks` object for endpoint, wallet, local Session, remote Session authority, and MCP discovery. Each check reports `ok`, `missing`, `invalid`, `unavailable`, or `skipped`, with guidance for unhealthy checks. Missing login or wallet state does not prevent independent discovery checks; an invalid endpoint prevents network checks. The command emits one JSON report with exit code 0 when ready, or 2 when any required check is unhealthy. It verifies that the active CLI authority, AgentCLI Session, local wallet, MCP challenge, OAuth metadata, and source-controlled persistent-Harness manifest agree. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI does not configure or launch Codex and never reads Harness OAuth material. During the Harness's native OAuth flow, the authorization page supplies an exact `finch mcp authorize <REQUEST_TOKEN>` command. The versioned base64url token carries the original OAuth request without shell metacharacters so Windows package-manager and Volta launchers cannot split it; the CLI decodes it before applying the existing origin, callback, state, and scope checks. That command uses only the active local AgentCLI Session and opens the verified callback without returning its one-use code. It never uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
 
 Doctor's `ready: true` is scoped by `readinessScope: "cli_session_and_mcp_discovery"`. Its `harnessOAuth.status` is always `not_checked`: CLI login and valid discovery metadata do not establish that the connected Harness has usable OAuth credentials, a saved issuer, or working refresh. The result includes identity-verification and native reauthorization guidance. If the Harness reports an OAuth failure, complete its native MCP authorization flow and the authorization page's fresh `finch mcp authorize` command, then verify MCP identity again.
 
-Ordinary installs require no profile file or environment selection. Network commands default to the PROD endpoint at `https://www.finchtech.ai`. An internal TEST installation may provide one strict owner-only `{ "version": 1, "origin": "..." }` profile override; it cannot configure an environment, chain, contract, or RPC. `finch login --chain-id <CHAIN_ID>` explicitly selects only the authentication chain, which the selected server must support. Market transaction chains come from Remote MCP/API plans and are independent of the login chain. `intent approve` signs only the shared publication-v2 or Local-purchase-v1 EIP-712 authorization; it cannot sign arbitrary transaction calldata.
+Run `finch login --help` to list supported production authentication chain IDs (1, 10, 56, 8453, 42161). For example, `finch login --chain-id 56` selects BNB Smart Chain for authentication only.
+
+Ordinary installs require no profile file or environment selection. Network commands default to the PROD endpoint at `https://www.finchtech.ai`. `finch login --chain-id <CHAIN_ID>` explicitly selects only the authentication chain, which the selected server must support. Market transaction chains come from Remote MCP/API plans and are independent of the login chain. `intent approve` signs only the shared publication-v2 or Local-purchase-v1 EIP-712 authorization; it cannot sign arbitrary transaction calldata.
 
 `operation show` and signing-decision recovery require an active, unexpired MCP grant for the current account and endpoint with `agent_market:operations:read`. The CLI selects that grant from protected local state and never substitutes the AgentCLI Session bearer.
 
@@ -51,7 +55,7 @@ Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` un
 Older clients receive an upgrade message from the Skill search API.
 
 Version 0.3.0 upgrades Skill publication and encrypted delivery together. Upgrade with
-`pnpm add -g @finchtech/cli@0.3.3` and verify `finch --version` before publishing new Skills
+`pnpm add -g @finchtech/cli@0.3.5` and verify `finch --version` before publishing new Skills
 or downloading encrypted Skills from the upgraded gateway. Older CLI versions cannot use
 the new encrypted delivery, including for historical Skills; 0.3.0 retains historical package support.
 
@@ -110,3 +114,11 @@ still exists. If source is unavailable or its excluded-path inventory changed ac
 the fingerprint-only recovery command can use the already stored publication bytes.
 
 These fixes require CLI 0.3.3 or newer; npm 0.3.2 does not include them. Updating a Skill does not upgrade the installed CLI. Journal v6 saves a pending stage before signing/submitting. Missing hashes in a pending stage or a legacy v4/v5 journal block automatic resubmission; contact support. Known hashes are verified without rebroadcast. The pending marker also blocks destructive local authorization/wallet cleanup through the recovery inventory.
+
+## Bootstrap and health reports (CLI 0.3.4+)
+
+First-wallet offline import, installed Account-switch revocation, partial doctor checks and exit code 2, contextual wallet recovery guidance, login authentication-chain help, and strict OAuth UUID response validation require CLI 0.3.4 or newer. Updating the website or Skill does not upgrade an installed CLI.
+
+## WebP image detection (CLI 0.3.5+)
+
+CLI 0.3.5 fixes valid WebP covers and packaged detail images being rejected when binary file-size bytes were decoded as UTF-8. Upgrade the installed CLI to receive the local detection fix; website or Skill updates alone do not update the executable. Image types, size limits, and publication recovery rules are unchanged.