From 127acce223699fe852323de6a85a68654a30cbe0 Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 12:00:01 -1000 Subject: [PATCH 1/3] docs(skill): guide wallet setup from environment --- skills/foc-cli/SKILL.md | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/skills/foc-cli/SKILL.md b/skills/foc-cli/SKILL.md index 0b7973d..580bc16 100644 --- a/skills/foc-cli/SKILL.md +++ b/skills/foc-cli/SKILL.md @@ -27,6 +27,28 @@ npx foc-cli -h # usage, args, options, examples npx foc-cli --schema --format json # JSON Schema: args, options, output shape ``` +## Before wallet setup + +For any workflow that needs a wallet, use **DISCOVER → EXPLAIN → ASK** before initializing or funding one: + +1. **Discover:** inspect the available wallet, custody, and secret-manager skills or tools, then safely check for an existing foc-cli wallet: + + ```bash + npx foc-cli wallet init --json + ``` + + With no initialization method, this keeps an existing wallet unchanged and reports whether one is configured; if none exists, it reports that a method is required. Never inspect the config contents or request, read, or display a private key. +2. **Explain:** tailor the relevant choices to what you found: + - Reuse an existing foc-cli wallet; never replace it automatically. + - A compatible secret-manager integration can provide a signing key through `--keyRef` without storing the key in foc-cli. + - Another wallet skill can fund the foc-cli public address even when it cannot sign foc-cli operations. + - If nothing suitable exists, offer a new dedicated foc-cli wallet. + - **Calibration** is for testing with faucet-provided tFIL and tUSDFC. **Mainnet** uses real FIL for gas and real USDFC for storage. + - On Calibration, offer agent-assisted faucets or show the address for user funding. On mainnet, show the address and funding instructions, then wait for the user to fund it. +3. **Ask:** ask only for choices the environment and request have not resolved: the operation's network, wallet approach, and who will fund it. Recommend reusing a suitable existing foc-cli wallet or compatible key integration when one was found. Otherwise, for a first test, recommend Calibration, a new dedicated wallet, and agent-assisted faucet funding. + +Do not initialize or fund a wallet until those choices are resolved. + ## What is FOC? FOC turns Filecoin into a **programmable cloud** with four layers: @@ -178,14 +200,20 @@ To acceptance-test a whole dataset, list its piece CIDs via `piece list` or `dat ## Workflows -### First-time setup (testnet) +### First-time setup (selected Calibration path) + +Only after the user chooses Calibration, a dedicated wallet, and agent-assisted faucet funding: ```bash npx foc-cli wallet init --auto -npx foc-cli wallet fund -npx foc-cli wallet costs --extraBytes 1000000 --extraRunway 1 # estimate before depositing -npx foc-cli wallet deposit 1 -npx foc-cli wallet balance +npx foc-cli wallet fund --chain 314159 +npx foc-cli wallet balance --chain 314159 +``` + +Before depositing or uploading, estimate the actual file and runway requirements, show the result, and obtain confirmation: + +```bash +npx foc-cli wallet costs --chain 314159 --extraBytes --extraRunway ``` ### Upload files From 8df4b27a7b22999a7c41c153336584f76c4c75f7 Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 12:58:32 -1000 Subject: [PATCH 2/3] docs(skill): require runway before cost estimate --- skills/foc-cli/SKILL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/skills/foc-cli/SKILL.md b/skills/foc-cli/SKILL.md index 580bc16..858ee17 100644 --- a/skills/foc-cli/SKILL.md +++ b/skills/foc-cli/SKILL.md @@ -47,6 +47,8 @@ For any workflow that needs a wallet, use **DISCOVER → EXPLAIN → ASK** befor - On Calibration, offer agent-assisted faucets or show the address for user funding. On mainnet, show the address and funding instructions, then wait for the user to fund it. 3. **Ask:** ask only for choices the environment and request have not resolved: the operation's network, wallet approach, and who will fund it. Recommend reusing a suitable existing foc-cli wallet or compatible key integration when one was found. Otherwise, for a first test, recommend Calibration, a new dedicated wallet, and agent-assisted faucet funding. +Before running `wallet costs`, also ask for the storage runway if the request does not specify one; do not guess a financially relevant duration. + Do not initialize or fund a wallet until those choices are resolved. ## What is FOC? From c951a42b3d9303034e30b37d3f85e3754d3f0fdc Mon Sep 17 00:00:00 2001 From: Mikers Date: Mon, 31 Aug 2026 13:05:32 -1000 Subject: [PATCH 3/3] docs(skill): match quotes to upload options --- skills/foc-cli/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/foc-cli/SKILL.md b/skills/foc-cli/SKILL.md index 858ee17..d67958a 100644 --- a/skills/foc-cli/SKILL.md +++ b/skills/foc-cli/SKILL.md @@ -212,10 +212,10 @@ npx foc-cli wallet fund --chain 314159 npx foc-cli wallet balance --chain 314159 ``` -Before depositing or uploading, estimate the actual file and runway requirements, show the result, and obtain confirmation: +Before depositing or uploading, estimate the actual file and runway requirements with the same `--copies` and `--withCDN` settings planned for the upload, show the result, and obtain confirmation: ```bash -npx foc-cli wallet costs --chain 314159 --extraBytes --extraRunway +npx foc-cli wallet costs --chain 314159 --extraBytes --extraRunway [--copies ] [--withCDN] ``` ### Upload files