docs: GA docs preview (do not merge)

docs/src/content/docs/cookbooks/payments-and-storage.mdx

@@ -8,8 +8,8 @@ sidebar:
 :::tip[What You'll Learn]
 
 - The mental model: deposit USDFC, FWSS handles payments to storage providers
-- How much storage costs (pricing, floors, CDN)
-- What payment rails are and why each dataset has up to three
+- How much storage costs (pricing, fees, CDN)
+- What payment rails are and why each data set has up to three
 - What happens if your account runs low on funds
 
 :::
@@ -41,47 +41,63 @@ This cookbook explains the underlying payment model. For practical code:
 
 ## Pricing
 
+Two recurring rates apply per data set:
+
 | Component | Cost | Notes |
 | -------------- | -------------------- | ------------------------------------------------------- |
-| **Storage** | $2.50/TiB/month | Minimum $0.06/month per dataset (~24.567 GiB threshold) |
-| **Sybil fee** | 0.1 USDFC (one-time) | Per new dataset creation; prevents state-growth spam |
-| **CDN egress** | $14/TiB downloaded | 1 USDFC top-up ≈ 71.5 GiB of downloads |
-| **CDN setup** | 1 USDFC (one-time) | Per dataset; reusing existing datasets incurs no cost |
+| **Storage** | $2.50/TiB/month per copy | Charged only while pieces exist. Empty data sets are free |
+| **Proving Service** | $0.024/data set/month | Flat per-data-set fee, added on top of the storage rate |
+| **CDN egress** | up to $0.014/GiB downloaded | Optional, via Filecoin Beam. About half this when served from cache |
 
 :::note
 "Month" always means exactly **30 days = 86,400 epochs** throughout the system. Filecoin epochs are ~30 seconds each.
 :::
 
-### Floor Pricing
+Each on-chain operation also pays a small one-time fee to the storage provider, covering the gas it spends on your behalf:
+
+| Operation | Fee |
+| -------------- | -------------------- |
+| **Create data set** | $0.025 |
+| **Add pieces** | $0.0005 + $0.0003 per piece |
+| **Schedule piece removals** | $0.002 per call |
+| **Terminate service** | $0.00112 (user-initiated only) |
+
+These are fractions of a cent. They are drawn from a ~$0.10 lockup reserve held while the data set is active, not billed separately on each call. See [Storage Costs: How the fees and lockup work](/developer-guides/storage/storage-costs/#how-the-fees-and-lockup-work) for the mechanics.
+
+:::caution[SDK pricing update in progress]
+The per-operation fees and the additive proving fee are live in the Warm Storage contract, but the SDK cost APIs (`getUploadCosts()`, `prepare()`) are still being updated to surface them, tracked in [synapse-sdk#763](https://github.com/FilOzone/synapse-sdk/issues/763). Until that lands, returned `rate` and `depositNeeded` values reflect the previous model.
+:::
+
+### Proving Fee
 
-Every dataset has a minimum monthly charge of **$0.06/month**, regardless of size. This compensates storage providers for the overhead of maintaining a dataset. Files under ~24.567 GiB all pay this same floor rate. Above that threshold, the natural rate (`bytes/TiB × $2.50/month`) takes over.
+The monthly cost of an active data set is `(bytes / TiB) × $2.50 + $0.024`. There is no minimum floor: a data set with no pieces costs nothing, and the rate activates when the first piece is added. Earlier pricing used a single $0.06/month minimum. The flat proving fee replaces it as an additive per-data-set charge.
 
-### Dataset Creation Costs
+### Data Set Creation Costs
 
-Creating a new dataset requires minimum available funds to cover the initial lockup plus the sybil fee:
+Creating a data set locks a small lifecycle reserve. The storage rate starts at zero and is set automatically when you add data:
 
 | Scenario | Minimum Funds Required |
 | -------- | ---------------------- |
-| No CDN | 0.16 USDFC (0.06 floor lockup + 0.10 sybil fee) |
-| With CDN | 1.16 USDFC (0.06 floor + 0.10 sybil + 0.70 CDN + 0.30 cache miss) |
+| No CDN | ~0.10 USDFC (lifecycle reserve lockup) |
+| With CDN | ~1.10 USDFC (0.10 reserve + 0.70 CDN egress + 0.30 cache-miss) |
 
-The storage rate starts at zero when a dataset is created and is set automatically when you add data.
+One-time fees such as the $0.025 creation fee are drawn from the lifecycle reserve, not added on top of these amounts.
 
 ## Payment Rails
 
-For each dataset, FWSS creates payment channels called **rails** that stream funds from your account to the storage provider. A dataset can have up to three rails:
+For each data set, FWSS creates payment channels called **rails** that stream funds from your account to the storage provider. A data set can have up to three rails:
 
 | Rail | Type | Purpose |
 | -------------- | --------- | ---------------------------------------- |
 | **PDP rail** | Streaming | Pays for storage at a rate per epoch |
 | **CDN rail** | Fixed | 0.7 USDFC lockup for CDN egress credits |
 | **Cache miss** | Fixed | 0.3 USDFC lockup for cache miss credits |
 
-Every dataset gets a PDP rail. CDN and cache miss rails are added only when CDN is enabled.
+Every data set gets a PDP rail, which also holds the ~$0.10 lifecycle reserve that one-time fees draw from. CDN and cache miss rails are added only when CDN is enabled.
 
 FWSS enforces a **30-day lockup period**: your account must always have enough funds to cover at least 30 days of storage at the current rate. Think of it as a security deposit. The funds aren't spent upfront, but they're reserved so providers are guaranteed payment even if you stop topping up.
 
-When you add data to an existing dataset, FWSS automatically adjusts the rail's payment rate. The SDK calculates the correct deposit amount for you via `getUploadCosts()` and `prepare()`.
+When you add data to an existing data set, FWSS automatically adjusts the rail's payment rate. The SDK calculates the correct deposit amount for you via `getUploadCosts()` and `prepare()`.
 
 ## Operator Approval
 

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/core-concepts/retrieval.mdx

@@ -0,0 +1,122 @@
+---
+title: Retrieval
+description: How the Filecoin Onchain Cloud serves stored data back to applications, from direct storage provider reads to CDN-accelerated delivery with Filecoin Beam.
+sidebar:
+  order: 5
+---
+
+Storing data is only half of a cloud platform. Applications also need to read it back quickly and reliably. The **Filecoin Onchain Cloud (FOC)** is built for a "store and serve" model, where every piece you store stays retrievable over HTTP for the life of its data set.
+
+This page explains how retrieval works in FOC and the paths available to you.
+
+## Content Addressing
+
+Every piece in FOC is identified by a **PieceCID**, a content-addressed identifier derived from the data itself. A PieceCID does not point at a location. It points at the content.
+
+This has two practical consequences for retrieval:
+
+- **Location independence.** The same PieceCID can be served by any provider that holds the piece, or by a CDN sitting in front of those providers. Retrieval can route around a slow or offline provider without changing the address.
+- **Verifiable downloads.** Because the identifier is derived from the bytes, a client can recompute the PieceCID of whatever it receives and confirm it matches what was requested. The Synapse SDK does this automatically on every download, so tampered or corrupted responses are rejected before they reach your application.
+
+## Retrieval Paths
+
+FOC offers three ways to retrieve a piece. They share the same PieceCID and can be mixed within a single application.
+
+| Path | Source | Latency | When to use |
+| ----- | ------- | ------- | ----------- |
+| **Direct SP retrieval** | Storage provider HTTP API | Seconds | Default. No extra setup or egress charges. |
+| **FilBeam (CDN) retrieval** | Filecoin Beam cache, backed by SPs | Milliseconds | Hot data, frequent reads, latency-sensitive apps. |
+| **IPFS retrieval** | IPFS network via Filecoin Pin | Varies | IPFS-native applications and gateways. |
+
+```mermaid
+graph TD
+    App[Application / Synapse SDK]
+
+    App -->|"withCDN"| FB[Filecoin Beam<br/>CDN cache]
+    App -->|direct| SP[Storage Providers<br/>Curio HTTP API]
+    App -->|IPFS| PIN[Filecoin Pin<br/>IPFS gateway]
+
+    FB -->|cache miss| SP
+    PIN --> SP
+```
+
+## Direct SP Retrieval
+
+The default path serves data straight from the storage providers that hold it. Each provider runs a Curio node that exposes an HTTP API, and pieces are fetched directly from that endpoint.
+
+Because data is content-addressed, retrieval does not require you to know which provider holds a given piece. The SDK resolves a serving URL for you:
+
+1. It reads your data sets on chain to find which providers store the piece.
+2. It probes those providers in parallel and selects one that confirms it has the piece.
+3. It downloads from that provider and validates the bytes against the PieceCID.
+
+This makes downloads **SP-agnostic**. If a piece lives on more than one provider, retrieval succeeds as long as any one of them is reachable.
+
+Direct retrieval has no egress charges. It is the right default for most workloads, with latency in the range of seconds.
+
+## FilBeam (CDN) Retrieval
+
+[**Filecoin Beam**](https://docs.filbeam.com/) is the retrieval and delivery layer of FOC. It is a content delivery network that caches pieces close to where they are requested, cutting retrieval latency from seconds to milliseconds.
+
+FilBeam serves each piece from a per-account subdomain keyed by PieceCID. On mainnet:
+
+```text
+https://<your-address>.filbeam.io/<pieceCid>
+```
+
+On calibration the host is `<your-address>.calibration.filbeam.io`. The SDK builds this URL for you, so you rarely construct it by hand.
+
+Retrieval through FilBeam follows one of two paths:
+
+- **Cache hit.** The piece is already in the FilBeam cache and is served directly. This is the fast path.
+- **Cache miss.** The piece is not yet cached. FilBeam retrieves it from a storage provider, serves it to the client, and warms the cache so later reads are hits.
+
+Both paths are metered. FilBeam tracks egress per data set and bills it based on volume, separately from the base storage cost, with cache misses priced higher than cache hits. See the [FilBeam pricing reference](https://docs.filbeam.com/how-it-works/pricing/) for current rates.
+
+You can inspect the remaining egress quotas for a data set through the SDK:
+
+```ts twoslash
+// @lib: esnext,dom
+import { Synapse } from "@filoz/synapse-sdk"
+import { privateKeyToAccount } from "viem/accounts"
+
+const synapse = await Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
+// ---cut---
+const stats = await synapse.filbeam.getDataSetStats(12345)
+console.log("Remaining CDN egress (cache hits):", stats.cdnEgressQuota)
+console.log("Remaining cache-miss egress:", stats.cacheMissEgressQuota)
+```
+
+For dashboards and other ways to track consumption, see the FilBeam [monitor usage guide](https://docs.filbeam.com/how-to-guides/monitor-usage/).
+
+FilBeam delivery is opt-in per data set. Storing with the `withCDN` option marks a data set as CDN-enabled, which keeps CDN and non-CDN data sets separate and routes downloads through FilBeam when requested.
+
+## IPFS Retrieval
+
+For applications that speak IPFS natively, content stored through [**Filecoin Pin**](/core-concepts/filecoin-pin/) is also served over the IPFS network. Filecoin Pin packs your data into an IPFS CAR, stores it on FOC providers, and announces it to IPNI, so it resolves through standard IPFS gateways by its root CID:
+
+```text
+https://dweb.link/ipfs/<your-root-cid>
+```
+
+This path lets IPFS-native apps treat FOC as a durable, verifiable backing store while keeping the addressing and access patterns their stack already uses. See the [Filecoin Pin quick start](/getting-started/filecoin-pin/) to pin and retrieve your first file.
+
+## Retrieving with the SDK
+
+The Synapse SDK exposes all of these paths through a single `download` method. Without `withCDN` it resolves a storage provider that holds the piece and downloads from it; setting `withCDN` adds the FilBeam URL to the sources it races. Either way, the returned bytes are validated against the requested PieceCID before they reach your application.
+
+For usage, code examples, CDN options, and provider-scoped reads, see [Retrieval in the Storage Operations guide](/developer-guides/storage/storage-operations/#retrieval).
+
+## Summary
+
+- Pieces are content-addressed by PieceCID, so retrieval is location-independent and verifiable.
+- **Direct SP retrieval** is the default. It is SP-agnostic and has no egress charges.
+- **FilBeam** adds a CDN layer for millisecond latency, billed on egress per data set.
+- **IPFS retrieval** via Filecoin Pin serves the same content to IPFS-native applications.
+
+## Next Steps
+
+- [Storage Operations](/developer-guides/storage/storage-operations/) - Upload and download with the SDK
+- [Filecoin Warm Storage Service](/core-concepts/fwss-overview/) - The service layer behind storage and retrieval
+- [Filecoin Pin](/core-concepts/filecoin-pin/) - Guaranteed IPFS pinning backed by FOC
+- [FilBeam Documentation](https://docs.filbeam.com/) - CDN delivery and egress pricing