Filecoin Pin docs: update landing page and add dApp demo and github action example

SUMMARY.md

@@ -208,6 +208,6 @@
   * [Decentralized Database](builder-cookbook/dapps/decentralized-database.md)
 * [Filecoin Pin](builder-cookbook/filecoin-pin/README.md)
   * [Filecoin Pin CLI](builder-cookbook/filecoin-pin/filecoin-pin-cli.md)
-  * [Host a website with Filecoin Pin using Github Actions](builder-cookbook/filecoin-pin/host-a-website-with-filecoin-pin-using-github-actions.md)
-  * [Store IPFS Files on Filecoin: A Drag-and-Drop Guide](builder-cookbook/filecoin-pin/store-ipfs-files-on-filecoin-a-drag-and-drop-guide.md)
+  * [Filecoin Pin Github Action](builder-cookbook/filecoin-pin/github-action.md)
+  * [Filecoin Pin dApp Demo](builder-cookbook/filecoin-pin/dapp-demo.md)
   * [FAQ](builder-cookbook/filecoin-pin/faq.md)

builder-cookbook/filecoin-pin/README.md

@@ -1,10 +1,41 @@
 ---
-description: How to use the Filecoin Pin CLI and creating GitHub Actions from the terminal
+description: Pin IPFS content to Filecoin using familiar IPFS tools and workflows.
 ---
 
 # Filecoin Pin
 
