docs: add Filecoin Pin concept and quickstart

docs/src/content/docs/core-concepts/filecoin-pin.mdx

@@ -0,0 +1,51 @@
+---
+title: Filecoin Pin
+description: Filecoin Pin bridges Filecoin and IPFS, providing guaranteed IPFS pinning powered by the Filecoin Onchain Cloud.
+sidebar:
+  order: 6
+---
+
+:::tip[Production-ready on Filecoin Mainnet]
+Filecoin Pin is live on Filecoin Mainnet and ready for use. Register for product updates and announcements at [filecoin.cloud](https://filecoin.cloud/).
+:::
+
+## What is Filecoin Pin?
+
+Filecoin Pin bridges Filecoin and IPFS. It provides the infrastructure for guaranteed IPFS pinning, where your content stays addressable with standard IPFS tooling and Filecoin storage providers back it with daily cryptographic proofs that they still hold it.
+
+When you pin content with Filecoin Pin, your IPFS data gains:
+
+- **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 on-chain.
+- **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 on-chain, with no dependency on a single company.
+- **Native 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.
+
+## How it works
+
+Filecoin Pin is built on the [Filecoin Onchain Cloud](/core-concepts/architecture/), the programmable storage stack that the Synapse SDK also exposes. Adding a file combines a familiar IPFS workflow with on-chain storage and payments:
+
+1. Filecoin Pin packs your file into an IPFS CAR and uploads it to a storage provider.
+2. The provider indexes the content and announces it to IPNI, so it resolves through standard IPFS gateways.
+3. The upload is recorded on-chain as a data set and piece through the [Filecoin Warm Storage Service](/core-concepts/fwss-overview/).
+4. The provider proves it still holds your data every day through [Proof of Data Possession](/core-concepts/pdp-overview/), and [Filecoin Pay](/core-concepts/filecoin-pay-overview/) releases payment as those proofs are verified.
+
+Everything you pin stays interoperable with the rest of the Filecoin Onchain Cloud. You can audit the same data sets, proofs, and payments on-chain, or manage them with the [Filecoin Pin CLI](https://github.com/filecoin-project/filecoin-pin) or the [Synapse SDK](/getting-started/).
+
+## Who is Filecoin Pin for?
+
+Filecoin Pin is for anyone who needs reliable, verifiable IPFS pinning:
+
+- **People moving from another pinning service**: if you are coming from Storacha, Pinata, or any other IPFS pinning service, Filecoin Pin gives you a place to keep your IPFS content pinned and accessible.
+- **Developers building on IPFS**: if you are building dApps, websites, AI agents, or other applications that rely on IPFS, Filecoin Pin provides the missing persistence layer with cryptographic guarantees.
+
+:::note[Migrating existing pins from Storacha?]
+This guide focuses on pinning new content. For migrating data already pinned on Storacha, see the dedicated migration guide (coming soon).
+:::
+
+## Next Steps
+
+- **[Quick Start with Filecoin Pin](/getting-started/filecoin-pin/)**: the fastest path to pinning your first file. Install the CLI, connect your wallet, deposit storage credit, and pin content end to end in around 10 minutes. Start here.
+- **[Behind the Scenes of Adding a File](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/behind-the-scenes-of-adding-a-file.md)**: a deep dive into how Filecoin Pin packs, stores, and proves your data on-chain.
+- **[Filecoin Pin repository](https://github.com/filecoin-project/filecoin-pin)**: source code and technical documentation.
+- **[Filecoin Slack #fil-foc](https://filecoinproject.slack.com/archives/C07CGTXHHT4)**: join for real-time developer support and updates, or [open an issue](https://github.com/filecoin-project/filecoin-pin/issues) on GitHub.

docs/src/content/docs/getting-started/filecoin-pin.mdx

@@ -0,0 +1,313 @@
+---
+title: Quick Start with Filecoin Pin
+description: Install Filecoin Pin, connect your wallet, deposit storage credit, and pin your first file to Filecoin in around 10 minutes.
+sidebar:
+  order: 1
+---
+
+import { Steps } from '@astrojs/starlight/components'
+
+This guide walks you through pinning your first file to Filecoin using the Filecoin Pin CLI. By the end, you will be set up to:
+
+- Install the Filecoin Pin CLI
+- Connect your Ethereum-style wallet on Filecoin
+- Deposit storage credit on Filecoin Pay
+- Pin a file to Filecoin and retrieve it using standard IPFS tooling
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- **An Ethereum-style wallet on Filecoin**: MetaMask is the easiest option. If you do not have one set up, see [MetaMask setup](https://docs.filecoin.io/basics/assets/metamask-setup).
+- **FIL in your wallet**: to pay transaction gas fees on Filecoin.
+- **USDFC in your wallet**: to pay for storage. USDFC is the stablecoin used by Filecoin Onchain Cloud. The easiest way to get some is to [swap FIL for USDFC on Sushi](https://www.sushi.com/filecoin/swap?token0=NATIVE&token1=0x80b98d3aa09ffff255c3ba4a241111ff1262f045).
+
+## Install the Filecoin Pin CLI
+
+Install the CLI globally with npm:
+
+```sh
+npm install -g filecoin-pin
+```
+
+Verify the installation:
+
+```sh
+filecoin-pin --version
+```
+
+To see all available commands at any time:
+
+```sh
+filecoin-pin --help
+```
+
+## Connect Your Wallet
+
+The Filecoin Pin CLI signs transactions using your wallet's private key. You provide it as an environment variable; the CLI reads it directly and never stores it on disk.
+
+<Steps>
+
+1. **Export your private key from MetaMask**
+
+   :::danger[Treat your private key like a password]
+   Anyone with your private key has full control of your wallet and any funds in it. Never paste it into a website, share it over chat, commit it to a repository, or store it in plain text on a shared system.
+   :::
+
+   In MetaMask:
+
+   1. Open the MetaMask extension.
+   2. Click the three dots next to your account name.
+   3. Select **Account details**.
+   4. Click **Show private key**.
+   5. Enter your MetaMask password.
+   6. Copy the private key shown.
+
+   The private key is a 64-character hex string, with or without an `0x` prefix.
+
+2. **Save the private key to a `.env` file**
+
+   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
+   chmod 600 .env
+   source .env
+   ```
+
+   Add `.env` to your `.gitignore` if you are inside a git repository.
+
+</Steps>
+
+## Set Up Payments
+
+Filecoin Pin uses [Filecoin Pay](https://github.com/FilOzone/filecoin-pay) to manage storage payments. Before you can pin anything, you need to:
+
+1. Authorize the Warm Storage Service contract to spend USDFC on your behalf.
+2. Deposit USDFC into Filecoin Pay so storage providers can be paid.
+
+The CLI walks you through both steps interactively:
+
+```sh
+filecoin-pin payments setup
+```
+
+The CLI guides you through the following stages:
+
+<Steps>
+
+1. **Connect and check balances**
+
+   The CLI confirms it can connect to Filecoin Mainnet and reports your wallet's FIL and USDFC balances.
+
+   :::note
+   If you do not have enough FIL for gas or USDFC for storage, the CLI tells you and stops. Top up your wallet and try again.
+   :::
+
+2. **Review pricing**
+
+   The CLI shows current storage pricing per GiB per month and per TiB per month. Use this to estimate how much USDFC you want to deposit.
+
+3. **Choose a deposit amount**
+
+   The CLI asks: **"Would you like to deposit USDFC to enable storage?"** Answer **Yes**.
+
+   It then shows example monthly costs for common storage amounts (100 GiB, 1 TiB, 10 TiB) so you can pick a sensible deposit. When prompted **"How much USDFC would you like to deposit?"**, enter the amount you want. A first-time deposit of `10.0` USDFC is a reasonable starting point.
+
+4. **Confirm the deposit**
+
+   The CLI submits the deposit transaction on-chain and shows the transaction hash and your new storage capacity.
+
+   <details>
+   <summary>Example output</summary>
+
+   ```text
+   ✓ Deposit complete
+     Deposit tx: 0x1234...abcd
+
+   New Storage Capacity:
+     Total deposit: 10.00 USDFC
+     Capacity: ~XX GiB for 1 month
+   ```
+
+   </details>
+
+</Steps>
+
+**Top Up Your Runway (Optional)**:
+
+Once you have data stored, you can top up your deposit to cover a specific number of days at your current usage:
+
+```sh
+filecoin-pin payments fund --days 30
+```
+
+This deposits (or withdraws) the right amount of USDFC to give you exactly 30 days of runway based on what you are currently storing. You can use any number of days you like.
+
+:::note
+`payments fund --days <n>` computes the target from your current storage rate, so it only works **after** you have pinned something. Before your first upload it reports `No active spend detected` — set an explicit target with `filecoin-pin payments fund --amount <usdfc>` instead, or just come back to this step after pinning your first file.
+:::
+
+To check your current deposit balance, runway, and payment status at any time:
+
+```sh
+filecoin-pin payments status
+```
+
+## Pin Your First File
+
+Now you are ready to pin. Create a test file:
+
+```sh
+echo "Hello Filecoin Pin! This is my first file stored on Filecoin with verifiable proofs of storage and retrievable over IPFS." > demo.txt
+```
+
+:::note
+Pieces have a minimum size of 127 bytes once packed. Very small files (a few bytes) are rejected, so make sure your test file has a little content.
+:::
+
+Pin it to Filecoin:
+
+```sh
+filecoin-pin add demo.txt
+```
+
+The CLI will:
+
+1. Pack your file into IPFS-compatible format (a CAR file).
+2. Select storage providers automatically.
+3. Store your file with two providers for redundancy.
+4. Verify the upload was advertised to [IPNI indexers](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/glossary.md#ipni).
+
+<details>
+<summary>Example output</summary>
+
+```text
+Filecoin Pin Add
+
+✓ File validated (122.0 B)
+✓ Connected to Filecoin - Mainnet
+✓ File packed with root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
+✓ [Primary] Stored on provider 2
+✓ [Secondary] Stored on provider 9
+✓ IPNI provider records found. IPFS retrieval possible.
+
+━━━ Add Complete ━━━
+
+Root CID:  bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
+Piece CID: bafkzcibcfab4grpgq6e6rva4kfuxfcvibdzx3kn2jdw6q3zqgwt5cou7j6k4wfq
+Copies:    2/2
+
+Add completed successfully
+```
+
+</details>
+
+The **Root CID** is your IPFS Content Identifier; it is how you will retrieve your data. Save it somewhere.
+
+You can also pin a directory by passing the directory path instead of a file:
+
+```sh
+mkdir my-data
+echo "File 1" > my-data/file1.txt
+echo "File 2" > my-data/file2.txt
+filecoin-pin add my-data/
+```
+
+## Retrieve Your File
+
+Your file is now retrievable via standard IPFS tooling using its Root CID.
+
+For example, via a subdomain gateway:
+
+```text
+https://<YOUR_ROOT_CID>.ipfs.inbrowser.link
+```
+
+Or via the dweb.link gateway:
+
+```text
+https://dweb.link/ipfs/<YOUR_ROOT_CID>
+```
+
+Try opening one of those URLs in your browser; your file should load. You can also retrieve it programmatically using any IPFS-compatible client (Kubo, Helia, Lassie, etc.) by referencing the Root CID.
+
+## Inspect Your Storage Proofs
+
+Filecoin storage providers must cryptographically prove daily that they continue to store your data. You can inspect those proofs and the on-chain payment rails at any time.
+
+List the data sets associated with your wallet:
+
+```sh
+filecoin-pin data-set ls
+```
+
+Then get the full on-chain detail for a specific data set:
+
+```sh
+filecoin-pin data-set show <DATASET_ID>
+```
+
+This queries the smart contracts directly, so the values are live blockchain state.
+
+<details>
+<summary>Example output</summary>
+
+```text
+Filecoin Onchain Cloud Data Set Details for #14081
+
+#14081
+  Status: live
+  CDN add-on: enabled
+
+  Provider
+    ID: 4
+    Name: <provider-name>
+    Service URL: https://<provider-service-url>
+
+  Metadata
+    source: "filecoin-pin"
+    withCDN: ""
+    withIPFSIndexing: ""
+
+  Payment
+    PDP rail ID: 17487
+    FilBeam rail ID: 17490
+    FilBeam cache-miss rail ID: 17489
+    Payer: 0xYOUR_WALLET_ADDRESS
+    Payee: 0xPROVIDER_ADDRESS
+
+  Pieces
+    Total pieces: 1
+    Total size: 219.0 B
+
+    #0 (active)
+      PieceCID: bafkzcib...
+      Metadata
+        ipfsRootCID: "bafkrei..."
+        name: "demo.txt"
+```
+
+</details>
+
+Key things to look for:
+
+- **Status `live`**: your data set is active and being proved.
+- **CDN add-on**: whether the FilBeam CDN retrieval add-on is enabled for this data set.
+- **PDP rail ID**: your active storage-proof payment rail.
+- **Provider Service URL**: direct retrieval endpoint for your pieces.
+- **PieceCID / ipfsRootCID** per piece: the PieceCID is what the provider proves; the ipfsRootCID (your Root CID) is what you use to retrieve.
+
+You have successfully pinned your first file to Filecoin.
+
+## Next Steps
+
+- Run `filecoin-pin --help` to explore advanced usage, including auto-funding and custom provider selection.
+- Want to understand what is happening behind the scenes? Read [Behind the Scenes of Adding a File](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/behind-the-scenes-of-adding-a-file.md) for a deep dive into each step.
+- Join the community in Filecoin Slack [#fil-foc](https://filecoinproject.slack.com/archives/C07CGTXHHT4) for help, discussion, and updates.
+- Found a bug or have a feature request? [Open an issue](https://github.com/filecoin-project/filecoin-pin/issues) on GitHub.