docs: add Filecoin Pin Action composition example

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- README: new `Archiving to Filecoin` section. Chains the [`filecoin-pin`](https://github.com/filecoin-project/filecoin-pin) CLI (>=0.20.1) after this action to archive `build.car` without repacking, preserving the root CID. Uses `filecoin-pin import --auto-fund` with `--min-runway-days` and `--max-balance` to cap wallet spend per run.
+
 ## [1.9.2] - 2026-04-07
 
 ### Fixed

README.md

@@ -22,6 +22,7 @@ The [composite action](https://docs.github.com/en/actions/sharing-automations/cr
 - [Usage](#usage)
   - [Simple Workflow (No Fork PRs)](#simple-workflow-no-fork-prs)
   - [Dual Workflows (With Fork PRs)](#dual-workflows-with-fork-prs)
+  - [Archiving to Filecoin](#archiving-to-filecoin)
 - [FAQ](#faq)
 
 ## Features
@@ -288,6 +289,41 @@ See real-world examples:
 - [IPFS Specs](https://github.com/ipfs/specs/tree/main/.github/workflows) - Uses the secure two-workflow pattern
 - [IPFS Docs](https://github.com/ipfs/ipfs-docs/tree/main/.github/workflows) - Uses the secure two-workflow pattern
 
+### Archiving to Filecoin
+
+Archive the CAR this action produces to Filecoin with the [`filecoin-pin`](https://github.com/filecoin-project/filecoin-pin) CLI (>=0.20.1). `filecoin-pin import` consumes `build.car` from the runner workspace without repacking, so the root CID stays identical and the Filecoin storage deal layers on top of whichever hot-pinning provider you use above. You provision the wallet (FIL for gas, USDFC for storage); see the [filecoin-pin docs](https://github.com/filecoin-project/filecoin-pin#getting-started).
+
+Add the archival step to a simple workflow:
+
+```yaml
+      - name: Deploy to IPFS
+        id: deploy
+        uses: ipfs/ipfs-deploy-action@v1
+        with:
+          path-to-deploy: out
+          cluster-url: ${{ secrets.CLUSTER_URL }}
+          cluster-user: ${{ secrets.CLUSTER_USER }}
+          cluster-password: ${{ secrets.CLUSTER_PASSWORD }}
+          github-token: ${{ github.token }}
+
+      - name: Archive CAR to Filecoin
+        # Block fork PRs from this wallet-spending step: same-repo events only,
+        # so non-maintainer authors cannot trigger deposits.
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name
+        env:
+          PRIVATE_KEY: ${{ secrets.FILECOIN_WALLET_KEY }}
+        run: |
+          npx -y filecoin-pin import build.car \
+            --mainnet \
+            --auto-fund \
+            --min-runway-days 30 \
+            --max-balance 5.0
+```
+
+`--auto-fund` enables `--min-runway-days` and `--max-balance`, which cap the USDFC deposit per run. Pin a specific `filecoin-pin` version (`npx -y filecoin-pin@<version>`) once you have validated it against your wallet, so a wallet-spending step never picks up a new release without an explicit bump.
+
+For the dual-workflow pattern, add the archival step to `deploy.yml` after the existing `Deploy to IPFS` step; `build.car` persists for the rest of the job. For maximum safety with mainnet wallets, isolate the archival step in its own job gated by a GitHub [Environment](https://docs.github.com/en/actions/deployment/targeting-different-environments/managing-environments-for-deployment) with required reviewers, so no workflow change merges wallet access without human approval.
+
 ## FAQ
 
 - How can I safely build on PRs from forks?