docs(storage): refresh store and retrieval examples (#76)

* docs(storage): refresh store and retrieval examples

* docs(storage): address retrieval review notes

* docs(storage): swap Storacha for fil.one and Pinata in storage lists

---------

Co-authored-by: nijoe1 <nick@fil.builders>

Author: snissn

build/cookbook/filecoin-pin/erc-8004-agent-registration.md

@@ -685,7 +685,7 @@ Get more from the [faucet](https://www.alchemy.com/faucets/base-sepolia) if need
 ```bash
 curl -s "https://ipfs.io/ipfs/<CID>/github-agent-card.json" | jq .
 curl -s "https://gateway.pinata.cloud/ipfs/<CID>/github-agent-card.json" | jq .
-curl -s "https://cloudflare-ipfs.com/ipfs/<CID>/github-agent-card.json" | jq .
+curl -s "https://dweb.link/ipfs/<CID>/github-agent-card.json" | jq .
 ```
 
 ### Issue: PDP proofs not showing

build/cookbook/filecoin-pin/faq.md

@@ -55,7 +55,7 @@ On **Calibration testnet** (the demo website), data has no persistence guarantee
 
 A Data Set groups your uploads together. Each upload becomes a "piece" within the Data Set. Multiple files you upload share the same payment rail.
 
-Check your Data Set with `filecoin-pin data-set <id>`.
+Check your Data Set with `filecoin-pin data-set show <id>`.
 
 ***
 
@@ -64,7 +64,7 @@ Check your Data Set with `filecoin-pin data-set <id>`.
 Three methods:
 
 1. **IPFS Gateways:** Use public gateways with your root CID: `https://gateway.example.com/ipfs/<root-cid>`
-2. **Direct from Storage Provider:** Get the direct download URL from `filecoin-pin data-set <id>`
+2. **Direct from Storage Provider:** Get the direct download URL from `filecoin-pin data-set show <id>`
 3. **IPFS Tools:** Use Kubo, Helia, IPFS Desktop with your root CID.
 
 ***
@@ -85,7 +85,7 @@ Both are linked cryptographically on-chain.
 
 Two ways to verify:
 
-1. **CLI:** Run `filecoin-pin data-set <id>` to see on-chain verification. Check proof status and piece details.
+1. **CLI:** Run `filecoin-pin data-set show <id>` to see on-chain verification. Check proof status and piece details.
 2. **PDP Explorer:** Visit `https://pdp.vxb.ai/calibration/dataset/{datasetID}` to view proofs in your browser.
 
 {% hint style="info" %}

build/cookbook/filecoin-pin/getting-started.md

@@ -33,7 +33,7 @@ Before starting, make sure you have:
 Install the CLI globally with npm:
 
 ```sh
-npm install -g filecoin-pin
+npm install -g filecoin-pin@latest
 ```
 
 Verify the installation:
@@ -71,22 +71,29 @@ In MetaMask:
 
 The private key is a 64-character hex string, with or without an `0x` prefix.
 
-### 2️⃣ Save the private key to a `.env` file
+### 2️⃣ Save or export the private key
+
+The Filecoin Pin CLI does not store your key, but a `.env` file is still a local file on disk. Use a private working directory, keep `.env` out of git, and delete the file when you no longer need it.
 
 Create a file named `.env` in your working directory containing:
 
-```
+```sh
 export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"
 ```
 
 Then secure it and load it into your shell:
 
 ```sh
+printf '.env\n' >> .gitignore
 chmod 600 .env
 source .env
 ```
 
-Add `.env` to your `.gitignore` if you're inside a git repository.
+For a one-off shell session, you can avoid writing the key to disk and export it directly instead:
+
+```sh
+export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"
+```
 
 ***
 
@@ -223,13 +230,13 @@ filecoin-pin add my-data/
 
 Your file is now retrievable via standard IPFS tooling using its Root CID. For example:
 
-```
+```text
 https://<YOUR_ROOT_CID>.ipfs.inbrowser.link
 ```
 
 Or via the dweb.link gateway:
 
-```
+```text
 https://dweb.link/ipfs/<YOUR_ROOT_CID>
 ```
 
@@ -246,13 +253,13 @@ Filecoin storage providers must cryptographically prove daily that they continue
 List the data sets associated with your wallet:
 
 ```sh
-filecoin-pin data-set --ls
+filecoin-pin data-set list
 ```
 
 Then get the full on-chain detail for a specific data set:
 
 ```sh
-filecoin-pin data-set <DATASET_ID>
+filecoin-pin data-set show <DATASET_ID>
 ```
 
 This queries the smart contracts directly, so the values are live blockchain state.

build/cookbook/retrieve-data.md

@@ -8,83 +8,50 @@ description: >-
 
 ### <mark style="color:blue;">Retrieve data using retrieval clients</mark>
 
-To retrieve data stored on the Filecoin network, the basic process involves making retrieval requests to Service Providers (SPs) who initially stored the data, using either the Content ID (CID) or the storage deal ID.
+To retrieve data stored on the Filecoin network, the basic process involves making retrieval requests to storage providers or IPFS peers using the root Content ID (CID) for the data.
 
-A programmatic option is to utilize Filecoin retrieval clients, which handle the intricate retrieval process behind the scenes. By simply providing a Content ID (CID), retrieval clients can efficiently return your data either via the command-line interface (CLI) or through the programmable method.
+Filecoin retrieval clients handle provider discovery and transport selection behind the scenes. Provide the root CID, and the client returns the data through a command-line interface or a library integration.
 
 #### **Ingredients**
 
-With a given CID, you can use any of the following retrieval clients to retrieve content.
+With a given CID, you can use the following maintained retrieval tooling:
 
-* [Lassie](https://github.com/filecoin-project/lassie): optimizes for most efficient available retrieval protocols.
-  * [go-car](https://github.com/ipld/go-car): a content addressable archive utility.
+* [Lassie](https://github.com/filecoin-project/lassie): retrieves IPFS and Filecoin content over the best available protocols.
+* [go-car](https://github.com/ipld/go-car): reads, lists, and extracts content-addressed archive (CAR) files.
 
 #### **Instructions**
 
 **Retrieving content with Lassie**
 
-Lassie is designed to fetch content in the content-addressed archive (CAR) form. In most cases, you will require additional tooling, such as the go-car library, to work with CAR files effectively.
+Install the current Lassie and go-car command-line tools. Make sure [Go](https://go.dev/doc/install) is installed and that your Go binary directory is on your `PATH`, or download the latest binaries from the [Lassie releases](https://github.com/filecoin-project/lassie/releases/latest) and [go-car releases](https://github.com/ipld/go-car/releases/latest):
 
-The Lassie command line interface (CLI) provides the simplest method for retrieving content from the Filecoin/IPFS network. By using the `lassie fetch` command and passing the CID as an argument, you can easily retrieve the desired content.
-
-<pre class="language-jsx"><code class="lang-jsx"><strong>lassie fetch -o - &#x3C;CID> | car extract
-</strong></code></pre>
+```sh
+go install github.com/filecoin-project/lassie/cmd/lassie@latest
+go install github.com/ipld/go-car/cmd/car@latest
+```
 
-For example,
+Lassie fetches content in CAR form. Stream the CAR to go-car when you want to extract the UnixFS files immediately:
 
+```sh
+lassie fetch -o - <CID> | car extract -
 ```
-lassie fetch -p bafybeic56z3yccnla3cutmvqsn5zy3g24muupcsjtoyp3pu5pm5amurjx4 | car extract
+
+To save the CAR for later inspection or extraction:
+
+```sh
+lassie fetch -p -o <CID>.car <CID>
+car ls -f <CID>.car
+car extract -f <CID>.car
 ```
 
-Lassie can also serve as a go library within your Golang application when programmatically retrieving content from the network. To utilize Lassie in your code, you need to install the dependency and import it into your program following the instructions [here](https://github.com/filecoin-project/lassie?tab=readme-ov-file#golang-library).
-
-The following example demonstrates how to use the Lassie library to fetch a CID.
-
-```go
-package main
-
-import (
-	"context"
-	"fmt"
-	"os"
-
-	"github.com/filecoin-project/lassie/pkg/lassie"
-	"github.com/filecoin-project/lassie/pkg/storage"
-	"github.com/filecoin-project/lassie/pkg/types"
-	"github.com/ipfs/go-cid"
-	trustlessutils "github.com/ipld/go-trustless-utils"
-)
-
-// main creates a default lassie instance and fetches a CID
-func main() {
-	ctx := context.Background()
-
-	// Create a default lassie instance
-	lassie, err := lassie.NewLassie(ctx)
-	if err != nil {
-		panic(err)
-	}
-
-	// Prepare the fetch
-	rootCid := cid.MustParse("bafybeic56z3yccnla3cutmvqsn5zy3g24muupcsjtoyp3pu5pm5amurjx4")       // The CID to fetch
-	store := storage.NewDeferredStorageCar(os.TempDir(), rootCid)                                 // The place to put the CAR file
-	request, err := types.NewRequestForPath(store, rootCid, "", trustlessutils.DagScopeAll, nil)  // The fetch request
-	if err != nil {
-		panic(err)
-	}
-
-	// Fetch the CID
-	stats, err := lassie.Fetch(ctx, request)
-	if err != nil {
-		panic(err)
-	}
-
-	// Print the stats
-	fmt.Printf("Fetched %d blocks in %d bytes\n", stats.Blocks, stats.Size)
-}
+For example:
 
+```sh
+lassie fetch -o - bafybeic56z3yccnla3cutmvqsn5zy3g24muupcsjtoyp3pu5pm5amurjx4 | car extract -
 ```
 
+For library integrations, use the current [Lassie Go library documentation](https://github.com/filecoin-project/lassie?tab=readme-ov-file#golang-library) instead of copying an example from this reference page.
+
 For quick retrieval of existing datasets with the methods above, check out the [Filecoin Dataset Explorer](https://datasets.filecoin.io/).
 
 * [Filecoin Dataset Explorer](https://datasets.filecoin.io/)

build/cookbook/store-data.md

@@ -18,8 +18,8 @@ Use the official resources below for implementation details.
 Use these resources to prepare CAR artifacts and storage inputs:
 
 * [Lighthouse documentation](https://docs.lighthouse.storage/)
-* [IPFS CAR tooling (`ipfs-car`)](https://github.com/web3-storage/ipfs-car)
-* [IPLD CAR specification and libraries](https://github.com/ipld/js-car)
+* [go-car command-line tooling](https://github.com/ipld/go-car)
+* [IPLD CAR specification and JavaScript libraries](https://github.com/ipld/js-car)
 * [IPFS Desktop / Kubo docs](https://docs.ipfs.tech/)
 
 Recommended outputs before proposing storage workflows:
@@ -41,6 +41,7 @@ Use the FOC stack for programmatic, verifiable storage at scale:
 For smaller datasets and managed ingestion paths:
 
 * [Storage onramps overview](../../getting-started/how-storage-works/storage-onramps.md)
+* [Filecoin Pin getting started](filecoin-pin/getting-started.md)
 * [Lighthouse documentation](https://docs.lighthouse.storage/)
 
 ### <mark style="color:blue;">Monitor storage deal status from a smart contract</mark>

getting-started/how-retrieval-works/basic-retrieval.md

@@ -30,15 +30,15 @@ Make sure that you have [Go](https://go.dev/) installed and that your `GOPATH` i
 
     Or download and install Lassie using the Go package manager:
 
-```
-go install github.com/filecoin-project/lassie/cmd/lassie@latest
-```
+    ```sh
+    go install github.com/filecoin-project/lassie/cmd/lassie@latest
+    ```
 
 2. Download the [go-car binary from the latest release](https://github.com/ipld/go-car/releases/latest) based on your system architecture or install the [go-car](https://github.com/ipld/go-car) package using the Go package manager. The go-car package makes it easier to work with content-addressed archive (CAR) files:
 
-```
-go install github.com/ipld/go-car/cmd/car@latest
-```
+    ```sh
+    go install github.com/ipld/go-car/cmd/car@latest
+    ```
 
 You now have everything you need to retrieve a file with Lassie and extract the contents with `go-car`.
 
@@ -51,7 +51,7 @@ The video below demonstrates how Lassie can be used to render content directly f
 Lassie and `go-car` can work together to retrieve and extract data from Filecoin. All you need is the CID of the content to download.
 
 ```shell
-lassie fetch -o - <CID> | car extract
+lassie fetch -o - <CID> | car extract -
 ```
 
 This command uses a `|` to chain two commands together. This will work on Linux or macOS. Windows users may need to use PowerShell to use this form. Alternatively, you can use the commands separately, as explained later on this page.
@@ -92,27 +92,27 @@ lassie fetch -p -o <OUTFILE_FILE_NAME> <CID>/path/to/content
 *   `-p` is an optional flag that tells Lassie that you would like to see detailed progress information as it fetches your data.
 
     For example:
-* ```plaintext
-  Fetching bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6
-  Querying indexer for bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6...
-  Found 4 storage providers candidates from the indexer, querying all of them:
-          12D3KooWPNbkEgjdBNeaCGpsgCrPRETe4uBZf1ShFXStobdN18ys
-          12D3KooWNHwmwNRkMEP6VqDCpjSZkqripoJgN7eWruvXXqC2kG9f
-          12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj
-          12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU
-  Querying [12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU] (started)...
-  Querying [12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj] (started)...
-
-  ...
-  ```
+
+    ```plaintext
+    Fetching bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6
+    Querying indexer for bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6...
+    Found 4 storage providers candidates from the indexer, querying all of them:
+            12D3KooWPNbkEgjdBNeaCGpsgCrPRETe4uBZf1ShFXStobdN18ys
+            12D3KooWNHwmwNRkMEP6VqDCpjSZkqripoJgN7eWruvXXqC2kG9f
+            12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj
+            12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU
+    Querying [12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU] (started)...
+    Querying [12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj] (started)...
+
+    ...
+    ```
 * `-o` is an optional flag that tells Lassie where to write the output to. If you don’t specify a file, it will append `.car` to your CID and use that as the output file name.
 
-If you specify `-p`, the output will be written to `stdout` so it can be piped to another command, such as `go-car`, or redirected to a file.
+  Use `-o -` to write the CAR stream to `stdout` so it can be piped to another command, such as `go-car`, or redirected to a file.
 
 * `<CID>/path/to/content` is the CID of the content you want to retrieve and an optional path to a specific file within that content. Example:
-* ```shell
-  lassie fetch -o - bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze/wiki/Cryptographic_hash_function | car extract - | less
-  ```
+
+      lassie fetch -o - bafybeiaysi4s6lnjev27ln5icwm6tueaw2vdykrtjkwiphwekaywqhcjze/wiki/Cryptographic_hash_function | car extract - | less
 
 A CID is always necessary, and if you don’t specify a path, Lassie will attempt to download the entire content. If you specify a path, Lassie will only download that specific file or, if it is a directory, the entire directory and its contents.
 
@@ -128,19 +128,19 @@ car extract -f <INPUT_FILE>[/path/to/file/or/directory] [<OUTPUT_DIR>]
 * `/path/to/file/or/directory` is an optional path to a specific file or directory within the CAR. If omitted, it will attempt to extract the entire CAR.
 * `<OUTPUT_DIR>` is an optional argument that tells `go-car` where to write the output to. If omitted, it will be written to the current directory.
 
-If you supply `-p`, as in the above example, it will attempt to extract the content directly to `stdout`. This will only work if we are extracting a single file.
+If you supply `-p`, `car extract` writes extracted file bytes directly to `stdout`. This only works when extracting a single file.
 
 In the example above, where we fetched a file named `lidar-data.tar`, the `>` operator was used to redirect the output of `car extract` to a named file. This is because the content we fetched was raw file data that did not have a name encoded. In this case, if we didn’t use `-` and `> filename`, `go-car` would write to a file named `unknown`. In this instance, `go-car` was used to reconstitute the file from the raw blocks contained within Lassie’s CAR output.
 
 `go-car` has other useful commands. The first is `car ls`, which can be used to list the contents of a CAR. The second is `car inspect`, which can be used to inspect the contents of the CAR and optionally verify the integrity of a CAR.
 
-And there we have it! Downloading and managing data from Filecoin is super simple when you use Lassie and Go-car!
+Lassie and go-car are the recommended command-line tools for retrieving and inspecting Filecoin data by CID.
 
 #### Lassie HTTP daemon
 
 The Lassie HTTP daemon is an HTTP interface for retrieving IPLD data from IPFS and Filecoin peers. It fetches content from peers known to have it and provides the resulting data in CAR format.
 
-```shell
+```http
 GET /ipfs/{cid}[/path][?params]
 ```
 

getting-started/how-storage-works/storage-onramps.md

@@ -8,13 +8,16 @@ description: >-
 
 Developers use web UIs, APIs, or libraries to send data to storage onramps. Behind the scenes, storage onramps receive the data and handle the underlying processes to store it in a reliable way, making deals with Filecoin storage providers.
 
-The available storage onramps are: 
+Examples of maintained storage onramps include:
 
-* [Lighthouse](https://lighthouse.storage/) "offers permanent, decentralized storage powered by Filecoin. Secure, scalable, and ideal for individuals, developers, and enterprises."
-* [Akave](https://www.akave.ai/) is "revolutionizing data management with a decentralized, modular solution that combines the robust storage of Filecoin with cutting-edge encryption and easy-to-use interfaces."  
-* [Storacha](https://storacha.network/) is an open hot storage network scales IPFS and Filecoin. Upload any data and Storacha will ensure it ends up on a decentralized set of IPFS and Filecoin storage providers. There Storacha [docs](https://docs.storacha.network/) detail the JavaScript and Go API libraries, and there is a no-code web uploader available as well.
-* [Singularity](https://data-programs.gitbook.io/singularity) "facilitates onboarding of large quantities of data (PB-scale) to the Filecoin network in an efficient, secure, and flexible way."
-* [CID Gravity](https://www.cidgravity.com/) is a "seamless gateway to the decentralized web", allowing you to drag and drop files through an easy-to-use UI that uploads files to Filecoin and IPFS.  
+* [Filecoin Onchain Cloud](../../build/advanced/filecoin-onchain-cloud.md) is a programmable, on-chain storage platform with verifiable storage proofs (PDP) and automatic payments (Filecoin Pay), accessed through the Synapse SDK.
+* [Filecoin Pin](../../build/cookbook/filecoin-pin/getting-started.md) is a CLI and API path for pinning IPFS-compatible content to Filecoin-backed storage with Filecoin Pay.
+* [fil.one](https://fil.one/) is S3-compatible object storage backed by Filecoin, with flat per-terabyte pricing and no egress fees. Point any S3 SDK or tool at its endpoint to store data with cryptographic integrity proofs. See the [fil.one docs](https://docs.fil.one/).
+* [Lighthouse](https://lighthouse.storage/) offers permanent, decentralized storage powered by Filecoin.
+* [Akave](https://www.akave.ai/) provides a decentralized data-lake and object-storage layer backed by Filecoin.
+* [Pinata](https://pinata.cloud/) is an IPFS pinning service for storing and serving files, media, and app data over IPFS. See the [Pinata docs](https://docs.pinata.cloud/).
+* [Singularity](https://data-programs.gitbook.io/singularity) facilitates onboarding large quantities of data to the Filecoin network.
+* [CID Gravity](https://www.cidgravity.com/) provides a web UI for uploading files to Filecoin and IPFS.
 * [Ramo](https://use.ramo.computer/) provides Filecoin-based, S3-compatible storage for data on Filecoin.
 
 [Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill\_Page+URL=https://docs.filecoin.io/getting-started/how-storage-works/storage-onramps)