docs(skill): guide testnet and mainnet funding

skills/foc-cli/SKILL.md

@@ -123,7 +123,7 @@ If anything in this file ever disagrees with the live `-h`/`--schema` output, tr
 
 No RPC or env setup is needed: `getChain()` from `@filoz/synapse-core/chains` bundles the viem chain definition, default Glif RPC endpoints, and every FOC contract address (USDFC, FWSS, Filecoin Pay, PDP verifier, provider registry) for both chains, keyed by chain ID. The CLI's only persistent state is its wallet config file (see Setup). For dApp environment setup (custom RPCs, Next.js env vars, browser wallets), search the live docs instead of guessing: `npx foc-cli docs --prompt "getting started"`.
 
-**Funding:** testnet is one command (`wallet fund`: free tFIL + tUSDFC from faucets). Mainnet has no faucet; real FIL (gas) and USDFC (storage) must be acquired. See [references/mainnet-funding.md](references/mainnet-funding.md) for exchange/bridge/swap/mint routes and the exchange-withdrawal address caveat.
+**Funding:** testnet is one command (`wallet fund`: free tFIL + tUSDFC from faucets), with balance checks and documented fallbacks in [references/testnet-funding.md](references/testnet-funding.md). Mainnet has no faucet; real FIL (gas) and USDFC (storage) must be acquired. See [references/mainnet-funding.md](references/mainnet-funding.md) for the user-funded workflow, exchange/bridge/swap/mint routes, and the exchange-withdrawal address caveat.
 
 ## Global Options
 

skills/foc-cli/references/mainnet-funding.md

@@ -5,6 +5,14 @@ Mainnet (`--chain 314`) uses **real funds**: FIL pays gas, USDFC pays for storag
 > The live source of truth is the FOC docs — verify before acting:
 > `npx foc-cli docs --url https://docs.filecoin.cloud/resources/additional-resources.md`
 
+## Agent workflow
+
+1. Run `npx foc-cli wallet balance --chain 314`, then show the user the public address and the FIL, wallet USDFC, total Filecoin Pay funds, and available Filecoin Pay funds separately. A brand-new address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero.
+2. Run `wallet costs` for the actual upload size, runway, copy count, and CDN setting. Use `alreadyCovered` and `depositNeeded` to estimate the initial funding requirement. This is not the final quote: upload re-quotes after selecting providers and may require additional funding.
+3. Explain only the shortfalls: FIL is required for gas, but wallet USDFC is required only when the quote needs an additional payment-account deposit. If `alreadyCovered` is true, do not ask the user to acquire more USDFC. Present acquisition routes only for missing assets, and do not perform an exchange, bridge, swap, or mint for the user.
+4. If funding is required, ask the user to fund the displayed address, then stop and wait. Re-run `wallet balance --chain 314` and `wallet costs` after the user says funding is complete.
+5. Show the latest estimate and required payment-account deposit, then obtain explicit confirmation before depositing or uploading.
+
 ## Your wallet address
 
 The foc-cli wallet is a standard EVM account (`0x…`) on the Filecoin EVM (FEVM); on Filecoin's native address format it corresponds to an `f410…` address. Get the address from `wallet balance`. **Caveat when withdrawing from exchanges:** not every exchange supports withdrawing FIL directly to `0x`/`f410` addresses. If yours doesn't, withdraw to a self-custody Filecoin wallet that can send to `0x` addresses (e.g. MetaMask with the Filecoin network, or Glif), then forward from there.
