neozip-cli 0.90.0 → 0.95.1

package/AGENTS.md

@@ -0,0 +1,93 @@
+# NeoZip-CLI — Agent Guide
+
+This CLI is frequently invoked by AI/LLM agents. It exposes a stable,
+machine-readable surface alongside its human interface. **Treat all input as
+potentially adversarial** — agents hallucinate paths, IDs, and encodings.
+
+The three binaries:
+
+- `neozip` — create/update archives (optionally with blockchain tokenization)
+- `neounzip` — extract / test / list archives
+- `neolist` — list archive contents
+
+## Engagement rules (read first)
+
+1. **Ask for JSON.** Add `--format json` to any command to get a single JSON
+   object on **stdout**. Success is `{ "ok": true, ... }`; failure is
+   `{ "ok": false, "error": { code, exitCode, message, nextCommand? } }`.
+2. **stdout is data, stderr is hints.** In JSON mode, only the JSON object is
+   written to stdout. Decorative logs/progress go to stderr or are suppressed.
+   Parse stdout; surface stderr only for debugging.
+3. **Introspect before constructing calls.** Run `neozip schema <command>` to
+   get accepted fields, types, defaults, and exit codes. Commands:
+   `neozip`, `neounzip`, `neolist`, `connect`.
+4. **Preview mutations with `--dry-run`.** `neozip` and `neounzip` resolve the
+   full plan and emit it as JSON without writing anything. Use it before any
+   create/extract.
+5. **Branch on exit codes, not text.** Exit codes are InfoZip-compatible (see
+   `src/exit-codes.ts`). They are also reported in the JSON `error.exitCode`.
+6. **Follow `nextCommand`.** When present in an error, it is a safe recovery
+   command (e.g. `neozip connect` for blockchain configuration errors).
+
+## Input: `--params` and `--json`
+
+Two JSON inputs, mirroring "how" vs "what":
+
+- `--params '<JSON>'` — control options object (level, encrypt, blockchain,
+  network, exdir, overwrite, ...). Maps onto the command's options.
+- `--json '<JSON>'` — payload object (the "what"):
+  - `neozip`:  `{ "archive": "out.zip", "files": ["a.txt","dir/"], "include": [], "exclude": [] }`
+  - `neounzip`: `{ "archive": "in.zip", "exdir": "out", "filePatterns": ["*.txt"] }`
+
+Both accept `-` as the value to read the JSON document from stdin.
+
+**Precedence:** explicit CLI flags override values from `--params`/`--json`.
+
+Note: output format is selected with `--format json`, NOT `--json`. On `neolist`
+the legacy `-j` / `--json` flag is an alias for `--format json` (it has no
+payload).
+
+## Examples
+
+```bash
+# Introspect
+neozip schema neozip
+
+# Create (agent-style, fully JSON-driven)
+neozip --format json \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+
+# Preview an extraction without writing
+neounzip --format json --dry-run --params '{"exdir":"out"}' in.zip
+
+# Extract
+neounzip --format json --params '{"exdir":"out","overwrite":true}' in.zip
+
+# List
+neolist --format json in.zip
+```
+
+## Safety rails (enforced by the CLI)
+
+- **Control characters / dangerous Unicode** in archive names and extraction
+  dirs are rejected (`src/cli/validate.ts`).
+- **Zip-slip protection:** `neounzip` refuses any entry whose resolved output
+  path escapes the target directory.
+- **`--dry-run`** never touches the filesystem.
+
+## InfoZip / PKZIP compatibility
+
+- Default compression is **zstd**, which stock InfoZip `unzip` cannot read.
+- Pass `--legacy` to `neozip` to produce a standard archive readable by stock
+  `unzip`: it forces deflate (or store at `-0`) + PKZIP encryption and disables
+  all NeoZip extensions (zstd, blockchain `-b`/`-bd`/`-bm`, `-ots`, `-ts`).
+- `--legacy` combined with blockchain features is a hard error (exit 10).
+
+## Where things live
+
+- Shared agent layer: `src/cli/` (`output.ts`, `params.ts`, `validate.ts`, `schema.ts`)
+- Exit codes: `src/exit-codes.ts`
+- Connection store / `neozip connect`: `src/connect/`, `src/connection/`
+- MCP server is **not** in this repo; it lives in `neozip-mcp` and shares the
+  same `~/.neozip/connection/` store.

package/CHANGELOG.md

