docs: Add Introduction Section (#331)

longfeiWan9 · web-flow · commit 0dd2c793aa6e · 2025-11-06T11:48:30.000+08:00
* add intro section for the docs

* address Tims comments
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -16,8 +16,8 @@ export default defineConfig({
   },
   integrations: [
     starlight({
-      title: 'Synapse',
-      logo: { src: './src/assets/foc-logo.svg', alt: 'synapse' },
+      title: 'Filecion Onchain Cloud',
+      logo: { src: './src/assets/foc-logo.svg', alt: 'foc' },
       favicon: 'favicon.ico',
       customCss: ['./src/custom.css'],
       head: [
@@ -82,6 +82,10 @@ export default defineConfig({
           label: 'Introduction',
           autogenerate: { directory: 'intro' },
         },
+        {
+          label: 'Getting Started',
+          autogenerate: { directory: 'gettingStarted' },
+        },
         {
           label: 'Guides',
           autogenerate: { directory: 'guides' },
diff --git a/docs/src/assets/foc-diagram.png b/docs/src/assets/foc-diagram.png
diff --git a/docs/src/content/docs/gettingStarted/getting-started.mdx b/docs/src/content/docs/gettingStarted/getting-started.mdx
@@ -1,5 +1,5 @@
 ---
-title: Getting Started
+title: Quick Start
 description: Learn how to install and use the Synapse SDK.
 sidebar:
   order: 0
diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
@@ -1,6 +1,8 @@
 ---
 title:  Components
 description: Learn how to configure the Synapse SDK for different networks.
+sidebar: 
+  order: 2
 ---
 
 All components can be imported and used independently for advanced use cases. The SDK is organized to match the external service structure:
diff --git a/docs/src/content/docs/guides/migration-guide.mdx b/docs/src/content/docs/guides/migration-guide.mdx
@@ -1,6 +1,8 @@
 ---
 title: Migration guide
 description: Learn how to migrate to newer versions of the SDK.
+sidebar: 
+  order: 0
 ---
 
 
diff --git a/docs/src/content/docs/guides/network-configuration.mdx b/docs/src/content/docs/guides/network-configuration.mdx
@@ -2,7 +2,7 @@
 title:  Network Configuration
 description: Learn how to configure the Synapse SDK for different networks.
 sidebar: 
-  order: 2
+  order: 1
 ---
 
 ### RPC Endpoints
diff --git a/docs/src/content/docs/guides/rails-settlement.mdx b/docs/src/content/docs/guides/rails-settlement.mdx
@@ -1,6 +1,8 @@
 ---
 title: Rails & Settlement
 description: Guide to payment rails and settlement operations
+sidebar: 
+  order: 4
 ---
 
 Payment rails are the core mechanism for streaming payments between parties in the Synapse ecosystem. They enable continuous, per-epoch payments for services like storage.
diff --git a/docs/src/content/docs/guides/storage.mdx b/docs/src/content/docs/guides/storage.mdx
@@ -1,6 +1,8 @@
 ---
 title: Storage
 description: Guides for using the Storage API.
+sidebar: 
+  order: 3
 ---
 
 The Synapse SDK automatically handles all the complexity of storage setup for you - selecting providers, managing data sets, and coordinating with the blockchain.
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -1,6 +1,6 @@
 ---
-title: Synapse SDK
-description: A JavaScript/TypeScript SDK for interacting with Filecoin Onchain Cloud - a smart-contract based marketplace for storage and other services in the Filecoin ecosystem.
+title: Filecoin Onchain Cloud
+description: A decentralized cloud platform built on Filecoin that enables developers to store, retrieve, and manage data through smart contracts.
 template: splash
 editUrl: false
 lastUpdated: false
@@ -10,7 +10,7 @@ hero:
     file: ../../assets/corgi.png
   actions:
     - text: Get started
-      link: intro/getting-started/
+      link: intro/about/
       icon: right-arrow
     - text: Star on GitHub
       link: https://github.com/FilOzone/synapse-sdk
diff --git a/docs/src/content/docs/intro/about.md b/docs/src/content/docs/intro/about.md
@@ -0,0 +1,44 @@
+---
+title: About Filecoin Onchain Cloud
+description: Learn about Filecoin Onchain Cloud - a decentralized cloud platform built on Filecoin that enables smart-contract based storage and services.
+sidebar: 
+  order: 1
+---
+
+Since its launch, [**Filecoin Network**](https://filecoin.io/) has been the backbone for **decentralized data storage**, anchored by its *Proof-of-Replication (PoRep)* model that ensures the integrity of long-term, immutable data. However, as decentralized applications evolve, they demand **faster access, dynamic payments, and cryptographic verification** that can operate within smart contracts.
+
+[**Filecoin Onchain Cloud (FOC)**](https://www.filecoin.cloud/) addresses this next-generation demand by reimagining storage as a **programmable cloud service layer** — where each capability (storage, retrieval, billing, verification) exists as a composable onchain module. These modules can be combined, forked, or extended, giving builders the flexibility to create customized decentralized applications and data-driven services.
+
+Built on the **Filecoin Virtual Machine (FVM)** and powered by a distributed network of verifiable storage providers, Filecoin Onchain Cloud transforms the Filecoin Network from a large-scale cold storage layer into a programmable, service-based data infrastructure. 
+
+## Architecture
+
+FOC addresses this next-generation demand by creating composable onchain modules where each capability (storage, retrieval, billing, verification) can be combined, forked, or extended, giving developers the flexibility to create customized decentralized applications and data-driven services. It is built around four fundamental layers:
+
+1. **Warm Storage Services** – Provided by decentralized service providers using the Filecoin Warm Storage Service (FWSS), optimized for accessibility and speed through PDP proofs.
+2. **Payment & Settlement Layer** – Managed by Filecoin Pay, enabling flexible, auditable billing flows between clients and providers.
+3. **Retrieval Layer** – Powered by Filecoin Beam, enabling fast, CDN-like retrieval with verifiable delivery proofs and pay-per-byte billing.
+4. **Developer & Application Layer** – Powered by the Synapse SDK, which abstracts service contracts, data sets, and payment rails into simple APIs usable across web, node, and edge environments.
+
+![Filecoin Onchain Cloud Architecture](../../../assets/foc-diagram.png)
+
+### Key Properties
+
+At its core, Filecoin Onchain Cloud delivers cloud-grade performance and usability with verifiable onchain properties:
+
+- 🔑 **Ownership** — Data, payments, and service logic belong to users and developers, not intermediaries.
+- 🔍 **Verifiability** — Every transaction, proof, and interaction is recorded, auditable, and cryptographically verifiable on the Filecoin blockchain.
+- ⚙️ **Programmability** — Services are governed by smart contracts that developers can compose, automate, or extend to suit diverse application needs.
+
+This design allows Filecoin to move beyond static data storage — offering real-time data services, decentralized payment flows, and programmable access policies that any developer can integrate through a unified interface.
+
+### Core Components
+
+The Filecoin Onchain Cloud services are built from foundational components that together create a verifiable, service-oriented cloud stack:
+
+- [**Proof of Data Possession (PDP)**](https://github.com/FilOzone/pdp) — The cryptographic proof layer ensuring data storage integrity and retrievability.
+- [**Filecoin Pay**](https://github.com/FilOzone/filecoin-pay) — The financial settlement engine that enables programmable payments for onchain services.
+- [**Filecoin Beam**](https://docs.filbeam.com/) — The retrieval and delivery network that ensures global accessibility of stored data.
+- [**Filecoin Warm Storage Service (FWSS)**](https://github.com/FilOzone/filecoin-services) — The operational layer providing fast, persistent, and verifiable data storage.
+
+Each of these components works independently yet integrates seamlessly through onchain smart contracts and the [**Synapse SDK**](https://github.com/FilOzone/synapse-sdk), forming a cohesive, modular system. Together, they deliver the core properties of a next-generation decentralized cloud: verifiability, programmability, and composability.
diff --git a/docs/src/content/docs/intro/why.md b/docs/src/content/docs/intro/why.md
@@ -0,0 +1,54 @@
+---
+title: Why Filecoin Onchain Cloud?
+description: Learn about the key benefits and use cases of Filecoin Onchain Cloud for decentralized storage and services.
+sidebar: 
+  order: 2
+---
+
+Traditional cloud storage solutions present several challenges:
+
+- **Centralized Control**: Data and services are controlled by a single provider
+- **Limited Transparency**: Operations and pricing are opaque
+- **Vendor Lock-in**: Difficult to migrate between providers
+- **Trust Requirements**: Users must trust providers to handle data properly
+- **Fixed Payment Models**: Inflexible billing tied to specific providers
+
+## The FOC Solution
+
+Traditional cloud services offer performance and usability but lack transparency, auditability, and user ownership. **Filecoin Onchain Cloud** bridges this gap by introducing a **trustless execution layer** for decentralized services. Each service in the Onchain Cloud — from storage to payment — operates as a smart contract, ensuring that every action, transaction, and proof is **verifiable on the Filecoin blockchain**.
+
+FOC is designed to:
+- ✅ **Enable hot and verifiable data storage and retrieval** with Proof of Data Possession (PDP) & Filecoin Beam
+- 🧩 **Simplify developer integration** through the Synapse SDK — a TypeScript library for building Filecoin-native dApps
+- 💰 **Power programmable payments** via Filecoin Pay — a token-agnostic payment rail for decentralized services
+- 💻 **Provide programmable services** — Smart contract-based, composable service primitives on top of the Filecoin network
+- 🚀 **Foster innovation** by letting teams build, fork, and combine services into new decentralized applications
+
+### Key Differentiators
+
+| Feature | Traditional Cloud | Filecoin Onchain Cloud |
+|---------|------------------|------------------------|
+| Data Control | Provider controlled | User owned |
+| Transparency | Limited | Full blockchain verification |
+| Programmability | Provider APIs | Smart contracts |
+| Payment Models | Fixed | Flexible & programmable |
+| Trust Model | Provider trust | Cryptographic proofs |
+| Vendor Lock-in | High | None |
+
+### Use Cases
+
+Filecoin Onchain Cloud opens the door for new classes of verifiable applications:
+
+- Decentralized data storage and pinning platforms (e.g., Filecoin Pin)
+- AI and compute services tied to verifiable data pipelines
+- Autonomous agents that own, store, and pay for their data
+- Regulatory-compliant archiving systems with proof-of-retention
+- Data DAOs and programmable marketplaces for shared datasets
+
+By unifying data, payments, and verifiability, FOC provides the foundation for the next generation of decentralized applications — where storage is not just a service, but a verifiable primitive.
+
+## Getting Started
+
+Ready to start building with Filecoin Onchain Cloud? Check out our [**Getting Started guide**](/docs/getting-started/) to learn how to integrate the Synapse SDK into your application.
+
+The **Synapse SDK** provides a simple, familiar API that abstracts away the complexity of blockchain interactions, allowing you to focus on building your application while leveraging the power of decentralized storage.
diff --git a/docs/src/custom.css b/docs/src/custom.css
@@ -23,3 +23,9 @@
   font-size: 0.8rem;
   color: #666;
 }
+
+/* Make diagram images smaller */
+img[src*="foc-diagram.png"] {
+  max-width: 80% !important;
+  height: auto !important;
+}