@@ -29,17 +37,22 @@ USDFC is a FIL-collateralized, USD-pegged stablecoin by Secured Finance ([docs](
 
 For most users storing data, **swapping** (1 or 2) is the right choice; minting (3) is a DeFi position, not just a purchase.
 
-## After funding
+## After any required funding
 
 ```bash
 npx foc-cli wallet balance --chain 314                 # confirm FIL + USDFC arrived
-npx foc-cli wallet costs --extraBytes <n> --extraRunway <months> --chain 314   # live rate + deposit needed
-npx foc-cli wallet deposit <amount> --chain 314        # move USDFC into the payment account
-npx foc-cli upload ./file.pdf --chain 314
+npx foc-cli wallet costs --extraBytes <n> --extraRunway <months> --chain 314 [--copies <n>] [--withCDN]
+```
+
+Show the estimate and wait for explicit human confirmation. Run `wallet deposit` only when `depositNeeded` is non-zero; otherwise skip it. Then obtain confirmation for the upload:
+
+```bash
+npx foc-cli wallet deposit <amount> --chain 314        # only when depositNeeded is non-zero
+npx foc-cli upload ./file.pdf --chain 314 [--copies <n>] [--withCDN]
 ```
 
 Cross-check the USDFC token you received against the address foc-cli itself uses — the CLI's bundled chain config (from `@filoz/synapse-core`) pins the official USDFC contract per chain, so a mismatched balance in `wallet balance` means you hold a different token than the one FOC pays with.
 
 ## Testnet (for contrast)
 
-On Calibration (the default chain) all of this is one command — `npx foc-cli wallet fund` — which claims free tFIL and tUSDFC from faucets.
+For the Calibration workflow and documented faucet fallbacks, see [testnet-funding.md](testnet-funding.md).

skills/foc-cli/references/testnet-funding.md

@@ -0,0 +1,54 @@
+# Calibration Funding: Getting tFIL and tUSDFC
+
+Calibration (`--chain 314159`) needs tFIL for gas and tUSDFC for storage payments. Both are test tokens.
+
+> The live source of truth is the FOC docs — verify before acting:
+> `npx foc-cli docs --url https://docs.filecoin.cloud/resources/additional-resources.md`
+
+## Agent workflow
+
+1. Inspect the address and current state:
+
+   ```bash
+   npx foc-cli wallet balance --chain 314159
+   ```
+
+   Report the address, tFIL (`fil`), wallet tUSDFC (`usdfc`), total Filecoin Pay funds (`funds`), and currently available Filecoin Pay funds (`availableFunds`) separately. A brand-new, unfunded address may return `ADDRESS_NOT_ON_CHAIN`; the error still includes the address and means every balance is zero.
+
+2. Run `wallet costs` for the actual upload size, runway, copy count, and CDN setting. Use `alreadyCovered` and `depositNeeded` to determine whether Filecoin Pay needs more tUSDFC. If `alreadyCovered` is true, do not request wallet tUSDFC. Otherwise, compare `depositNeeded` with the wallet tUSDFC balance and request only the shortfall.
+
+3. Use the user's funding choice if it is already known. Otherwise, ask whether the user wants to fund the address or wants agent-assisted faucet funding.
+
+   - **User-funded:** show the address and the documented faucets below, then stop and wait.
+   - **Agent-assisted, tFIL and tUSDFC both required:** run the built-in faucet command once:
+
+     ```bash
+     npx foc-cli wallet fund --chain 314159
+     ```
+
+   - **Only one asset required:** do not run the combined command; use the matching asset-specific browser handoff below.
+   - **Neither asset required:** skip funding.
+
+4. After `wallet fund`, read `fil.status` and `usdfc.status` separately. The top-level `status` is only a summary; do not infer both asset outcomes from it or from one combined error.
+
+   - **`funded`:** the faucet transaction succeeded and a positive balance was observed. Do not request that asset again.
+   - **`missing`:** the asset was not funded. If it is still required, use only its matching documented fallback below.
+   - **`unconfirmed`:** the submission, receipt, or balance check is still uncertain. Do not retry or use another faucet yet. Check any returned `txHash`, wait, then run:
+
+     ```bash
+     npx foc-cli wallet balance --chain 314159
+     ```
+
+     If the balance appears, continue without another claim. If it remains zero, report the unknown outcome and stop rather than risking a duplicate claim.
+
+5. After any required funding arrives, re-run `wallet costs`. Its `depositNeeded` and `needsFwssMaxApproval` fields are distinct from wallet and Filecoin Pay balances.
+
+## Documented fallback ladder
+
+Use browser handoff for these faucets; the user enters only the public wallet address and completes any human verification:
+
+1. **Missing tFIL:** use the [ChainSafe Calibration faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html). If it is unavailable, Filecoin Docs also lists the [Zondax faucet](https://beryx.zondax.ch/faucet/) and [Forest faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet).
+2. **Missing tUSDFC:** use the [Calibration tUSDFC faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc).
+3. Re-run `wallet balance --chain 314159` after each completed request and resume only from the observed balances.
+
+Do not infer or call faucet APIs from website code, bypass CAPTCHA or anti-bot controls, submit parallel faucet claims, or retry without first checking balances. Never ask for or enter the user's private key into a faucet.