@@ -7,10 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **Release notes** for each version are documented here (not in a separate “what’s new” file).
 
+## [Unreleased]
+
+## [0.95.1] - 2026-07-07
+
+### Documentation
+
+- **[README.md](README.md)** — v0.95.1 release: expanded AI agent integration guide (CLI + JSON, Skills, neozip-mcp), NeoZip Token Service (`connect refresh`, `connect fund`), advanced-feature matrix, and agent workflow documentation.
+
+## [0.95.0] - 2026-07-03
+
+### Added
+
+- **AI-agent support** — machine-readable mode across `neozip`, `neounzip`, and `neolist`:
+  - `--format json` emits a single structured JSON object on stdout (`{ "ok": true, ... }` / `{ "ok": false, "error": { code, exitCode, message, nextCommand? } }`); human hints stay on stderr.
+  - `--params '<JSON>'` (control options) and `--json '<JSON>'` (payload: archive + files/targets) input flags; both accept `-` to read from stdin. Explicit CLI flags override JSON input.
+  - `neozip schema <neozip|neounzip|neolist|connect>` introspection command emits accepted fields, types, defaults, and exit codes.
+  - `--dry-run` on `neozip`/`neounzip` resolves and prints the plan as JSON without writing.
+  - Structured JSON errors mapped from `src/exit-codes.ts`, with `nextCommand` recovery hints (InfoZip-compatible exit codes preserved).
+  - Input hardening: control-character/Unicode rejection on names and extraction dirs; zip-slip protection refuses entries that escape the extraction directory.
+  - Agent docs and skills: [AGENTS.md](AGENTS.md) and [skills/](skills/) (`neozip-shared`, `neozip-create`, `neozip-extract`, `neozip-list`, `neozip-legacy`, `neozip-connect`).
+- **`neozip skills`** — install bundled Agent Skills from the npm package: `path`, `list`, `install` (symlink into `~/.claude/skills` and/or `~/.cursor/skills`), and `pack` (ZIP per skill for Claude Cowork / claude.ai upload). Skills ship in the tarball under `skills/`.
+- **`neozip --legacy`** — produce an InfoZip/PKZIP-compatible archive (forces deflate/store + PKZIP encryption, disables zstd and all blockchain extensions) readable by stock `unzip`. Combining `--legacy` with blockchain features is a parameter error.
+- **`neozip connect refresh`** — renew an expired Token Service access token without disturbing the wallet/identity. Prefers a **silent wallet-signature login** (no email round-trip) when the Token Service supports it, and falls back to the email OTP flow otherwise. `connect status` now reports access-token expiry (`accessTokenExpired` / `accessTokenExpiresAt` in JSON; an "Access token" line in text).
+- **Automatic token renewal for `-ts`** — before a Token Service timestamp, an expired access token is silently renewed via wallet signature when possible, so timestamping "just works" without a manual refresh.
+- **`neozip connect fund`** — request native gas for the local Data Wallet from the Token Service funding API. Subactions: `request` (default; sends the policy-defined grant to your primary linked wallet), `status` (eligibility + recent grants), and `policy` (grant size/cooldown, no auth). Accepts `--network NAME` / `--chain ID` and `--json`; an expired access token is silently renewed via wallet signature first. The recipient is server-authoritative — the client cannot redirect funds. Wallet/insufficient-balance error messages across `-b`, `-ts`, `-ots`, and `--upgrade` now point to `neozip connect fund` (with the public faucet kept as a fallback).
+
+### Changed
+
+- **Token Service HTTP clients moved to `neozip-blockchain`** — the account-auth (email/code, magic link, silent wallet-login, phone OTP), funding, and wallet/identity-key HTTP clients now live in `neozip-blockchain/token-service` (v0.8.0) and are shared with NeoZip Desktop and MCP. The CLI keeps only the local orchestration that needs the wallet private key (`runWalletEnsureAndAttach` in `src/account/wallet-setup.ts`) and product-specific UX (token-expiry guidance in `src/connection/token-auth.ts`). No user-facing command behavior changes; the library emits generic auth errors and the CLI maps them to `neozip connect refresh` guidance.
+- **Production dependencies** — `neozipkit` and `neozip-blockchain` updated to `^0.8.0` (npm).
+- **Development workflow** — pnpm-only from source (`engines.pnpm` `>=10.0.0`); Yarn config removed. Use `pnpm install`, `pnpm build`, and `pnpm test`.
+
+### Fixed
+
+- **Blockchain tokenization (`-b`) blocked by an expired Token Service token** — `-b` and on-chain `mint` sign locally with the wallet key and never use the Token Service access token, but the readiness gate required a non-expired token for them. The gate now distinguishes on-chain abilities (wallet only) from Token Service abilities (`-ts`, which still require a current token), and expired-token errors now point to `neozip connect refresh`.
+- **`pack:dry-run` script** — use `npm pack --dry-run` (pnpm has no `--dry-run` flag).
+
+### Documentation
+
+- **[README.md](README.md)** — updated for v0.95: NeoZip Token Service (`connect refresh`, `connect fund`, silent wallet-login renewal), AI agent integration guide (CLI + JSON, bundled Skills via `neozip skills install`, neozip-mcp), advanced-feature matrix for agents (encryption, compression, blockchain, legacy mode), and agent workflow (schema → dry-run → execute → recover via `nextCommand`).
+- **[AGENTS.md](AGENTS.md)** — engagement rules for machine-readable I/O, schema introspection, dry-run, exit codes, and safety rails.
+- **[skills/](skills/)** — six bundled Agent Skills (`neozip-shared`, `neozip-create`, `neozip-extract`, `neozip-list`, `neozip-connect`, `neozip-legacy`) with per-command guidance for autonomous agents.
+
 ## [0.90.0] - 2026-03-18
 
 ### Added
 
