diff --git a/site/docs/index.md b/site/docs/index.md
index d5640c9..df758c2 100644
--- a/site/docs/index.md
+++ b/site/docs/index.md
@@ -4,10 +4,11 @@ sidebar_position: 1
# Catalyst documentation hub
-This site is the single docs home for the Catalyst ecosystem.
+This is the public documentation hub for the Catalyst ecosystem.
## Choose your path
+- **Everyday users**: start with **[Use cases (for everyone)](/docs/use-cases/send-money)** or **[Quickstart: use Catalyst apps](/docs/quickstarts/i-want-to-use-apps)**.
- **Node operators**: start with **[Run a node](/docs/node-operators/run-a-node)**.
- **Wallet users**: start with **[Use the wallet](/docs/quickstarts/i-want-to-use-the-wallet)**.
- **dApp builders**: start with **[Deploy a contract](/docs/quickstarts/i-want-to-deploy-a-contract)**, then **[RPC: transaction lifecycle](/docs/rpc-reference/transaction-lifecycle)**.
diff --git a/site/docs/node-operators/install-build-binaries.md b/site/docs/node-operators/install-build-binaries.md
index 7bdaf28..b07375e 100644
--- a/site/docs/node-operators/install-build-binaries.md
+++ b/site/docs/node-operators/install-build-binaries.md
@@ -5,12 +5,28 @@ title: Install / build binaries
## You will need
-- Rust toolchain (for source builds)
-- Linux build dependencies (RocksDB, OpenSSL, toolchain)
+- Linux host
+- Either:
+ - a **release binary** (no build), or
+ - a Rust toolchain + build dependencies (source build)
## Steps
-### Build from source (recommended)
+### Option A (recommended): download a release binary (no build)
+
+If you want to run a node without compiling anything, use a published release.
+
+1) Go to the releases page and download the latest `catalyst-cli` for Linux.
+
+- Node repo releases: `https://github.com/catalyst-network/catalyst-node-rust/releases`
+
+2) Verify the checksum (recommended) and install the binary somewhere stable, for example:
+
+```bash
+sudo install -m 0755 catalyst-cli /usr/local/bin/catalyst-cli
+```
+
+### Option B: build from source
```bash
git clone https://github.com/catalyst-network/catalyst-node-rust
diff --git a/site/docs/node-operators/run-a-node.md b/site/docs/node-operators/run-a-node.md
index ee9f6a4..cbd9499 100644
--- a/site/docs/node-operators/run-a-node.md
+++ b/site/docs/node-operators/run-a-node.md
@@ -19,18 +19,34 @@ Running a public node is operationally risky. Treat the host as production infra
- Linux host (Ubuntu/Debian examples below)
- Open TCP **30333** (P2P). Open **8545** (RPC) only if you know what you’re doing (prefer IP allowlist / SSH tunnel).
-- Build deps (for source builds): `build-essential`, `clang`, `cmake`, `libssl-dev`
+- Either:
+ - a **release binary** (no build), or
+ - build deps (for source builds): `build-essential`, `clang`, `cmake`, `libssl-dev`
## Steps
-### 1) Install build dependencies (Ubuntu/Debian)
+### 1) Get the binary (no-build or source-build)
+
+Choose one:
+
+- **No build (recommended)**: download a `catalyst-cli` release binary
+ - `https://github.com/catalyst-network/catalyst-node-rust/releases`
+- **Build from source**: continue with the steps below
+
+If you downloaded a binary, install it to a stable path used by systemd, for example:
+
+```bash
+sudo install -m 0755 catalyst-cli /var/lib/catalyst/node/catalyst-cli
+```
+
+### 2) Install build dependencies (Ubuntu/Debian) (source builds only)
```bash
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev clang libclang-dev cmake
```
-### 2) Build the node
+### 3) Build the node (source builds only)
```bash
git clone https://github.com/catalyst-network/catalyst-node-rust
@@ -52,7 +68,7 @@ The binary is:
./target/release/catalyst-cli --help
```
-### 3) Create a dedicated user + directories
+### 4) Create a dedicated user + directories
```bash
sudo useradd --system --create-home --home-dir /var/lib/catalyst --shell /usr/sbin/nologin catalyst || true
@@ -61,7 +77,7 @@ sudo chown -R catalyst:catalyst /var/lib/catalyst
sudo chmod 700 /var/lib/catalyst
```
-### 4) Generate a config (safe defaults)
+### 5) Generate a config (safe defaults)
Catalyst can generate a default config file if the path doesn’t exist.
@@ -81,7 +97,7 @@ Stop it (Ctrl+C) after it starts once—this creates sibling directories near th
Do **not** delete `node.key` during resets/upgrades unless you intend to change the node’s network identity.
:::
-### 5) Run under systemd
+### 6) Run under systemd
Create a unit file:
@@ -122,6 +138,8 @@ sudo install -o catalyst -g catalyst -m 0755 \
/var/lib/catalyst/node/catalyst-cli
```
+If you used a release binary and already installed it to `/var/lib/catalyst/node/catalyst-cli`, you can skip this step.
+
Start:
```bash
@@ -130,7 +148,7 @@ sudo systemctl enable --now catalyst
sudo systemctl status catalyst --no-pager
```
-### 6) Firewall (minimum)
+### 7) Firewall (minimum)
If using `ufw`:
diff --git a/site/docs/quickstarts/i-want-to-use-apps.md b/site/docs/quickstarts/i-want-to-use-apps.md
new file mode 100644
index 0000000..357b6d0
--- /dev/null
+++ b/site/docs/quickstarts/i-want-to-use-apps.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 0
+title: "Quickstart: I want to use Catalyst apps"
+---
+
+This quickstart is for everyday users. The goal is to **use apps**—Catalyst should fade into the background.
+
+## You will need
+
+- A wallet app
+- (Testnet) Access to the faucet
+
+## Steps
+
+### 1) Start with a use case
+
+Pick what you want to do:
+
+- **[Send money](/docs/use-cases/send-money)**
+- **[Games and digital items](/docs/use-cases/games-assets)**
+- **[Social apps you control](/docs/use-cases/social-you-control)**
+
+### 2) Create an account in your wallet
+
+- Create a new account.
+- Back it up using the wallet’s instructions (offline is best).
+
+If you’re new, see:
+
+- **[Wallet → user guide](/docs/wallets/wallet-user-guide)**
+
+### 3) Get testnet funds (testnet only)
+
+- **[Faucet → user guide](/docs/faucet/user-guide)**
+
+### 4) Verify activity (optional but recommended)
+
+If something looks “stuck” in an app UI, the explorer can show the source of truth.
+
+- **[Explorer → user guide](/docs/explorer/user-guide)**
+
+## Verify
+
+- You can see your balance in the wallet.
+- The explorer shows your account activity.
+
diff --git a/site/docs/quickstarts/i-want-to-use-the-wallet.md b/site/docs/quickstarts/i-want-to-use-the-wallet.md
index aef7d7b..1d2420f 100644
--- a/site/docs/quickstarts/i-want-to-use-the-wallet.md
+++ b/site/docs/quickstarts/i-want-to-use-the-wallet.md
@@ -3,6 +3,8 @@ sidebar_position: 2
title: "Quickstart: I want to use the wallet"
---
+This quickstart is for everyday users. You don’t need to know how Catalyst works to use it.
+
## You will need
- A supported wallet app (web wallet for testnet)
@@ -12,7 +14,12 @@ title: "Quickstart: I want to use the wallet"
1) Open the wallet and create/import an account.
-2) Confirm the wallet shows the expected network identity before signing anything:
+2) Confirm you’re on the **right network** (testnet vs mainnet) before signing anything.
+
+If you’re on testnet, your wallet should say “testnet” and show the expected network name.
+
+
+Advanced: exact testnet network identifiers
- `network_id`: `catalyst-testnet`
- `chain_id`: `0xbf8457c` (hex) / `200820092` (decimal)
@@ -20,6 +27,7 @@ title: "Quickstart: I want to use the wallet"
Canonical defaults (for the current testnet wallet implementation):
- `WebWallet/README.md`
+
3) Request testnet funds from the faucet (testnet only):
@@ -31,6 +39,6 @@ Canonical defaults (for the current testnet wallet implementation):
## Troubleshooting
-- If the wallet refuses to sign, it’s often because **chain identity mismatched** (wrong RPC URL / wrong network).
+- If the wallet refuses to sign, it’s often because you’re connected to the **wrong network**.
- Never paste your private key into websites or support chats. See **[Wallets → User guide](/docs/wallets/wallet-user-guide)**.
diff --git a/site/docs/rpc-reference/transaction-lifecycle.md b/site/docs/rpc-reference/transaction-lifecycle.md
index e484c2b..d4e4695 100644
--- a/site/docs/rpc-reference/transaction-lifecycle.md
+++ b/site/docs/rpc-reference/transaction-lifecycle.md
@@ -3,6 +3,12 @@ sidebar_position: 1
title: "RPC: transaction lifecycle"
---
+:::note Not for everyday users
+If you’re just using a wallet or an app, you don’t need this page.
+
+This page is for people building wallets, SDKs, dApps, and tooling that submit transactions directly to Catalyst RPC.
+:::
+
This page is the canonical “how a tx moves through Catalyst” reference:
1) fetch domain
diff --git a/site/docs/sdk/get-started.md b/site/docs/sdk/get-started.md
index 1313cf7..8e4c269 100644
--- a/site/docs/sdk/get-started.md
+++ b/site/docs/sdk/get-started.md
@@ -3,6 +3,11 @@ sidebar_position: 1
title: Get started
---
+This section is for builders (dApps, tooling, wallets). If you’re just using apps, start with:
+
+- **[Use cases (for everyone)](/docs/use-cases/send-money)**
+- **[Quickstart: use Catalyst apps](/docs/quickstarts/i-want-to-use-apps)**
+
## You will need
- Node.js >= 20
@@ -35,6 +40,11 @@ console.log({
Your domain fetch should succeed and `genesisHashLen` should be `32`.
+## Next steps
+
+- **[Deploy a contract](/docs/sdk/deploy-contract)**
+- **[Common pitfalls](/docs/sdk/common-pitfalls)**
+
## Troubleshooting
- **Intermittent signature failures behind a load balancer**: ensure you use `getTxDomain` (single-call domain) rather than fetching chain identity via multiple RPC calls.
diff --git a/site/docs/use-cases/_category_.json b/site/docs/use-cases/_category_.json
new file mode 100644
index 0000000..3e57a64
--- /dev/null
+++ b/site/docs/use-cases/_category_.json
@@ -0,0 +1,10 @@
+{
+ "label": "Use cases (for everyone)",
+ "position": 5,
+ "link": {
+ "type": "generated-index",
+ "title": "What can I do with Catalyst?",
+ "description": "Real-world use cases, explained without jargon. Start here if you just want to use apps."
+ }
+}
+
diff --git a/site/docs/use-cases/games-assets.md b/site/docs/use-cases/games-assets.md
new file mode 100644
index 0000000..ed84bee
--- /dev/null
+++ b/site/docs/use-cases/games-assets.md
@@ -0,0 +1,58 @@
+---
+title: Games and digital items you actually own
+sidebar_position: 2
+---
+
+This page is for everyday users.
+
+## The problem
+
+In many games today:
+
+- your items are trapped inside one game or one company
+- you can lose access if an account is banned or a game shuts down
+- you can’t easily prove an item is “really yours”
+
+## What Catalyst enables
+
+Catalyst can support games where:
+
+- items can be **owned by you**, not just by a game server
+- items can **move between apps** (when the apps choose to support it)
+- ownership can be **verified publicly** (like checking a serial number)
+
+You don’t need to learn the underlying technology to benefit from it—your wallet and game UI can make it feel normal.
+
+## What you do (as a player)
+
+### 1) Get a wallet
+
+- Create an account and back it up.
+- **[Wallet → user guide](/docs/wallets/wallet-user-guide)**
+
+### 2) Play a Catalyst-enabled game
+
+When a game supports Catalyst, it can show:
+
+- your items (in-game)
+- your ownership (in-wallet)
+- transfers (send/trade)
+
+### 3) Verify ownership (optional)
+
+If you ever want to double-check, the explorer can show activity tied to your account.
+
+- **[Explorer → user guide](/docs/explorer/user-guide)**
+
+## What to look for in good apps
+
+- Clear “backup” guidance for your wallet
+- Human-friendly names/contacts (so you don’t paste long strings all day)
+- A simple “activity / receipts” page
+
+## Troubleshooting
+
+### “I can’t see my item in the wallet”
+
+Not all wallets show every kind of in-game item yet. The game might still work fine even if the wallet UI is still catching up.
+
diff --git a/site/docs/use-cases/how-it-works-plain-english.md b/site/docs/use-cases/how-it-works-plain-english.md
new file mode 100644
index 0000000..aee702e
--- /dev/null
+++ b/site/docs/use-cases/how-it-works-plain-english.md
@@ -0,0 +1,66 @@
+---
+title: How it works (plain English)
+sidebar_position: 10
+---
+
+You don’t need to read this to use Catalyst apps, but it can help you feel confident.
+
+## The three things you’ll see
+
+### 1) A wallet
+
+A wallet is an app that:
+
+- creates your account
+- lets you send/receive money
+- keeps your “keys” (the secret needed to approve actions)
+
+**Important:** if you lose your wallet backup, you can lose access.
+
+### 2) Apps
+
+Apps are what you actually use:
+
+- games
+- social apps
+- marketplaces
+- tools
+
+Good apps will make Catalyst “disappear” and just feel like normal software.
+
+### 3) An explorer
+
+An explorer is like a public receipt viewer. You can use it to:
+
+- verify a payment happened
+- verify an app action was recorded
+- troubleshoot when an app UI is slow to update
+
+## What a “transaction” is
+
+A transaction is just a signed request from your wallet, like:
+
+- “send 5 tokens to Alex”
+- “deploy this app feature”
+- “call this contract”
+
+Your wallet signs it so the network can verify it’s really you approving it.
+
+## Testnet vs mainnet
+
+Testnet is for testing:
+
+- funds are free (via a faucet)
+- things can reset or change
+
+Mainnet is real:
+
+- funds are not free
+- you should be more careful with backups and security
+
+## Where to go next
+
+- **[Quickstarts](/docs/quickstarts/i-want-to-use-the-wallet)**
+- **[Faucet → user guide](/docs/faucet/user-guide)**
+- **[Explorer → user guide](/docs/explorer/user-guide)**
+
diff --git a/site/docs/use-cases/send-money.md b/site/docs/use-cases/send-money.md
new file mode 100644
index 0000000..ecc2de9
--- /dev/null
+++ b/site/docs/use-cases/send-money.md
@@ -0,0 +1,86 @@
+---
+title: Send money (without scary addresses)
+sidebar_position: 1
+---
+
+This page is for everyday users. You do **not** need to understand blockchains to use Catalyst.
+
+## What you can do
+
+- **Send money to a person** and verify it arrived
+- **Check activity** in a public explorer (like a receipt)
+- **Avoid common mistakes** (wrong network, copying the wrong text)
+
+## How it feels (high level)
+
+Using Catalyst is like using:
+
+- a **wallet app** (to hold money and sign payments)
+- an **explorer** (to verify what happened)
+- an **app** (the thing you actually care about)
+
+Catalyst is the underlying network that makes those apps work.
+
+## Steps
+
+### 1) Install a wallet and create an account
+
+- Open the wallet.
+- Create a new account.
+- **Back it up** in whatever way the wallet recommends (offline is best).
+
+If you’re using the testnet web wallet, start here:
+
+- **[Wallet → user guide](/docs/wallets/wallet-user-guide)**
+
+### 2) Get some funds (testnet)
+
+If you’re on testnet, you can request free test funds:
+
+- **[Faucet → user guide](/docs/faucet/user-guide)**
+
+### 3) Send money
+
+In the wallet:
+
+- Choose **Send**
+- Paste the recipient’s address (or choose from contacts if the wallet supports it)
+- Choose an amount
+- Confirm and send
+
+### 4) Verify (your receipt)
+
+Open the explorer and search for:
+
+- your address, or
+- the transaction ID (if your wallet shows it)
+
+- **[Explorer → user guide](/docs/explorer/user-guide)**
+
+## Verify
+
+You’re done when:
+
+- the wallet shows the transfer as completed, and
+- the explorer shows the transaction as applied.
+
+## Troubleshooting
+
+### “My balance didn’t change”
+
+Sometimes apps update slowly. The explorer is your source of truth:
+
+- **[Explorer → user guide](/docs/explorer/user-guide)**
+
+### “Wallet says wrong network”
+
+Make sure you’re using the wallet for the right network (testnet vs mainnet). If you’re unsure, stop and ask—this prevents sending to the wrong place.
+
+### Safety reminder
+
+Never paste your private key / recovery phrase into:
+
+- websites
+- screenshots
+- support chats
+
diff --git a/site/docs/use-cases/social-you-control.md b/site/docs/use-cases/social-you-control.md
new file mode 100644
index 0000000..299ef95
--- /dev/null
+++ b/site/docs/use-cases/social-you-control.md
@@ -0,0 +1,47 @@
+---
+title: Social apps you control (not platforms)
+sidebar_position: 3
+---
+
+This page is for everyday users.
+
+## The problem
+
+On most social platforms:
+
+- the platform owns your identity and audience
+- moderation and ranking rules change without you choosing them
+- moving to another app often means starting over
+
+## What Catalyst enables
+
+Catalyst can support social apps where:
+
+- your identity can be **portable** between apps
+- your content and relationships can be **yours**, not locked to one company
+- you can choose apps that match your preferences without losing everything
+
+You shouldn’t need to understand “blockchains” to get these benefits. A good app will feel like a normal social app—just with better portability and user control.
+
+## What you do (as a user)
+
+### 1) Create an account in your wallet
+
+- **[Wallet → user guide](/docs/wallets/wallet-user-guide)**
+
+### 2) Pick a social app
+
+In the future, this docs site will link to an app directory so you can install apps without thinking about the underlying network.
+
+For now: use whichever Catalyst-enabled social app you trust and enjoy.
+
+### 3) Verify activity (optional)
+
+If you ever need an audit trail (for example, “did I post / did I follow / did I pay?”), explorers can provide public verification.
+
+- **[Explorer → user guide](/docs/explorer/user-guide)**
+
+## Safety reminder
+
+If you lose your wallet backup, you can lose access to accounts and assets. Follow your wallet’s backup guidance carefully.
+
diff --git a/site/src/components/HomepageFeatures/index.tsx b/site/src/components/HomepageFeatures/index.tsx
index af8666c..99edb35 100644
--- a/site/src/components/HomepageFeatures/index.tsx
+++ b/site/src/components/HomepageFeatures/index.tsx
@@ -11,6 +11,22 @@ type FeatureItem = {
};
const FeatureList: FeatureItem[] = [
+ {
+ title: 'Use cases (for everyone)',
+ Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+ description: (
+ <>
+ Send money, play games, and use apps where you control your assets and identity—without needing to learn jargon.
+
+ Send money
+ {' · '}
+ Games & assets
+ {' · '}
+ Social
+
+
+ ),
+ },
{
title: 'Node operators',
Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
@@ -28,21 +44,21 @@ const FeatureList: FeatureItem[] = [
Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
description: (
<>
- Build dApps and tooling against the RPC surface and CTX2 signing model.
+ Build dApps and tooling against Catalyst, with a focus on safe defaults and simple deploy flows.
- RPC: tx lifecycle
- {' · '}
SDK get started
+ {' · '}
+ Deploy a contract
),
},
{
- title: 'Wallet + explorer + faucet',
- Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+ title: 'Wallet, explorer, and faucet',
+ Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
description: (
<>
- End-user guides and operator runbooks for ecosystem apps.
+ Guides for using Catalyst tools (and running them if you’re an operator).