zk-agent-cli 0.1.0-beta.8 → 0.1.0-rc.0

package/README.md

@@ -3,6 +3,10 @@
 `zk-agent-cli` is the packaged `zk-agent-cli` command surface for zkSync Era
 and zkSync Sepolia.
 
+This README is the canonical operator manual for the packaged CLI. If you want
+repo architecture, contributor state, or project planning context, use the root
+repository docs instead of this package manual.
+
 Current strengths:
 
 - local-first wallet/session storage
@@ -23,8 +27,9 @@ npx skills add https://github.com/AgiWeb3/zk-agent-cli
 ```
 
 This repo currently ships a repository skill bundle for compatible harnesses.
-It does not yet ship a native ChatGPT/Codex plugin bundle such as
-`.codex-plugin/plugin.json`.
+The repository root now also ships a native ChatGPT/Codex plugin manifest at
+`.codex-plugin/plugin.json`, but that plugin source belongs to the repository
+surface rather than this published npm tarball.
 
 For direct terminal use, install the packaged CLI:
 
@@ -80,6 +85,13 @@ Use:
 
 ## Shortest Path
 
+Current validated first-run baseline:
+
+- `setup` defaults to `zksync-sepolia`
+- the local approval path expects the connector UI at `http://localhost:4444`
+- override `--default-chain` or `--connector-url` only when you intentionally
+  target another chain or connector deployment
+
 Fresh setup:
 
 ```bash
@@ -99,6 +111,11 @@ zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
 zk-agent next
 ```
 
+If local setup or wallet readiness is unclear, start with `zk-agent doctor`.
+It inspects saved config, wallet approval metadata, and local signer state
+without live RPC reads, and `--relay-url` only makes the remote fallback
+commands concrete.
+
 If a wallet already exists, inspect the blocker first. Use `wallet reapprove`
 when approval is missing or expired, then return to `zk-agent next`. Use
 `wallet signer attach` when approval is still present but the local execution
@@ -228,7 +245,9 @@ published package now also ships the bundled connector UI build used by
 source checkout just to serve the UI. `relay inspect` now also reports
 `stateBackend`, `deploymentScope`, and `sameHostRestartPersists` so the
 single-host local-filesystem constraint is explicit before you rely on a hosted
-URL.
+URL. For the current supported hosted operating contract and the remaining
+`beta -> rc` blocker on this path, see
+[`docs/16-hosted-approval-operated-baseline.md`](../../docs/16-hosted-approval-operated-baseline.md).
 
 ## Local Storage
 
@@ -278,6 +297,7 @@ Connector callback never arrives:
 
 CLI says the wallet is missing a writable session:
 
+- if the blocker is unclear, run `zk-agent doctor --wallet <wallet>` first
 - inspect `zk-agent wallet status --name <wallet>`
 - if approval is missing, run `zk-agent wallet reapprove --name <wallet> --await-local`
 - if approval is present but the local signer is missing, run
@@ -300,6 +320,7 @@ For the canonical command surfaces:
 
 ```bash
 zk-agent --help
+zk-agent doctor --help
 zk-agent wallet --help
 zk-agent workflow --help
 ```