FilOzone · nijoe1 · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025 · Oct 16, 2025
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -16,7 +16,7 @@ export default defineConfig({
   },
   integrations: [
     starlight({
-      title: 'Synapse',
+      title: 'Filecoin Onchain Cloud',
       logo: { src: './src/assets/foc-logo.svg', alt: 'synapse' },
       favicon: 'favicon.ico',
       customCss: ['./src/custom.css'],
@@ -80,17 +80,29 @@ export default defineConfig({
       sidebar: [
         {
           label: 'Introduction',
-          autogenerate: { directory: 'intro' },
+          autogenerate: { directory: 'introduction' },
         },
         {
-          label: 'Guides',
-          autogenerate: { directory: 'guides' },
+          label: 'Getting Started',
+          autogenerate: { directory: 'getting-started' },
+        },
+        {
+          label: 'Core Concepts',
+          autogenerate: { directory: 'core-concepts' },
+        },
+        {
+          label: 'Developers',
+          autogenerate: { directory: 'developers' },
         },
         {
           label: 'API',
           collapsed: true,
           autogenerate: { directory: 'api' },
         },
+        {
+          label: 'Resources',
+          autogenerate: { directory: 'resources' },
+        },
       ],
       expressiveCode: {
         plugins: [

diff --git a/docs/package.json b/docs/package.json
@@ -10,8 +10,15 @@
     "astro": "astro"
   },
   "dependencies": {
+    "@astrojs/starlight": "^0.35.2",
     "@filoz/synapse-sdk": "workspace:*",
-    "ethers": "^6.15.0"
+    "astro": "^5.13.0",
+    "ethers": "^6.15.0",
+    "expressive-code-twoslash": "^0.5.3",
+    "markdown-table": "^3.0.4",
+    "starlight-llms-txt": "^0.6.0",
+    "typedoc": "^0.28.9",
+    "typedoc-plugin-mdn-links": "^5.0.9"
   },
   "devDependencies": {
     "@astrojs/starlight": "^0.36.0",

diff --git a/docs/src/content/docs/core-concepts/architecture.mdx b/docs/src/content/docs/core-concepts/architecture.mdx
@@ -0,0 +1,6 @@
+---
+title: Architecture
+description: Learn about the architecture of Filecoin Onchain Cloud.
+sidebar:
+  order: 0
+---
diff --git a/docs/src/content/docs/core-concepts/filecoin-pay-overview.mdx b/docs/src/content/docs/core-concepts/filecoin-pay-overview.mdx
@@ -0,0 +1,6 @@
+---
+title: FilecoinPay
+description: Learn about the Filecoin Pay.
+sidebar:
+  order: 2
+--- 
diff --git a/docs/src/content/docs/core-concepts/fwss-overview.mdx b/docs/src/content/docs/core-concepts/fwss-overview.mdx
@@ -0,0 +1,6 @@
+---
+title: Warm Storage Service
+description: Learn about the Filecoin Warm Storage Service.
+sidebar:
+  order: 3
+---
diff --git a/...src/content/docs/core-concepts/how-to-build-your-own-service-best-practices.mdx b/...src/content/docs/core-concepts/how-to-build-your-own-service-best-practices.mdx
@@ -0,0 +1,6 @@
+---
+title: Building Your Own Service
+description: How to Build Your Own Service using Filecoin Onchain Cloud.
+sidebar:
+  order: 5
+---
diff --git a/docs/src/content/docs/core-concepts/index.mdx b/docs/src/content/docs/core-concepts/index.mdx
@@ -0,0 +1,6 @@
+---
+title: Overview
+description: Overview of Core Concepts of Filecoin Onchain Cloud.
+sidebar:
+  order: 0
+---
diff --git a/docs/src/content/docs/core-concepts/pdp-overview.mdx b/docs/src/content/docs/core-concepts/pdp-overview.mdx
@@ -0,0 +1,6 @@
+---
+title: PDP
+description: Learn about the PDP.
+sidebar:
+  order: 1
+---
diff --git a/docs/src/content/docs/developers/index.mdx b/docs/src/content/docs/developers/index.mdx
@@ -0,0 +1,6 @@
+---
+title: Overview
+description: Developers with Filecoin Onchain Cloud.
+sidebar:
+  order: 0
+---
diff --git a/...cs/developers/synapse-sdk-guides/payments/how-to-monitor-your-storage-usage.mdx b/...cs/developers/synapse-sdk-guides/payments/how-to-monitor-your-storage-usage.mdx
@@ -0,0 +1,6 @@
+---
+title: How to Monitor Your Storage
+description: How to Monitor Your Storage Usage using the Synapse SDK.
+sidebar:
+  order: 2
+---
diff --git a/...cs/developers/synapse-sdk-guides/payments/how-to-topup-your-storage-balance.mdx b/...cs/developers/synapse-sdk-guides/payments/how-to-topup-your-storage-balance.mdx
@@ -0,0 +1,6 @@
+---
+title: How to Topup Your Storage
+description: How to Topup Your Storage Balance using the Synapse SDK.
+sidebar:
+  order: 1
+---
diff --git a/docs/src/content/docs/developers/synapse-sdk-guides/payments/index.mdx b/docs/src/content/docs/developers/synapse-sdk-guides/payments/index.mdx
@@ -0,0 +1,6 @@
+---
+title: Overview
+description: Overview of Filecoin Pay using the Synapse SDK.
+sidebar:
+  order: 0
+---
diff --git a/docs/src/content/docs/developers/synapse-sdk-guides/payments/troubleshooting.mdx b/docs/src/content/docs/developers/synapse-sdk-guides/payments/troubleshooting.mdx
@@ -0,0 +1,6 @@
+---
+title: Troubleshooting
+description: Troubleshooting Filecoin Pay using the Synapse SDK.
+sidebar:
+  order: 3
+---
diff --git a/.../content/docs/developers/synapse-sdk-guides/storage/how-to-create-a-dataset.mdx b/.../content/docs/developers/synapse-sdk-guides/storage/how-to-create-a-dataset.mdx
@@ -0,0 +1,6 @@
+---
+title: How to Create a Dataset
+description: How to Create a Dataset using the Synapse SDK.
+sidebar:
+  order: 1
+---
diff --git a/...c/content/docs/developers/synapse-sdk-guides/storage/how-to-retrieve-a-file.mdx b/...c/content/docs/developers/synapse-sdk-guides/storage/how-to-retrieve-a-file.mdx
@@ -0,0 +1,6 @@
+---
+title: How to Retrieve a File
+description: How to Retrieve a File using the Synapse SDK.
+sidebar:
+  order: 3
+---
diff --git a/...src/content/docs/developers/synapse-sdk-guides/storage/how-to-upload-a-file.mdx b/...src/content/docs/developers/synapse-sdk-guides/storage/how-to-upload-a-file.mdx
@@ -0,0 +1,6 @@
+---
+title: How to Upload a File
+description: How to Upload a File using the Synapse SDK.
+sidebar:
+  order: 2
+---
diff --git a/docs/src/content/docs/developers/synapse-sdk-guides/storage/index.mdx b/docs/src/content/docs/developers/synapse-sdk-guides/storage/index.mdx
@@ -0,0 +1,6 @@
+---
+title: Overview
+description: Overview of Storage using the Synapse SDK.
+sidebar:
+  order: 0
+---
diff --git a/docs/src/content/docs/developers/synapse-sdk-guides/storage/troubleshooting.mdx b/docs/src/content/docs/developers/synapse-sdk-guides/storage/troubleshooting.mdx
@@ -0,0 +1,6 @@
+---
+title: Troubleshooting
+description: Troubleshooting Storage operations using the Synapse SDK.
+sidebar:
+  order: 4
+---
diff --git a/...ntent/docs/developers/synapse-sdk-guides/usage-monitoring/egress-monitoring.mdx b/...ntent/docs/developers/synapse-sdk-guides/usage-monitoring/egress-monitoring.mdx
@@ -0,0 +1,6 @@
+---
+title: Egress Monitoring
+description: Monitoring Egress Usage using the Synapse SDK.
+sidebar:
+  order: 2
+---
diff --git a/docs/src/content/docs/developers/synapse-sdk-guides/usage-monitoring/index.mdx b/docs/src/content/docs/developers/synapse-sdk-guides/usage-monitoring/index.mdx
@@ -0,0 +1,6 @@
+---
+title: Overview
+description: Overview of Monitoring Storage Usage using the Synapse SDK.
+sidebar:
+  order: 0
+---
diff --git a/...tent/docs/developers/synapse-sdk-guides/usage-monitoring/ingress-monitoring.mdx b/...tent/docs/developers/synapse-sdk-guides/usage-monitoring/ingress-monitoring.mdx
@@ -0,0 +1,6 @@
+---
+title: Ingress Monitoring
+description: Monitoring Ingress Usage using the Synapse SDK.
+sidebar:
+  order: 1
+---
diff --git a/docs/src/content/docs/getting-started/index.mdx b/docs/src/content/docs/getting-started/index.mdx
@@ -0,0 +1,62 @@
+---
+title: Overview
+description: Getting Started with Filecoin Onchain Cloud.
+sidebar:
+  order: 0
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+
+A JavaScript/TypeScript SDK for interacting with Filecoin Synapse - a smart-contract based marketplace for storage and other services in the Filecoin ecosystem.
+
+> ⚠️ **BREAKING CHANGES in v0.24.0**: Major terminology updates have been introduced. **Pandora** is now **Warm Storage**, **Proof Sets** are now **Data Sets**, **Roots** are now **Pieces** and **Storage Providers** are now **Service Providers**. Additionally, the storage API has been improved with a new context-based architecture. See the [Migration Guide](/guides/migration-guide/#0240) section for migration instructions.
+
+
+The Synapse SDK provides an interface to Filecoin's decentralized services ecosystem:
+
+- **🚀 Recommended Usage**: Use the high-level `Synapse` class for a streamlined experience with sensible defaults
+- **🔧 Composable Components**: Import and use individual components for fine-grained control over specific functionality
+
+The SDK handles all the complexity of blockchain interactions, provider selection, and data management, so you can focus on building your application.
+
+## Installation
+
+```bash
+npm install @filoz/synapse-sdk ethers
+```
+
+Note: `ethers` v6 is a peer dependency and must be installed separately.
+
+---
+
+## Project Structure
+
+This project uses a monorepo structure managed by `pnpm` workspaces. Core libraries reside in the `packages/` directory, examples in `examples/`, and this documentation site in `docs/`.
+
+
+<FileTree>
+
+- packages/
+  - synapse-sdk/ Core Synapse SDK library
+  - synapse-sdk-react/ React hooks and context
+- examples/ Usage examples and demos
+- docs/ This documentation site
+- pnpm-workspace.yaml Workspace configuration
+- package.json Root package file
+
+</FileTree>
+
+## Key Concepts
+
+Before diving into the code, understand these fundamental concepts:
+
+- **Service Contracts**: Smart contracts that manage specific services (like storage). Currently, **Warm Storage** is the primary service contract that handles storage operations and payment validation.
+- **Payment Rails**: Automated payment streams between clients and service providers, managed by the Payments contract. When you create a data set in Warm Storage, it automatically creates corresponding payment rails.
+- **Data Sets**: Collections of stored data managed by Warm Storage. Each data set has an associated payment rail that handles the ongoing storage payments.
+- **Pieces**: Individual units of data identified by PieceCID (content-addressed identifiers). Multiple pieces can be added to a data set for storage.
+- **PDP (Proof of Data Possession)**: The cryptographic protocol that verifies storage providers are actually storing the data they claim to store. Providers must periodically prove they possess the data.
+- **Validators**: Service contracts (like Warm Storage) act as validators for payment settlements, ensuring services are delivered before payments are released.
+
+## Usage
+
+The [`Synapse`](/api/synapse/classes/synapse/) class provides a complete, easy-to-use interface for interacting with Filecoin storage services.