+- **`neozip connect`** — Token Service account setup subcommand (status, register, verify, wallet, finish, migrate). Shares `~/.neozip/connection/` with NeoZip Desktop and MCP (`neozip-connect` from neozip-mcp).
+- **Connection store bootstrap** — non-blocking startup read of active connection; gated operations (`-ts`, mint) require connect readiness with actionable guidance.
+
+### Changed
+
+- **Unified wallet** — all blockchain operations (`-b`, `-ts`, mint) use the connection store wallet (`secrets.enc`); `wallet.json` retired. `neozip init` is an alias for `neozip connect`. On-chain prefs (`defaultNetwork`, RPC, gas) live on `public.json`.
+- **Token Service configuration** — URL, verified email, and access token are read **only** from the connection store (`~/.neozip/connection/`), not from `wallet.json`, env vars, or CLI flags.
+- **Package manager** — development workflow uses pnpm (`packageManager: pnpm@10.12.1`); use `pnpm install` and `pnpm build` from source.
+
+### Removed
+
+- **`~/.neozip/wallet.json`** — migrate via `neozip connect migrate`; archived as `wallet.json.migrated`.
+- **`NEOZIP_WALLET_PASSKEY`** as user-facing configuration (connection store only; `-w` remains for one-off overrides).
+
+- **`neozip verify-email`** command and `npm run verify-email` script — use `neozip connect` instead.
+- **`--timestamp-email`** flag and `wallet.json` `tokenService.timestampEmail` — configure via `neozip connect`.
+- **`TOKEN_SERVICE_URL`**, **`NEOZIP_TIMESTAMP_EMAIL`** runtime env vars for Token Service operations.
+
+### Added (encryption)
+
 - **Full AES-256 encryption support** — create, list, and extract password-protected archives with WinZip-compatible AES-256 (default) or legacy PKZIP encryption.
 
 #### Creating encrypted archives
@@ -62,6 +125,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 See [README.md](README.md) and [DOCUMENTATION.md](DOCUMENTATION.md) for more examples.
 
+### Changed
+
+- **Dependencies**: `neozipkit` and `neozip-blockchain` updated to **^0.7.2** (latest).
+- **Token service API**: imports migrated from `neozip-blockchain/zipstamp-server` to `neozip-blockchain/token-service`; `getZipStampServerUrl()` replaced by `getTokenServiceUrl()`. Configure the server with `TOKEN_SERVICE_URL` (see `env.example`).
+- **ZipStamp → Token Service rename**: all user-facing "Zipstamp" terminology replaced with "Token Service"; `wallet.json` key `zipstamp.timestampEmail` removed in favor of `tokenService.timestampEmail`; CLI flags `--zipstamp-auto-upgrade` / `--zipstamp-skip-upgrade` replaced with `--token-service-auto-upgrade` / `--token-service-skip-upgrade`.
+
 ---
 
 ## [0.80.0] - 2026-03-04
