FIL-Builders · nijoe1 · Jul 23, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to **foc-cli** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0, minor versions may contain breaking changes; they are always called out explicitly.
+
+## [Unreleased]
+
+Agent-hardening release ([#30]), driven by a 609-invocation live smoke campaign on Calibration and a keystore field test. Contains one breaking change, so the next release should be **0.2.0**.
+
+### Added
+
+- `download <pieceCid>` — retrieval as verification: the SDK validates received bytes against the piece CID, so a successful download is itself the proof of storage. Distinct error codes separate what retrying can fix (`DOWNLOAD_FAILED`) from what it cannot (`INTEGRITY_MISMATCH`, `PROVIDER_NOT_FOUND`, `WRITE_FAILED`). ([#7])
+- `docs --deep` — searches the full ~1,800-page site sitemap (SDK API reference, changelogs), automatically invoked when the curated index has no matches. ([#25])
+- MCP tool annotations on every command — human titles, `readOnlyHint` on reads, `destructiveHint` on `wallet init` / `dataset terminate` / `piece remove` — plus descriptions that state consequences (uploads commit USDFC onchain, terminate is irreversible). ([#28])
+- Fetch-all CTAs on paginated lists (`piece list`, `dataset details`) alongside next-page.
+- `ADDRESS_NOT_ON_CHAIN` — `wallet balance` on a brand-new address now explains the address has no onchain history and suggests `wallet fund`, instead of dumping raw RPC internals. ([#27])
+- Skill references: [keystore setup](skills/foc-cli/references/keystore-setup.md) (with creation recipe), [mainnet funding](skills/foc-cli/references/mainnet-funding.md), and a [troubleshooting catalog](skills/foc-cli/references/troubleshooting.md) of every error code with retry semantics. ([#2], [#4])
+- Skills-consistency test: skill frontmatter version/license and every `foc-cli@x.y.z` doc pin are CI-pinned to `cli/package.json`.
+
+### Changed
+
+- Uploads stream to providers (`upload`, `multi-upload`) — peak memory stays flat at any file size; only `stat` sizes are read up front. ([#24])
+- `wallet costs` prices each existing dataset individually (one storage context per dataset) and no longer depends on endorsed-provider selection. ([#26])
+- `--schema` now tells the truth: declared output schemas include the `processLog` step trail and `cta` block that real agent-mode responses carry. ([#28])
+- Both agent skills open with a self-discovery rule (run `<cmd> -h` and `<cmd> --schema --format json` before first use) and document flag syntax truthfully: camelCase and kebab-case spellings both parse, and boolean flags are presence-only switches (`--flag=false` is the explicit form). ([#1], [#3], [#5])
+- Keystore mode documented as interactive-CLI-only: the password prompt reads the terminal at use time, so MCP and CI must use a private-key wallet.
+- README rewritten against the verified current surface — one-table command map, quick start ending in a download round-trip. ([#29])
+- Dependencies: `@filoz/synapse-sdk` 1.1.0, `incur` 0.4.19 (fixes the doubled group prefix in `--llms` output). ([#23])
+
+### Fixed
+
+- `wallet costs` failed with `No endorsed provider available` and undercounted datasets sharing a provider (live check: 0.1058 → correct 0.1322 USDFC/month for 1 GiB). ([#26])
+- `wallet init --keystore` accepted a directory or arbitrary JSON and reported success; it now validates the path is an encrypted keystore file (`KEYSTORE_INVALID`). ([#27])
+- Keystore failures decode themselves: missing `cast` (install Foundry), `Mac Mismatch` (wrong password), no terminal (keystore mode cannot run under MCP/CI). ([#27])
+- `docs` auto-fetch could return raw HTML for pages without a markdown mirror; both fetch paths now share the HTML backstop.
+- Interactive spinner no longer blanks step labels or leaks orphan glyphs when info/success messages interleave with steps.
+
+### Removed
+
+- **Breaking:** `dataset upload` — `upload` already creates a dataset automatically; the low-level duplicate had a worse interface. Use `foc-cli upload <path>` (auto provider/dataset) or `dataset create` + `upload` for explicit control. ([#24])
+
+### Security
+
+- `docs --url` is restricted to `docs.filecoin.cloud` (full URL or bare docs path), rejects traversal, and refuses redirects so the host allowlist holds end-to-end. ([#25])
+- Keystore decryption invokes `cast` with an argument array — the keystore path is never interpolated into a shell command. ([#27])
+
+## [0.1.1] — 2026-06-16
+
+Synapse SDK v1 migration plus a CLI-hardening pass ([#17], [#19], [#20], [#21], [#22]).
+
+### Added
+
+- Provider health checks before upload context selection — unreachable providers are skipped instead of failing the upload.
+- Piece pagination with next-page CTAs on `piece list` and `dataset details`.
+- `wallet init --source <name>` — attribution tag reported to Synapse/Warm Storage.
+
+### Changed
+
+- Migrated all commands to Synapse SDK v1 APIs.
+- Centralized Synapse client construction (`synapseClient`).
+- `incur` 0.4.8; Node.js >= 22 required; dropped `@remix-run/fs`.
+- CLI version is read from `package.json` (was hardcoded).
+
+### Fixed
+
+- Failure envelopes render the real error code and message (previously `code: null, message: null`).
+- `wallet costs` no longer reports a duplicate monthly rate and surfaces whether a one-time operator approval is still needed.
+
+## [0.1.0] — 2026-05-13
+
+### Added
+
+- CI workflow (test + lint on every push).
+- Test coverage for the Synapse-backed commands.
+
+### Changed
+
+- Upgraded Synapse SDK and synapse-core.
+- `dataset create` requires a `providerId` (schema-enforced).
+
+## [0.0.4] — 2026-03-19
+
+Initial public release.
+
+### Added
+
+- CLI refactored out of the original `foc-skill`: upload, wallet, dataset, piece, provider, and docs commands for Filecoin Onchain Cloud.
+- MCP server mode and the two agent skills (`foc-cli`, `foc-docs`).
+- MCP client compatibility fixes.
+
+[Unreleased]: https://github.com/FIL-Builders/foc-cli/compare/main...agent-hardening
+[0.1.1]: https://www.npmjs.com/package/foc-cli/v/0.1.1
+[0.1.0]: https://www.npmjs.com/package/foc-cli/v/0.1.0
+[0.0.4]: https://www.npmjs.com/package/foc-cli/v/0.0.4
+[#1]: https://github.com/FIL-Builders/foc-cli/issues/1
+[#2]: https://github.com/FIL-Builders/foc-cli/issues/2
+[#3]: https://github.com/FIL-Builders/foc-cli/issues/3
+[#4]: https://github.com/FIL-Builders/foc-cli/issues/4
+[#5]: https://github.com/FIL-Builders/foc-cli/issues/5
+[#7]: https://github.com/FIL-Builders/foc-cli/issues/7
+[#17]: https://github.com/FIL-Builders/foc-cli/pull/17
+[#19]: https://github.com/FIL-Builders/foc-cli/pull/19
+[#20]: https://github.com/FIL-Builders/foc-cli/pull/20
+[#21]: https://github.com/FIL-Builders/foc-cli/pull/21
+[#22]: https://github.com/FIL-Builders/foc-cli/pull/22
+[#23]: https://github.com/FIL-Builders/foc-cli/issues/23
+[#24]: https://github.com/FIL-Builders/foc-cli/issues/24
+[#25]: https://github.com/FIL-Builders/foc-cli/issues/25
+[#26]: https://github.com/FIL-Builders/foc-cli/issues/26
+[#27]: https://github.com/FIL-Builders/foc-cli/issues/27
+[#28]: https://github.com/FIL-Builders/foc-cli/issues/28
+[#29]: https://github.com/FIL-Builders/foc-cli/issues/29
+[#30]: https://github.com/FIL-Builders/foc-cli/pull/30
diff --git a/README.md b/README.md
@@ -1,172 +1,101 @@
+<h1 align="center">foc-cli</h1>
+
 <p align="center">
-  <strong>foc-cli</strong>
-  <br/>
   Store files on Filecoin. From your terminal. Or your AI agent.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/foc-cli"><img src="https://img.shields.io/npm/v/foc-cli?color=0090ff&label=npm" alt="npm version"/></a>
+  <a href="https://www.npmjs.com/package/foc-cli"><img src="https://img.shields.io/node/v/foc-cli?color=339933&label=node" alt="node version"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue" alt="license"/></a>
+</p>
+
 <p align="center">
   <a href="https://docs.filecoin.cloud">Docs</a> &nbsp;&bull;&nbsp;
   <a href="https://skills.sh">Skills.sh</a> &nbsp;&bull;&nbsp;
+  <a href="https://clawhub.ai">ClawHub</a> &nbsp;&bull;&nbsp;
   <a href="https://github.com/FIL-Builders/foc-cli">GitHub</a>
 </p>
 
 ---
 
-**foc-cli** is a CLI and AI agent skill for [Filecoin Onchain Cloud](https://docs.filecoin.cloud) (FOC) — decentralized warm storage with cryptographic proof your data is held, paid with USDFC stablecoin on Filecoin.
-
-**Why FOC?** Traditional cloud storage requires trusting a provider. FOC gives you onchain verification (PDP proofs), programmable payments, and redundant copies across independent storage providers — all through a simple CLI or AI agent skill.
-
-## Install
-
-**As a CLI:**
-
-```bash
-npm install -g foc-cli
-```
-
-**As an AI Agent Skill** via [skills.sh](https://skills.sh) — works with Claude Code, Cursor, Copilot, Codex, Windsurf, and 20+ AI tools:
-
-```bash
-# Install all skills (CLI + docs)
-npx skills add FIL-Builders/foc-cli
-
-# Or install individually
-npx skills add FIL-Builders/foc-cli --skill foc-cli  # CLI & operations
-npx skills add FIL-Builders/foc-cli --skill foc-docs   # Documentation search
-```
-
-**As an MCP server** for direct tool access:
-
-```bash
-npx foc-cli mcp add                       # Auto-detect your agent
-npx foc-cli mcp add --agent claude-code   # Specific agent
-```
+**foc-cli** is a command-line interface and AI agent skill for [Filecoin Onchain Cloud](https://docs.filecoin.cloud) (FOC) — decentralized warm storage on Filecoin with cryptographic proof your data is held (PDP), paid in USDFC stablecoin. Upload, download (with built-in cryptographic verification), and pay for storage from a terminal, a script, or an agent via MCP.
 
 ## Quick Start
 
 ```bash
 npx foc-cli wallet init --auto        # 1. Create a wallet
 npx foc-cli wallet fund               # 2. Get testnet tokens
-npx foc-cli wallet deposit 1          # 3. Deposit 1 USDFC for storage
-npx foc-cli upload ./myfile.pdf       # 4. Upload a file
+npx foc-cli wallet costs --extraBytes 1000000 --extraRunway 1   # 3. Estimate cost
+npx foc-cli wallet deposit 1          # 4. Deposit 1 USDFC for storage
+npx foc-cli upload ./myfile.pdf       # 5. Upload a file
+npx foc-cli download <pieceCid>       # 6. Prove it's retrievable (pieceCid from upload output)
 ```
 
-That's it. Your file is now stored on Filecoin with PDP verification and redundant copies.
-
-## Skills
-
-This package ships two focused skills for AI agents:
-
-| Skill | Purpose | When to use |
-|-------|---------|-------------|
-| **foc-cli** | CLI & Operations | Setup, upload, wallets, datasets, pieces, providers — everything operational. |
-| **foc-docs** | Documentation | Search guides, SDK refs, concept explainers. |
-
-## Commands
-
-Every command supports `-h` for full usage details.
+A successful `download` is cryptographic proof your file is stored and intact — the SDK validates the bytes against the piece CID.
 
-### Upload
+## Install
 
 ```bash
-npx foc-cli upload <path>                        # Upload with auto provider/dataset
-npx foc-cli upload <path> --withCDN --copies 3   # CDN + 3 redundant copies
-npx foc-cli multi-upload ./a.pdf,./b.pdf         # Batch upload; all paths must be readable
+npm install -g foc-cli                    # CLI
+npx skills add FIL-Builders/foc-cli       # Agent skills via skills.sh (Claude Code, Cursor, Copilot, 20+ tools)
+clawhub install foc-cli && clawhub install foc-docs   # Agent skills via ClawHub (OpenClaw)
+npx foc-cli mcp add                       # MCP server (auto-detects your agent)
 ```
 
-### Wallet
+## Commands
 
-```bash
-npx foc-cli wallet init [--auto|--keystore <path>|--privateKey <key>]
-npx foc-cli wallet balance             # Check FIL & USDFC balances
-npx foc-cli wallet fund                # Testnet faucet
-npx foc-cli wallet deposit <amount>    # Deposit USDFC for storage
-npx foc-cli wallet withdraw <amount>   # Withdraw USDFC
-npx foc-cli wallet summary             # Funding timeline & rates
-npx foc-cli wallet costs --extraBytes <n> --extraRunway <months>
-```
+Every command supports `-h` for usage and `--schema --format json` for its JSON Schema. Flags are camelCase as documented (`--withCDN`); help shows kebab-case equivalents — both work. Boolean flags are presence-only switches (use `--flag=false` for an explicit value).
 
-### Datasets
+| Group | Commands | Notes |
+|-------|----------|-------|
+| Upload | `upload <path>` · `multi-upload <a,b>` | Auto provider/dataset. `--copies N`, `--withCDN` |
+| Download | `download <pieceCid> [--out <path>]` | Bytes validated against the CID — retrieval is the verification |
+| Wallet | `wallet init` · `balance` · `fund` · `deposit` · `withdraw` · `summary` · `costs` | `fund` = testnet faucet. `costs` = live pricing (source of truth) |
+| Datasets | `dataset list` · `details` · `create` · `terminate` | `details` paginates pieces with next-page + fetch-all CTAs |
+| Pieces | `piece list <id>` · `piece remove <id> <pieceId>` | Paginated with next-page + fetch-all CTAs |
+| Providers | `provider list` | Approved PDP providers with location, pricing, performance |
+| Docs | `docs --prompt "upload"` · `docs --url developer-guides/synapse.md` | Searches/fetches `docs.filecoin.cloud` only |
 
-```bash
-npx foc-cli dataset list                          # List all datasets
-npx foc-cli dataset details -d <id>               # Metadata + pieces
-npx foc-cli dataset create <providerId> [--cdn]   # Create dataset
-npx foc-cli dataset upload <path> <providerId>    # Create + upload
-npx foc-cli dataset terminate <dataSetId>         # Terminate dataset
-```
+**Global options:** `--chain <id>` (`314159` testnet default, `314` mainnet) · `--format toon|json|yaml|md` · `--json` · `--debug`
 
-### Pieces & Providers
+## Wallet & Keys
 
-```bash
-npx foc-cli piece list <dataSetId>                # List pieces in dataset
-npx foc-cli piece remove <dataSetId> <pieceId>    # Remove piece
-npx foc-cli provider list                         # Approved PDP providers
-```
+`wallet init --auto` for quick start, testnet, and automation. Use an encrypted [Foundry keystore](skills/foc-cli/references/keystore-setup.md) (`--keystore <path>`) when the wallet will hold real funds. A `--privateKey` flag exists for non-interactive setups — avoid it: raw keys in arguments leak into shell history and logs. Keep a dedicated wallet holding only what foc-cli needs.
 
-### Docs
+## Chains & Funding
 
-```bash
-npx foc-cli docs                                  # Browse docs index
-npx foc-cli docs --prompt "upload files"          # Search by topic
-npx foc-cli docs --url <url>                      # Fetch specific page
-```
+All commands default to **Calibration testnet**; add `--chain 314` for mainnet. Testnet tokens are one command (`wallet fund`). Mainnet needs real FIL for gas and USDFC for storage — see the [funding guide](skills/foc-cli/references/mainnet-funding.md).
 
-### Global Options
+**Pricing:** billed per copy per month by size (default 2 copies) plus a flat per-data-set monthly fee. `wallet costs` is the source of truth.
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--chain <id>` / `-c` | `314159` | Chain ID (`314159` = testnet, `314` = mainnet) |
-| `--debug` | `false` | Verbose error logging |
-| `--format <fmt>` | `toon` | Output format: `toon`, `json`, `yaml`, `md` |
-| `--json` | | Shorthand for `--format json` |
+## Agent Skills
 
-### Source tag
+| Skill | Purpose |
+|-------|---------|
+| [**foc-cli**](skills/foc-cli/SKILL.md) | Operations — setup, upload, download, wallets, datasets, pieces, providers |
+| [**foc-docs**](skills/foc-docs/SKILL.md) | Documentation — search guides, SDK refs, concept explainers |
 
-The `source` string the CLI reports to Synapse/Warm Storage (telemetry & attribution) is stored in your config. Set it to identify your app or integration (defaults to `foc-cli`):
+Built with [incur](https://github.com/wevm/incur) for first-class agent support:
 
-```bash
-npx foc-cli wallet init --source my-app
-```
+- **MCP server** — every command as an MCP tool (`npx foc-cli --mcp`)
+- **Structured output** — `--json`, `--format yaml`, `--filter-output`
+- **Introspection** — `--schema` per command, `--llms` manifest
+- **TTY-aware** — interactive prompts for humans, structured output for agents
+- **Source tag** — `wallet init --source my-app` sets the attribution tag reported to Synapse (default `foc-cli`)
 
 ## How FOC Works
 
-FOC transforms Filecoin into a **programmable cloud storage layer**:
-
 | Layer | What it does |
 |-------|-------------|
 | **Storage** | Warm, retrievable files via FWSS (Filecoin Warm Storage Service) |
-| **Verification** | PDP (Proof of Data Possession) — cryptographic proof providers hold your data |
+| **Verification** | PDP — cryptographic proof providers hold your data |
 | **Settlement** | Filecoin Pay — continuous USDFC payment streams to providers |
-| **Developer** | Synapse SDK + this CLI — TypeScript APIs for storage, payments, retrieval |
-
-**Pricing:** $2.5/TiB/month per copy (minimum 2 copies). Minimum spend: 0.06 USDFC/month (~24 GiB).
-
-## Agent Features
-
-Built with [incur](https://github.com/wevm/incur) for first-class AI agent support:
-
-- **MCP Server** — all commands as MCP tools (`npx foc-cli --mcp`)
-- **Structured Output** — `--json`, `--format yaml`, `--token-count`
-- **Schema Introspection** — `npx foc-cli <cmd> --schema` for JSON Schema
-- **LLM Manifest** — `npx foc-cli --llms` for machine-readable docs
-- **TTY Awareness** — interactive prompts for humans, structured output for agents
-
-## Mainnet
-
-All commands default to **Calibration testnet**. Add `--chain 314` for mainnet:
-
-```bash
-npx foc-cli upload ./data.bin --chain 314
-```
+| **Developer** | Synapse SDK + this CLI |
 
 ## References
 
-- [FOC Documentation](https://docs.filecoin.cloud)
-- [LLM-friendly docs](https://docs.filecoin.cloud/llms.txt)
-- [Synapse SDK](https://github.com/FilOzone/synapse-sdk)
-- [PDP Overview](https://docs.filecoin.cloud/core-concepts/pdp-overview/)
-- [Filecoin Pay](https://docs.filecoin.cloud/core-concepts/filecoin-pay-overview/)
+[FOC Documentation](https://docs.filecoin.cloud) · [LLM-friendly docs](https://docs.filecoin.cloud/llms.txt) · [Synapse SDK](https://github.com/FilOzone/synapse-sdk) · [PDP Overview](https://docs.filecoin.cloud/core-concepts/pdp-overview/) · [Filecoin Pay](https://docs.filecoin.cloud/core-concepts/filecoin-pay-overview/)
 
 ## License