GenesisL1 · Colonel-Courtz · May 18, 2026
diff --git a/README.md b/README.md
@@ -24,8 +24,10 @@
 
 Due to the recent on-chain minting of the full Protein Data Bank (PDB), the size of the GenesisL1 blockchain has increased significantly. This data-heavy event resulted in a substantial boost to storage requirements and syncing time. To address this, the GenesisL1 community provides multiple streamlined methods to get a node up and running quickly — including a bootstrapped `data` folder backup that allows syncing within hours instead of several days.
 
+Long-form operational docs now start in [`docs/README.md`](docs/README.md). New operators who want a docs-first flow can use the [`node operator guide`](docs/node-operator-guide.md) for setup-path selection, host preparation, bootstrap, upgrade, service, and validator handoff notes.
+
 > ⚠️ **IMPORTANT:**
-> In **Step 2**, you will need to choone **one setup methods**: Option A or B.
+> In **Step 2**, you will need to choose **one setup method**: Option A or B.
 
 This repository is intended for those who want to join the Cronos-fork **mainnet**: `genesis_29-2`, using one of the following paths:
 
@@ -410,7 +412,7 @@ genesisd tx staking create-validator \
 ## 7. Explore utilities
 
 > [!TIP]
-> The [/utils](/utils)-folder contains useful utilities one could use to manage their node (e.g. for fetching latest seeds and peers, fetching the genesis state, quickly shifting your config's ports, recalibrating your state sync etc.). To learn more about these, see the [README](utils/README.md) in the folder.
+> The [`utils`](utils/README.md) folder contains useful utilities one could use to manage their node (e.g. for fetching latest seeds and peers, fetching the genesis state, quickly shifting your config's ports, recalibrating your state sync etc.). To learn more about these, see the [README](utils/README.md) in the folder.
 
 ---
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,31 @@
+# GenesisL1 documentation
+
+This directory is the starting point for GenesisL1 operator and developer documentation. It keeps long-form operational guidance out of the repository root while leaving the root `README.md` as a short project overview and quick-start pointer.
+
+## Operator docs
+
+- [Node operator guide](node-operator-guide.md) — choose a setup path, prepare a host, bootstrap or upgrade a node, run the daemon, and move into validator operations.
+- [Setup script reference](../setup/README.md) — details for the helper scripts under `setup/`.
+- [VersionDB guide](../versiondb/README.md) — archive and non-validator node storage guidance.
+
+## Protocol and API docs
+
+- [Architecture decisions](architecture/README.md)
+- [Proto API reference](api/proto-docs.md)
+- JSON-RPC: [server](api/json-rpc/server.md), [endpoints](api/json-rpc/endpoints.md), [namespaces](api/json-rpc/namespaces.md), [events](api/json-rpc/events.md)
+
+## Bridge docs
+
+- [Gravity bridge development setup](gravity-bridge/dev-setup-guide.md)
+- [Relayer modes](gravity-bridge/gravity-bridge-relayer-modes.md)
+- [GORC build guide](gravity-bridge/gorc-build.md)
+- [GORC keystore guide](gravity-bridge/gorc-keystores.md)
+
+## Maintenance notes
+
+When adding or changing docs:
+
+1. Keep the root `README.md` focused on project identity and the shortest viable onboarding path.
+2. Put step-by-step operational details in this directory or in `setup/README.md`.
+3. Link to release-specific setup scripts instead of duplicating values that change per network upgrade.
+4. Call out destructive actions, such as replacing `~/.genesis/data`, before the command block that performs them.
diff --git a/docs/node-operator-guide.md b/docs/node-operator-guide.md
@@ -0,0 +1,138 @@
+# GenesisL1 node operator guide
+
+This guide is a docs-first companion to the root `README.md`. It gives operators one page to choose a path, prepare a host, and find the right setup script without mixing those details into the repository overview.
+
+## 1. Choose the correct setup path
+
+GenesisL1 mainnet currently uses chain ID `genesis_29-2`. Before running commands, decide which path matches your node:
+
+| Path | Use it when | Primary script or command |
+| --- | --- | --- |
+| Bootstrapped snapshot | You are starting a new full node and want the fastest sync path. | `setup/quick-sync.sh` plus a trusted community snapshot. |
+| Existing node upgrade | Your node has halted at a planned upgrade height or you are upgrading a legacy node. | `setup/upgrade.sh` from the release you are upgrading to. |
+| Staged upgrade | You want to build the next binary before the chain reaches the upgrade height. | `setup/staged-upgrade.sh`. |
+| Validator creation | Your node is fully synced and you have a funded local key. | `setup/create-validator.sh`. |
+
+> [!IMPORTANT]
+> Use the setup scripts from the same release tag or commit that matches the upgrade you are applying. Upgrade scripts are release-dependent.
+
+## 2. Prepare the host
+
+Recommended baseline:
+
+- Debian-based Linux host.
+- 1000GB+ NVMe storage for a full node.
+- 8GB RAM minimum; 16GB+ recommended.
+- 4 physical CPU cores or better.
+- Stable network connectivity above 100Mbit/s.
+
+Install common dependencies:
+
+```bash
+sudo apt update && sudo apt upgrade -y
+sudo apt install curl tar wget build-essential git make gcc liblz4-tool htop unzip jq ca-certificates rsync lz4 pv -y
+```
+
+Optional swap for small hosts:
+
+```bash
+sudo fallocate -l 8G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+```
+
+Persisting swap is host-specific; back up `/etc/fstab` before editing it.
+
+## 3. Bootstrap a new full node from a snapshot
+
+A snapshot is the fastest path, but it relies on the snapshot provider. Verify the source before use.
+
+1. Clone the repository and check out the release you intend to run:
+
+   ```bash
+   git clone https://github.com/GenesisL1/genesis-crypto.git
+   cd genesis-crypto
+   git checkout v1.1.1
+   ```
+
+2. Create the base home directory and configuration:
+
+   ```bash
+   sh setup/quick-sync.sh <moniker>
+   ```
+
+3. Stop `genesisd` if it is running, then replace only the data directory with the downloaded snapshot:
+
+   ```bash
+   rm -r ~/.genesis/data
+   lz4 -d data.tar.lz4 | tar -xvf - -C "$HOME/.genesis"
+   ```
+
+4. Start the daemon and watch logs:
+
+   ```bash
+   genesisd start --log_level warn
+   ```
+
+## 4. Upgrade an existing node
+
+Use this path when the node has halted at a planned upgrade height or you are moving a legacy node forward.
+
+1. Confirm the plan name, halt height, and target version in the root `README.md` or the release notes.
+2. Check out the matching release:
+
+   ```bash
+   cd ~/genesis-crypto
+   git checkout <version-to-upgrade-to>
+   ```
+
+3. Run the release-specific upgrade script:
+
+   ```bash
+   sh setup/upgrade.sh
+   ```
+
+4. Restart and monitor:
+
+   ```bash
+   sudo systemctl start genesisd
+   journalctl -fu genesisd -ocat
+   ```
+
+For upgrades that should be built ahead of the halt height, see the staged upgrade flow in [`setup/README.md`](../setup/README.md#staged-upgradesh).
+
+## 5. Run as a systemd service
+
+The root `README.md` includes a minimal service example. Before enabling a service, confirm that `genesisd start --log_level warn` works interactively.
+
+Typical service workflow:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable genesisd
+sudo systemctl start genesisd
+journalctl -fu genesisd -ocat
+```
+
+## 6. Validator handoff checklist
+
+Only create a validator after the node is fully synced.
+
+- `genesisd status` reports the node is caught up.
+- The local key exists or has been imported.
+- The wallet has enough funds for the validator transaction.
+- The operator understands the commission, moniker, website, and security-contact values being submitted on-chain.
+
+Use the helper script when ready:
+
+```bash
+sh setup/create-validator.sh <moniker> <walletname>
+```
+
+## 7. Related references
+
+- [`setup/README.md`](../setup/README.md) for script-level behavior.
+- [`../README.md`](../README.md) for the project overview and current network values.
+- [`../utils/README.md`](../utils/README.md) for node utility scripts.
+- [`versiondb/README.md`](../versiondb/README.md) for archive and non-validator storage options.