@@ -79,7 +148,7 @@ See [README.md](README.md) and [DOCUMENTATION.md](DOCUMENTATION.md) for more exa
 
 ### Fixed
 
-- `neozip config` / `neozip init` no longer fail with "Cannot find module './config/ConfigSetup.js'" when run via `yarn neozip-config` or ts-node
+- `neozip config` / `neozip init` no longer fail with "Cannot find module './config/ConfigSetup.js'" when run via `pnpm neozip-config` or ts-node
 
 ---
 

package/DOCUMENTATION.md

@@ -119,16 +119,16 @@ neolist --help     # Show listing help
   - Cryptographic proof of archive existence
   - Timestamp verification
 
-- **Zipstamp**
-  - Ethereum blockchain timestamping via Zipstamp server
+- **Token Service**
+  - Ethereum blockchain timestamping via NeoZip Token Service
+  - Account setup via `neozip connect` (shared store at `~/.neozip/connection/`)
   - Pending timestamps (TS-SUBMIT.NZIP) can be upgraded to confirmed (TIMESTAMP.NZIP)
   - Use `neozip upgrade <archive> [output] [--wait]` to upgrade pending timestamps
 
 - **Wallet Integration**
-  - Interactive wallet setup wizard (`neozip init`)
-  - Configuration management (`neozip config`)
-  - Environment variable support
-  - Secure wallet key storage
+  - Token Service account and wallet via `neozip connect` (alias: `neozip init`)
+  - Connection dashboard (`neozip config`) and `neozip connect settings` for on-chain prefs
+  - Wallet key in encrypted `secrets.enc` under `~/.neozip/connection/`
 
 ### Advanced Features
 
@@ -142,44 +142,36 @@ neolist --help     # Show listing help
 
 ## 🔧 Configuration
 
-### Wallet Setup
-
-For blockchain features, configure your wallet:
+### Account, wallet, and on-chain preferences
 
 ```bash
-# Interactive setup wizard
-neozip init
-
-# View or modify configuration
-neozip config
+neozip connect          # Setup (alias: neozip init)
+neozip connect status
+neozip connect settings # default network, RPC, gas
+neozip config           # dashboard
+neozip connect migrate  # legacy wallet.json → connection store
 
-# Upgrade pending Zipstamp timestamp to confirmed
+# Upgrade pending Token Service timestamp
 neozip upgrade archive.nzip [output.nzip] [--wait]
 ```
 
-Configuration is stored in `~/.neozip/wallet.json` and supports:
-- Wallet private key
-- Network selection (testnet/mainnet)
-- Custom RPC endpoints
-- Gas settings
-- Debug options
+Store: `~/.neozip/connection/` (see [dev_doc/CONNECTION_CLI_PREFS.md](dev_doc/CONNECTION_CLI_PREFS.md)).
 
-### Environment Variables
+### Environment Variables (optional session overrides)
 
-You can also configure via environment variables (see [env.example](env.example)):
-- `NEOZIP_WALLET_PASSKEY` - Wallet private key
-- `NEOZIP_NETWORK` - Blockchain network
-- `NEOZIP_BASE_SEPOLIA_RPC_URL` - Custom RPC endpoints
-- `NEOZIP_VERBOSE` - Enable verbose logging
-- `NEOZIP_DEBUG` - Enable debug mode
+See [env.example](env.example):
+- `NEOZIP_NETWORK` — override default network for this process
+- `NEOZIP_BASE_SEPOLIA_RPC_URL` — override RPC for this process
+- `NEOZIP_CONNECTION_DIR`, `NEOZIP_UNLOCK_PASSPHRASE` — connection store
+- `NEOZIP_VERBOSE`, `NEOZIP_DEBUG`, `NEOZIP_GAS_MULTIPLIER`, `NEOZIP_MAX_GAS_PRICE`
 
 ## 📚 Reading Order
 
 1. **Start with** [README.md](README.md) for installation and basic usage
 2. **Read** [WHY_NEOZIP.md](WHY_NEOZIP.md) to understand the project vision
 3. **Review** [CHANGELOG.md](CHANGELOG.md) for version history and known issues
-4. **Configure** wallet using `neozip init` for blockchain features
-5. **Reference** [env.example](env.example) for environment variable configuration
+4. **Configure** via `neozip connect` for blockchain features
+5. **Reference** [env.example](env.example) for optional environment overrides
 
 ## 🔗 Related Links
 

