Merge pull request #1 from catalyst-network/docs/use-cases-user-first

docs: user-first use cases + simplified entry points

Author: TheNewAutonomy

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)**.

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

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`:
 

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.
+

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,14 +14,20 @@ 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.
+
+<details>
+<summary>Advanced: exact testnet network identifiers</summary>
 
 - `network_id`: `catalyst-testnet`
 - `chain_id`: `0xbf8457c` (hex) / `200820092` (decimal)
 
 Canonical defaults (for the current testnet wallet implementation):
 
 - `WebWallet/README.md`
+</details>
 
 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)**.
 

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  

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.

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."
+  }
+}
+

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.
+

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)**
+