-* [filecoin-pin-cli.md](filecoin-pin-cli.md "mention")
-* [host-a-website-with-filecoin-pin-using-github-actions.md](host-a-website-with-filecoin-pin-using-github-actions.md "mention")
-* [store-ipfs-files-on-filecoin-a-drag-and-drop-guide.md](store-ipfs-files-on-filecoin-a-drag-and-drop-guide.md "mention")
-* [faq.md](faq.md "mention")
+## Status
+
+Filecoin Pin is currently **alpha software** running on Filecoin Calibration testnet. As of 2025-10-15, It is not recommended for production use yet, but it is undergoing active development and will be ready for production later in 2025Q4.
+
+## What is Filecoin Pin?
+
+Filecoin Pin is a fully decentralized persistence layer for IPFS content using the global network of Filecoin storage providers with cryptographic guarantees.
+
+When you use Filecoin Pin, your IPFS files gain:
+
+- **Verifiable persistence** - Storage providers must cryptographically prove daily that they continue to store and serve your data
+- **Economic incentives** - You only pay when storage proofs are successfully delivered and verified onchain
+- **Decentralized infrastructure** - Your data can be stored across a global network of independent storage providers
+- **Sovereign data** - Choose your providers, audit storage proofs and payments onchain, with no dependency on a single company
+- **Seamless IPFS integration** - Continue using standard [IPFS Mainnet](https://docs.ipfs.tech/concepts/glossary/#mainnet) tooling like Kubo, Helia, and IPFS HTTP Gateways while gaining Filecoin's persistence guarantees
+
+## Who is Filecoin Pin for?
+
+Filecoin Pin is designed for developers building on IPFS who need trustless, economically-incentivized persistence for their content. Whether you're building dApps, workflows, websites, AI agents, or other applications, Filecoin Pin provides the missing persistence layer for IPFS.
+
+## How to Get Started
+
+Get started using Filecoin Pin today with:
+1. [Filecoin Pin CLI](filecoin-pin-cli.md) - Upload new or existing IPFS files directly to Filecoin via the command line. Perfect for developers who want to integrate Filecoin storage into scripts, workflows, or local development environments.
+2. [Filecoin Pin GitHub Actions](github-action.md) - Use GitHub Actions to automatically publish websites or build artifacts to IPFS and Filecoin as part of your CI/CD pipeline. Ideal for static websites, documentation sites, and automated deployment workflows.
+3. [Filecoin Pin dApp Demo](dapp-demo.md) - Run or fork a simple demo dApp that demonstrates Filecoin Pin in a browser-based application. Great for understanding how to integrate Filecoin Pin into web applications.
+
+
+## Learn More
+
+- **[FAQ](faq.md)** - Common questions about Filecoin Pin
+- **[Filecoin Pin GitHub Repository](https://github.com/filecoin-project/filecoin-pin)** - Source code and technical documentation
+- **[Community and Support](https://github.com/filecoin-project/filecoin-pin?tab=readme-ov-file#community-and-support)** - Join the community for real-time developer support and updates.
+
+

builder-cookbook/filecoin-pin/dapp-demo.md

@@ -0,0 +1,107 @@
+---
+description: See an example of Filecoin Pin working end to end within a web context.
+---
+
+# Filecoin Pin dApp Demo
+
+## What You'll Build
+
+In this walkthrough, you’ll build a simple drag-and-drop file uploader that:
+
+- Stores IPFS files directly on Filecoin with built-in payments, all in browser!
+- Tracks real-time upload progress through each step
+- Retrieves data easily from IPFS Mainnet and the underlying Filecoin Service Provider
+- Verifies persistent storage with on-chain Filecoin proofs
+- Multi-user support with session-based authentication
+- Seamlessly integrates with React, TypeScript, and Vite
+
+## Setup
+
+We will start building by [forking the *filecoin-pin-website demo repo](https://github.com/filecoin-project/filecoin-pin-website/fork).* Make sure you have **Node.js 18+** and **npm 9+** installed.  The dapp works with Filecoin Calibration testnet. 
+
+This will take ~10min. ⏲️
+
+### Step 1: Fork, Clone, and Install Dependencies
+
+```bash
+# Fork the repo using the command below
+# or visit [https://github.com/filecoin-project/filecoin-pin-website/fork](https://github.com/filecoin-project/filecoin-pin-website/fork)
+gh repo fork filecoin-project/filecoin-pin-website
+
+git clone https://github.com/YOUR-USERNAME/filecoin-pin-website.git
+cd filecoin-pin-website
+npm install
+```
+
+### **Step 2: Set Up Your Filecoin Wallet**
+
+A Filecoin wallet is needed to send transactions on Filecoin and pay for the Filecoin storage service.
+
+This demo dapp supports two authentication methods:
+
+- **Private Key:** easiest for local development and learning.
+- **Session Key:** recommended for production deployments - allows multiple users to share one wallet safely.
+
+💡 The demo repo supports deployment with a shared session key, allowing multiple users to safely upload files using the same wallet. It has hardcoded DEFAULT_WALLET_ADDRESS and DEFAULT_SESSION_KEY that are ready to go, but please do NOT use it for production. You can override these defaults with env vars, see instructions [here](https://github.com/filecoin-project/filecoin-pin-website/blob/main/CONTRIBUTING.md#local-setup)!
+
+**2.1 Get test FIL and test USDFC**
+
+If you are using your own wallet, you need to get test FIL and test USDFC to pay for the Filecoin storage service and transactions.
+
+1. Create or use an existing Filecoin wallet on the ****Calibration testnet**** ([such as MetaMask](https://docs.filecoin.io/basics/assets/metamask-setup#tab-calibration)).
+
+2. Visit the [Filecoin Calibration Faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html) to get free test FIL (to pay for transaction gas).
+
+3. Visit the [Filecoin USDFC faucet]([https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc?__cf_chl_tk=qFwEfa7MNFkJlhKo32IUtR9rgP99qqf_XOmTs7qhusg-1758703656-1.0.1.1-gE8b6EQEmdp0lgg0gk5j2UZhF_69vRyYAAhtt..weyA))  to get test USDFC, which is a USD stable coin backed by FIL that can be used to pay for services.
+
+### **Step 3: Run Your dApp**
+
+Fire up your local development server:
+
+```bash
+ npm run dev
+```
+
+Visit `http://localhost:5173` and you should see your dApp running! That is all it takes to set up your app. Now, let’s upload a file to see the magic happen!
+
+## Store IPFS Files on Filecoin
+
+The magic happens in one key file [**`src/hooks/use-filecoin-upload.ts`**](https://github.com/filecoin-project/filecoin-pin-website/blob/main/src/hooks/use-filecoin-upload.ts). This is where your IPFS files get uploaded to Filecoin. 
+
+### Step 1: Upload the data
+
+- **Prepare Service** - Validates wallet balance and gets the Filecoin Warm Storage service initialized.
+- **Create CAR** - Converts your file to an IPFS CAR (Content Addressed aRchive) file.
+- **Upload** - Sends the CAR file to a Filecoin Storage Provider (SP).
+
+    ![](./assets/pinapp-upload.gif)
+
+### Step 2: Announce CIDs and confirm the transaction
+
+The Filecoin SP:
+
+- indexes the IPFS CAR file and publishes all the contained CIDs to the IPFS network via IPNI.
+- commits to the Filecoin network via onchain transactions to store the data. Once the transaction is confirmed, your data is paid to be persisted on Filecoin.
+
+    ![](./assets/pinapp-publish.gif)
+
+### Step 3: Download the data
+
+Your data is available from both the IPFS Mainnet network using standard traditional IPFS tooling and/or directly from Filecoin SPs.
+
+    ![](./assets/pinapp-download.gif)
+
+### **Step 4: Verify your data storage**
+
+Filecoin storage providers submit cryptographic proofs regularly onchain to prove that they are storing your data, and you can verify and see it for yourself [on the PDP Scan](https://pdp.vxb.ai/calibration).
+
+    ![](./assets/pinapp-viewproof.gif)
+
+That is it - you now have a dapp with a drag-and-drop interface to store IPFS Files on Filecoin!
+
+## Next Steps
+
+1. Check back on the [filecoin-pin-website repo](https://github.com/filecoin-project/filecoin-pin-website) - it will continue to be updated as new functionality is brought to filecoin-pin.
+2. Feel free to report any issues with the dApp demo to https://github.com/filecoin-project/filecoin-pin-website/issues
+3. Check out the the [other example uses of filecoin-pin](../).
+4. Ask questions or get help with filecoin-pin in the [supported communcation channels](https://github.com/filecoin-project/filecoin-pin?tab=readme-ov-file#support-info).

builder-cookbook/filecoin-pin/filecoin-pin-cli.md

@@ -1,50 +1,50 @@
 ---
-description: How to use the Filecoin Pin CLI to store IPFS data on Filecoin
+description: How to use the Filecoin Pin CLI to store and retrieve IPFS data on Filecoin
 ---
 
 # Filecoin Pin CLI
 
-### Get Started Now
+## Get Started Now
 
-#### 1. Setup Payments
+### Setup Payments
 
 Configure permissions for automatic payment handling:
 
 <figure><img src="../../.gitbook/assets/1 (2).png" alt=""><figcaption></figcaption></figure>
 
-#### 2. Upload Data
+### Upload Data
 
 Upload your file with automatic funding:
 
 <figure><img src="../../.gitbook/assets/2 (2).png" alt=""><figcaption></figcaption></figure>
 
-#### 3. Retrieve over an IPFS Gateway
+### Retrieve over an IPFS Gateway
 
 Retrieve your data using the IPFS gateway:
 
 <figure><img src="../../.gitbook/assets/3 (2).png" alt=""><figcaption></figcaption></figure>
 
-#### 4. Prove Storage
+### Prove Storage
 
 Verify your data is stored with cryptographic proofs:
 
 <figure><img src="../../.gitbook/assets/4 (1).png" alt=""><figcaption></figcaption></figure>
 
 ***
 
-> NOTE! For demo purposes, I have created a THROWAWAY PRIVATE KEY. **NEVER USE YOUR PRIVATE KEY IN A REPOSITORY OR EXPOSE IT**. The repo references using your private key LOCALLY as an ENV VARIABLE. When you create a GITHUB ACTION, use GITHUB SECRETS to store your private key.
+> NOTE! For demo purposes, this example uses a THROWAWAY PRIVATE KEY. **NEVER USE YOUR PRIVATE KEY IN A REPOSITORY OR EXPOSE IT**. The repo references using your private key LOCALLY as an ENV VARIABLE. When you create a GITHUB ACTION, use GITHUB SECRETS to store your private key.
 
-### Who is this for
+## Who is this for
 
 1. Existing IPFS developers who want to use Filecoin to persist their data
 2. Technical users who want to use GitHub Actions to automate deployment of IPFS Files onto decentralized storage
 3. Agent builders that want to store their agent cards and validation materials on Filecoin for cryptographic proof of storage
 
 ***
 
-### Prerequisites
+## Prerequisites
 
-#### Install Required Tools
+### Install Required Tools
 
 ```bash
 # Install Node.js 22+ (required for filecoin-pin)
@@ -68,7 +68,7 @@ curl -L https://foundry.paradigm.xyz | bash
 foundryup
 ```
 
-#### Verify Installation
+### Verify Installation
 
 ```bash
 filecoin-pin --version
@@ -86,11 +86,11 @@ cast --version
 
 ***
 
-### Part 0: Wallet Setup from Scratch
+## Wallet Setup from Scratch
 
 > **Note**: The `filecoin-pin` CLI expects a `PRIVATE_KEY` environment variable. This section shows initial setup.
 
-#### Step 0.1: Generate a New Wallet
+### Generate a New Wallet
 
 Generate wallet using Foundry:
 
@@ -100,15 +100,15 @@ cast wallet new
 
 Save the private key and wallet address.
 
-#### Step 0.2: Get Testnet FIL
+### Get Testnet FIL
 
 Get 100 tFIL from ChainSafe faucet (requires browser):
 
 ```bash
 open "https://faucet.calibnet.chainsafe-fil.io/funds.html"
 ```
 
-#### Step 0.3: Get USDFC Stablecoin
+### Get USDFC Stablecoin
 
 1. [Setup MetaMask with Filecoin Calibration](https://docs.filecoin.io/basics/assets/metamask-setup) (1-click import available)
 2. Import your private key to MetaMask
@@ -119,7 +119,7 @@ Final state: \~2 tFIL (gas) + 200 USDFC (storage payments)
 
 ***
 
-#### Step 0.4: Create Environment File
+### Create Environment File
 
 > I put my private key on this repo for DEMO purposes. It is a TESTNET KEY. **NEVER USE YOUR PRIVATE KEY IN A REPOSITORY OR EXPOSE IT**.
 
@@ -143,9 +143,11 @@ echo "RPC URL: $RPC_URL"
 
 ***
 
-### Step 1: Setup Payments
+## Using the CLI
 
-All commands in this section use the environment variables set in Part 0 (Step 0.4). If you're starting a new terminal session, reload them:
+### Setup Payments
+
+All commands in this section use the environment variables set in [Create Environment File](#create-environment-file). If you're starting a new terminal session, reload them:
 
 ```bash
 source ~/.filecoin-pin-env
@@ -165,7 +167,7 @@ filecoin-pin payments setup --auto
 
 ***
 
-#### Step 2: Upload Data
+### Upload Data
 
 Use `--auto-fund` flag to automatically handle payment deposits (v0.7.0+).
 
@@ -192,7 +194,7 @@ filecoin-pin add demo.txt
 
 ***
 
-#### Step 4b: Upload Directory
+### Upload Directory
 
 Package multiple files into a single CAR:
 
@@ -218,7 +220,7 @@ filecoin-pin add --auto-fund my-data/
 
 ***
 
-#### Step 5: Prove Storage
+### Prove Storage
 
 Get detailed information about a specific data set (this queries the blockchain directly) that includes proofs:
 
@@ -305,7 +307,7 @@ Data set inspection complete
 
 > 💡 **Note**: This command queries the smart contracts on-chain to retrieve all data set information. The data shown is live blockchain state, not cached data.
 
-#### Links
+## Links
 
 * FAQ: [Frequently Asked Questions](faq.md)
 * Filecoin Pin Docs:  [https://docs.filecoin.io/builder-cookbook/filecoin-pin](https://docs.filecoin.io/builder-cookbook/filecoin-pin)

builder-cookbook/filecoin-pin/github-action.md

@@ -0,0 +1,19 @@
+---
+description: Host a static website with Filecoin Pin using GitHub Actions
+---
+
+# Filecoin Pin GitHub Action
+
+`filecoin-pin` can be used in CI pipelines like GitHub Actions to upload assets to the Filecoin decentralized storage network.  Static website assets are particularly good candidates, given the existing tooling within the IPFS ecosystem for static website retrieval.
+
+The [Filecoin Pin repo](https://github.com/filecoin-project/filecoin-pin) has an [example upload to Filecoin GitHub Action](https://github.com/filecoin-project/filecoin-pin/tree/master/upload-action) that can be used directly or as a starting point for your own CI pipeline.  
+
+The example filecoin-pin upload action itself has a [usage example](https://github.com/filecoin-project/filecoin-pin/tree/master/upload-action/examples), and you can even see it in production as part of [filecoin-pin-website's CI pipeline](https://github.com/filecoin-project/filecoin-pin-website/tree/main/.github/workflows)!
+
+Below is also a video walkthrough of the example GitHub Action in use!
+
+{% embed url="https://www.youtube.com/watch?v=_2ZsMYXfgwI=" %}
+
+Note: there is more work coming soon to add "filecoin-pin functionality" directly to the robust [ipshipyard/ipfs-deploy-action](https://github.com/ipshipyard/ipfs-deploy-action) ([tracking issue](https://github.com/ipfs/ipfs-deploy-action/issues/39)).
+
+