package/README.md

@@ -8,7 +8,7 @@
 
 ## Release Notice
 
-**Current version: v0.90.0.** This release adds full AES-256 encryption support. See [CHANGELOG.md](CHANGELOG.md) for details.
+**Current version: v0.95.1.** This release adds first-class **AI agent** support (JSON I/O, schema introspection, bundled Skills with `neozip skills install`), deep **NeoZip Token Service** integration (silent token refresh, wallet funding), and `--legacy` InfoZip compatibility. See [CHANGELOG.md](CHANGELOG.md) for details.
 
 - **API Stability**: Command-line interface is becoming more stable but may still change
 - **Testing**: Please test thoroughly and report any issues
@@ -18,8 +18,10 @@
 
 NeoZip CLI is a modern, full-featured ZIP utility that provides:
 
-- **Standard ZIP Compatibility**: ~99% compatible with InfoZip utilities
+- **Standard ZIP Compatibility**: ~99% compatible with InfoZip utilities (`--legacy` for stock `unzip`)
 - **Blockchain Integration**: Tokenize archives and verify integrity on-chain
+- **NeoZip Token Service**: Email-verified timestamps, wallet-linked identity, and testnet gas grants
+- **AI Agent Ready**: Machine-readable JSON I/O, schema introspection, dry-run, and bundled [Skills](skills/)
 - **Advanced Compression**: Zstd, Deflate, and Store compression methods
 - **Encryption Support**: AES-256 (default) and PKZIP encryption
 - **Cross-Platform**: Works on macOS, Linux, and Windows
@@ -48,10 +50,11 @@ NeoZip CLI is a modern, full-featured ZIP utility that provides:
 - Auto-detection of encryption method during extraction
 
 ### Blockchain Features
-- **Tokenization**: Create on-chain tokens for archives
-- **OpenTimestamp**: Bitcoin blockchain timestamping
-- **Zipstamp**: Ethereum blockchain timestamping (Zipstamp server)
-- **Integrity Verification**: Verify archive integrity on-chain
+- **Tokenization (`-b`)**: Create on-chain tokens for archives (signs locally with the Data Wallet)
+- **OpenTimestamp (`-ots`)**: Bitcoin blockchain timestamping
+- **Token Service (`-ts`)**: Ethereum timestamping via the NeoZip Token Service (requires a verified account)
+- **Integrity Verification**: Verify archive integrity on-chain during extract (`neounzip --pre-verify`)
+- **Wallet funding**: Request testnet gas grants via `neozip connect fund`
 - **Network Support**: Base Sepolia, Base Mainnet, Arbitrum, and more
 
 ### Advanced Features
@@ -69,7 +72,8 @@ NeoZip CLI is a modern, full-featured ZIP utility that provides:
 ### Prerequisites
 
 - Node.js 16.0.0 or higher
-- npm or yarn package manager
+- [pnpm](https://pnpm.io/) 10+ (required for development from source)
+- npm (optional — for global install of the published package only)
 
 ### Install from npm
 
@@ -164,11 +168,11 @@ neozip -b tokenized.nzip file.txt
 # Tokenize with OpenTimestamp proof (Bitcoin)
 neozip -ots timestamped.nzip file.txt
 
-# Create Zipstamp timestamp (Ethereum)
-neozip -ts zipstamp.nzip file.txt
+# Create Token Service timestamp (Ethereum)
+neozip -ts timestamped.nzip file.txt
 
-# Upgrade pending Zipstamp timestamp to confirmed
-neozip upgrade zipstamp.nzip [output.nzip] [--wait]
+# Upgrade pending Token Service timestamp to confirmed
+neozip upgrade timestamped.nzip [output.nzip] [--wait]
 
 # Extract and verify blockchain integrity
 neounzip tokenized.nzip tests/extracted/
@@ -196,17 +200,16 @@ neozip [options] <archive> [files...]
 - `--pkzip` - Use legacy PKZIP encryption (weak, for compatibility only)
 - `-b, --blockchain` - Enable blockchain tokenization
 - `-ots, --opentimestamp` - Enable OpenTimestamp proof (Bitcoin)
-- `-ts, --timestamp` - Enable Zipstamp timestamp (Ethereum)
-- `--timestamp-email <email>` - Email for Zipstamp server (some servers require verified email)
+- `-ts, --timestamp` - Enable Token Service timestamp (Ethereum; requires `neozip connect`)
 - `-T, --test-integrity` - Test archive after creation
 - `-v, --verbose` - Enable verbose output
 - `-q, --quiet` - Suppress output
 
 **Configuration Commands:**
 ```bash
-neozip init      # Interactive wallet setup wizard
-neozip config    # Show current configuration
-neozip upgrade <archive> [output] [--wait]  # Upgrade pending Zipstamp timestamp to confirmed
+neozip connect   # Token Service account + wallet setup (alias: neozip init)
+neozip config    # Connection dashboard (status, prefs, migrate)
+neozip upgrade <archive> [output] [--wait]  # Upgrade pending Token Service timestamp to confirmed
 ```
 
 **Examples:**
@@ -301,41 +304,58 @@ neolist -1 archive.nzip
 
 ## Configuration
 
-### Wallet Setup (for Blockchain Features)
+### Account and wallet setup
 
-To use blockchain features, you need to configure a wallet:
+All wallet identity and Token Service credentials live in the shared connection store (`~/.neozip/connection/`). Use the same profile as NeoZip Desktop and the [neozip-mcp](https://github.com/NeoWareInc/neozip-mcp) server.
 
 ```bash
-# Interactive setup wizard
-neozip init
+neozip connect          # Interactive setup (alias: neozip init)
+neozip connect status   # Show connection phase and credentials
+neozip connect settings # Default network, RPC overrides, gas prefs
+neozip connect migrate  # Import legacy wallet.json / MCP profiles
+neozip config           # Connection dashboard (status, prefs, migrate)
 ```
 
-This will guide you through:
-1. Creating or importing a wallet
-2. Selecting a blockchain network
-3. Saving configuration to `~/.neozip/wallet.json`
+On-chain preferences (`defaultNetwork`, custom RPC URLs, gas) are stored in each connection's `public.json`.
 
-### Environment Variables
+### NeoZip Token Service
 
-You can also configure via environment variables:
+The Token Service provides email-verified identity, Ethereum timestamps (`-ts`), and optional testnet gas grants. Configuration is read **only** from the connection store — not from env vars or CLI flags.
+
+**Setup (interactive or scripted):**
+
+```bash
+neozip connect register --email you@example.com --json
+neozip connect verify --email you@example.com --code 123456 --json
+neozip connect wallet create --ack-backup --json
+neozip connect finish --json
+```
+
+**Token refresh** — access tokens expire. Renewal prefers a **silent wallet-signature login** (no email round-trip); falls back to email OTP on older deployments:
 
 ```bash
-export NEOZIP_WALLET_PASSKEY="your-wallet-key"
-export NEOZIP_NETWORK="base-sepolia"  # or base-mainnet, arbitrum-sepolia, etc.
-export ZIPSTAMP_SERVER_URL="https://zipstamp-dev.neozip.io"  # Zipstamp server (optional)
-export NEOZIP_TIMESTAMP_EMAIL="your@email.com"  # Email for Zipstamp (some servers require verified email)
+neozip connect refresh --json                              # silent wallet login (preferred)
+neozip connect refresh --email you@example.com --json      # send OTP code
+neozip connect refresh --email you@example.com --code 123456 --json
 ```
 
-### Configuration File
+`-ts` auto-renews an expired token before failing, so timestamping usually needs no manual step. `-b` tokenization and `mint` sign on-chain with the local wallet key and do **not** require a current access token.
 
-Configuration is stored in `~/.neozip/wallet.json`:
+**Wallet funding** — on-chain operations need native gas. The Token Service can send a small fixed grant to your primary linked wallet (recipient is server-authoritative):
 
-```json
-{
-  "walletKey": "0x...",
-  "network": "base-sepolia",
-  "rpcUrl": "https://..."
-}
+```bash
+neozip connect fund policy --json    # grant size + cooldown (no auth)
+neozip connect fund status --json    # eligibility and recent grants
+neozip connect fund --json           # request a grant (default action)
+neozip connect fund --network base-sepolia --json
+```
+
+Optional overrides:
+
+```bash
+export NEOZIP_CONNECTION_DIR="/path/to/connection"  # Store path override
+export NEOZIP_UNLOCK_PASSPHRASE="..."               # Decrypt secrets.enc non-interactively
+export NEOZIP_NETWORK="base-sepolia"                # Override default network for this session
 ```
 
 ## Advanced Examples
@@ -398,14 +418,17 @@ neounzip -P "secure-password" secret.nzip decrypted/
 ### Blockchain Features
 
 ```bash
-# Tokenize archive
+# Tokenize archive (on-chain mint; needs gas — run neozip connect fund if low)
 neozip -b tokenized.nzip important-file.txt
 
-# Tokenize with OpenTimestamp
+# Token Service timestamp (needs verified account + current access token)
+neozip -ts timestamped.nzip document.pdf
+
+# OpenTimestamp (Bitcoin)
 neozip -ots timestamped.nzip document.pdf
 
-# Extract and verify
-neounzip tokenized.nzip verified/
+# Extract and verify on-chain integrity
+neounzip --pre-verify tokenized.nzip verified/
 ```
 
 ### Advanced Operations
@@ -427,6 +450,137 @@ neozip -X archive.nzip ./files/
 neozip -y archive.nzip ./symlinks/
 ```
 
+## For AI agents
+
+NeoZip is designed for autonomous AI/LLM agents. Every command exposes a stable,
+machine-readable surface alongside its human interface. Agents can integrate via
+three paths:
+
+| Path | When to use |
+|------|-------------|
+| **CLI + JSON** | Direct shell invocation from any agent runtime |
+| **Bundled Skills** | Cursor, Claude Code, or other skill-aware hosts — load from [skills/](skills/) |
+| **neozip-mcp** | MCP-native agents — same `~/.neozip/connection/` store, tool-based API |
+
+Start with [AGENTS.md](AGENTS.md) for engagement rules, then load the relevant
+skill for each task.
+
+### Agent workflow
+
+1. **Introspect** — `neozip schema <neozip|neounzip|neolist|connect>` returns accepted fields, types, defaults, and exit codes.
+2. **Preview** — add `--dry-run` to `neozip`/`neounzip` to resolve the full plan as JSON without writing.
+3. **Execute** — run with `--format json`; parse stdout only (stderr is hints).
+4. **Recover** — on failure, check `error.exitCode` and run `error.nextCommand` when present.
+
+```bash
+neozip schema neozip
+neozip --format json --dry-run \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+neozip --format json \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+```
+
+### Install Agent Skills
+
+Six bundled skills ship inside the npm package. Install them into Claude Code or
+Cursor after `npm install -g neozip-cli`:
+
+| Skill | Covers |
+|-------|--------|
+| [neozip-shared](skills/neozip-shared/SKILL.md) | JSON output, `--params`/`--json`, schema, dry-run, exit codes |
+| [neozip-create](skills/neozip-create/SKILL.md) | Archive creation: compression, encryption, blockchain flags |
+| [neozip-extract](skills/neozip-extract/SKILL.md) | Extract, test, verify; zip-slip protection; `--pre-verify` |
+| [neozip-list](skills/neozip-list/SKILL.md) | List archive contents as JSON |
+| [neozip-connect](skills/neozip-connect/SKILL.md) | Token Service setup, refresh, funding |
+| [neozip-legacy](skills/neozip-legacy/SKILL.md) | InfoZip/PKZIP-compatible archives (`--legacy`) |
+
+```bash
+# Symlink bundled skills into ~/.claude/skills and ~/.cursor/skills
+neozip skills install
+
+# Claude Code only
+neozip skills install --target claude
+
+# Show where skills live in your install
+neozip skills path
+neozip skills list
+
+# ZIP files for Claude Cowork / claude.ai upload (Customize > Skills)
+neozip skills pack --output-dir ./neozip-skills-zips
+```
+
+Alternative (skills registry):
+
+```bash
+npx skills add https://github.com/NeoWareInc/neozip-cli
+npx skills add https://github.com/NeoWareInc/neozip-cli/tree/main/skills/neozip-create
+```
+
+### JSON I/O conventions
+
+- **Output:** `--format json` writes a single object to stdout:
+  - Success: `{ "ok": true, ... }`
+  - Failure: `{ "ok": false, "error": { "code", "exitCode", "message", "nextCommand"? } }`
+- **Input:** `--params '<JSON>'` (control options) and `--json '<JSON>'` (payload: archive + files/targets). Either accepts `-` to read from stdin. Explicit CLI flags override JSON input.
+- **Exit codes:** InfoZip-compatible; echoed in `error.exitCode`. Branch on codes, not message text.
+
+### Advanced features for agents
+
+| Feature | Agent params / flags | Prerequisites |
+|---------|---------------------|---------------|
+| AES-256 encryption | `"encrypt": true`, `"password": "…"` | None |
+| PKZIP encryption | `"encryptionMethod": "pkzip"` | None |
+| Zstd compression (default) | `"compression": "zstd"`, `"level": 0–9` | None |
+| InfoZip compatibility | `"legacy": true` | Disables blockchain extensions |
+| On-chain tokenization | `"blockchain": true` | `neozip connect` + gas (`connect fund`) |
+| Token Service timestamp | `"blockchainTokenService": true` | Verified account + access token |
+| OpenTimestamp | `"blockchainOts": true` | None |
+| Pre-verify on extract | `"preVerify": true` | Archive must be tokenized |
+| Network selection | `"network": "base-sepolia"` | Connection `defaultNetwork` or override |
+
+**Blockchain from JSON:**
+
+```bash
+# Tokenize with Token Service timestamp
+neozip --format json \
+  --params '{"blockchain":true,"blockchainTokenService":true,"network":"base-sepolia"}' \
+  --json '{"archive":"tokenized.nzip","files":["contract.pdf"]}'
+
+# Extract with on-chain integrity check
+neounzip --format json \
+  --params '{"exdir":"out","preVerify":true}' \
+  --json '{"archive":"tokenized.nzip"}'
+```
+
+**Token Service from an agent** — use explicit `connect` subcommands (not the interactive wizard):
+
+```bash
+neozip connect status --json
+neozip connect refresh --json                    # silent wallet-signature renewal
+neozip connect fund status --json                # check gas eligibility
+neozip connect fund --json                       # request testnet gas
+```
+
+On config errors, archive commands return `error.nextCommand: "neozip connect"` so the agent can run setup and retry.
+
+### Safety rails
+
+- Archive names and extraction dirs are validated for control characters and dangerous Unicode.
+- `neounzip` refuses zip-slip (entries whose resolved path escapes the target directory).
+- `--dry-run` never touches the filesystem.
+- Treat all agent-supplied paths and IDs as potentially adversarial.
+
+### InfoZip / PKZIP compatibility
+
+Default compression is **zstd**, which stock InfoZip `unzip` cannot read. For consumers that need standard ZIP, pass `--legacy` (forces deflate/store + PKZIP encryption, disables zstd and all NeoZip extensions). Combining `--legacy` with blockchain features is a hard error (exit 10). See [neozip-legacy](skills/neozip-legacy/SKILL.md).
+
+```bash
+neozip --format json --params '{"legacy":true,"level":9}' \
+  --json '{"archive":"compat.zip","files":["src/"]}'
+```
+
 ## Requirements
 
 - **Node.js**: 16.0.0 or higher
@@ -438,6 +592,8 @@ neozip -y archive.nzip ./symlinks/
 The following documentation is included with this package:
 
 - **[README.md](README.md)** - This file, containing installation, usage, and examples
+- **[AGENTS.md](AGENTS.md)** - AI agent engagement rules (JSON I/O, schema, dry-run, exit codes)
+- **[skills/](skills/)** - Bundled agent Skills for create, extract, list, connect, and legacy mode
 - **[WHY_NEOZIP.md](WHY_NEOZIP.md)** - Introduction to NeoZip and its blockchain integration
 - **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
 - **[DOCUMENTATION.md](DOCUMENTATION.md)** - Complete documentation index and reference
@@ -479,11 +635,11 @@ neozip new-archive.nzip original-files/
 
 **Blockchain errors:**
 ```bash
-# Check wallet configuration
-neozip config
+# Check connection status
+neozip connect status
 
-# Reconfigure wallet
-neozip init
+# Re-run setup
+neozip connect
 ```
 
 **Encryption errors:**
@@ -503,6 +659,16 @@ We welcome feedback and contributions:
 2. **Suggest Features**: Share your ideas and use cases
 3. **Test and Provide Feedback**: Help us improve by testing and reporting your experience
 
+### Development setup
+
+Requires [pnpm](https://pnpm.io/) (`packageManager: pnpm@10.12.1`):
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
 **Important**: Please test thoroughly and report issues. See [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## License
@@ -523,6 +689,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Version**: 0.90.0
+**Version**: 0.95.1
 **Status**: Release (see [CHANGELOG.md](CHANGELOG.md) for latest changes)
-**Last Updated**: March 18, 2026
+**Last Updated**: July 7, 2026