ethersphere · yjkellyjoo · Jul 28, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/CODING.md b/CODING.md
@@ -22,3 +22,21 @@ Note that the Bee client supports running/forming multiple Swarm swarms, i.e. yo
  > when your node joins the designated swarm
 
 [`Bee`](https://github.com/ethersphere/bee), with a capital, refers to a specific bee client, written in the `go` programming language, while `bee`, in lower case, refers to any worker that can join a swarm (e.g. any client implementation that speaks the Swarm protocol).
+
+## Writing for answer engines (AEO/GEO)
+
+These conventions keep pages easy for search and AI answer engines to extract:
+
+- **Answer first**: open each page with a 1–2 sentence direct answer to its implied question (a definition, or the outcome/first step), before context, citations, or marketing.
+  A friendly or on-brand line can follow the factual one.
+
+- **One H1 per page**: the frontmatter `title` renders as the page's H1, so don't add a body `# H1`.
+
+- **Descriptive, question-shaped headings**: phrase a heading as the question a reader would ask (e.g. "What is a full node?", "How do I pin content during upload?"), on concept, reference, and how-to pages alike, rather than generic labels like "Overview" or "Introduction".
+  When you rename an existing heading, pin its original slug with `{#old-slug}` so existing anchor links keep working.
+
+- **Self-contained sentences**: avoid "as mentioned above", "at this point", and bare "this/it/here" — name the entity or section, so a sentence still makes sense when quoted on its own.
+
+- **`description` frontmatter**: write one concise, factual, self-contained sentence stating the page's key fact (not "Guide for…" / "Overview of…"), and make sure any acronym expansion matches the body.
+
+- **Prefer extraction aids**: definition-first paragraphs, lists, tables, and `:::info`/`:::tip` callouts for key facts, rather than long walls of prose.
diff --git a/docs/bee/installation/build-from-source.md b/docs/bee/installation/build-from-source.md
@@ -14,7 +14,7 @@ Prerequisites for installing directly from source are:
 -  **git** - download from [git-scm.com](https://git-scm.com/).
 -  **make** - [make](https://www.gnu.org/software/make/) is usually included by default in most UNIX operating systems, and can be installed and used on almost any other operating system where it is not included by default.
 
-### Build from Source
+## Build steps
 
 1. Clone the repository:
 

diff --git a/docs/bee/installation/docker.md b/docs/bee/installation/docker.md
@@ -4,8 +4,6 @@ id: docker
 description: Provides comprehensive steps for deploying Bee nodes using Docker containers with volume management and network configuration.
 ---
 
-# Docker Install
-
 The following is a guide for installing a Bee node using Docker. Docker images for Bee are hosted at [Docker Hub](https://hub.docker.com/r/ethersphere/bee). Using Docker to operate your Bee node offers many benefits, such as ease of deployment and consistency across environments. 
 
 :::caution

diff --git a/docs/bee/installation/getting-started.md b/docs/bee/installation/getting-started.md
@@ -4,7 +4,11 @@ id: getting-started
 description: Introduces Bee node types their requirements and available installation methods to help users choose appropriate setup approaches.
 ---
 
-*If you want to get a Bee node up and running ASAP, check out the [Quick Start](./quick-start.md) guide.* 
+Running a Bee node means choosing a node type (full, light, or ultra-light), meeting the software, hardware, and network requirements, and picking an installation method. This guide covers each so you can choose the right setup.
+
+:::tip
+If you want to get a Bee node up and running ASAP, check out the [Quick Start](./quick-start.md) guide.
+:::
 
 ## Overview
 

diff --git a/docs/bee/installation/hive.md b/docs/bee/installation/hive.md
@@ -7,21 +7,21 @@ description: Describes tools and orchestration methods for managing multiple Bee
 Due to the mechanics of Swarm's [storage incentives](./../../concepts/incentives/redistribution-game.md), node operators may wish to run multiple nodes in order to maximize earning potential. Read [The Book of Swarm](https://www.ethswarm.org/the-book-of-swarm-2.pdf) for more information on how the
 swarm comes together.
 
-### Docker
+## Docker
 
 Up-to-date [Docker images for Bee](./docker.md) are provided.
 
-### Docker Compose
+## Docker Compose
 
 Running multiple Bee nodes is easier with
 `docker-compose`. Check out the Docker compose section of the
 [Docker README](https://github.com/ethersphere/bee/tree/master/packaging/docker).
 
-### Helm
+## Helm
 
 If you plan to run a large number of Bee nodes and you have experience using Kubernetes with Helm, you can have a look at how we manage our cluster under [Ethersphere/helm](https://github.com/ethersphere/helm/tree/master/charts/bee).
 
-### Manual Setup
+## Manual Setup
 
 If you just want to run a handful of Bee nodes, you can run multiple Bee nodes by creating separate configuration files.
 
@@ -35,6 +35,6 @@ Make as many copies of bee-config-1.yaml as you want to run Bee nodes. Increment
 
 Configure your nodes as desired, but ensure that the values `api-addr`, `data-dir` and `p2p-addr` are unique for each configuration.
 
-### Monitoring
+## Monitoring
 
 See the [logging section](./../working-with-bee/logs-and-files.md) for more information on how to access your node's metrics. Share your community creations (such as [swarmMonitor](https://github.com/doristeo/SwarmMonitoring) - thanks doristeo!) in the [#node-operators](https://discord.gg/kHRyMNpw7t) channel of our Discord server so we can add you to our list of all things that are [awesome](https://github.com/ethersphere/awesome-swarm) and Swarm. 🧡
diff --git a/docs/bee/installation/set-target-neighborhood.md b/docs/bee/installation/set-target-neighborhood.md
@@ -13,14 +13,14 @@ Therefore the default Bee configuration now includes the `neighborhood-suggester
 The Swarmscan neighborhood selector prioritizes the least populated neighborhood. If a neighborhood contains imbalanced sub-neighborhoods, it will suggest the least populated sub-neighborhood instead. Furthermore, the suggester will temporarily de-prioritize previously suggested neighborhoods based on the assumption that a new node is being created in each suggested neighborhood so that multiple nodes do not simultaneously attempt to join the same neighborhood.
 :::
 
-#### Setting Neighborhood Manually
+## Setting Neighborhood Manually
 
 It's recommended to use the default `neighborhood-suggester` configuration for choosing your node's neighborhood, however you may also set your node's neighborhood manually using the `target-neighborhood` option.
 
 To use this option, it's first necessary to identify potential target neighborhoods. You can find underpopulated neighborhoods using the [Swarmscan website](https://swarmscan.io/neighborhoods). It ranks neighborhoods from least to most populated and displays their leading binary bits. Simply copy the leading bits from one of the least populated neighborhoods (for example, `0010100001`) and use it to set `target-neighborhood`. After doing so, an overlay address within that neighborhood will be generated when starting Bee for the first time.
 
 ```yaml
-## bee.yaml
+# bee.yaml
 target-neighborhood: "0010100001"
 ```
 

diff --git a/docs/bee/installation/shell-script.md b/docs/bee/installation/shell-script.md
@@ -7,8 +7,6 @@ description: Provides flexible installation using an automated shell script supp
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Swarm Shell Script Installation Guide
-
 The official [shell script](https://github.com/ethersphere/bee/blob/master/install.sh) provided by Swarm automatically detects your system and installs the correct version of Bee. This installation method is an excellent choice if you're looking for a minimalistic and flexible option for your Bee node installation.
 
 :::warning

diff --git a/docs/bee/working-with-bee/configuration.md b/docs/bee/working-with-bee/configuration.md
@@ -586,7 +586,7 @@ Full and light Bee nodes require a Gnosis Chain RPC endpoint in order to sync bl
 To set your RPC endpoint, specify it with the `blockchain-rpc-endpoint` value, which is set to an empty string by default.
 
 ```yaml
-## bee.yaml
+# bee.yaml
 blockchain-rpc-endpoint: https://xdai.fairdatasociety.org
 ```
 
@@ -606,7 +606,7 @@ Bee periodically reads the current block number from your blockchain RPC endpoin
 The `block-sync-interval` option controls how frequently the real block number is refreshed:
 
 ```yaml
-## bee.yaml
+# bee.yaml
 block-sync-interval: 10
 ```
 
@@ -629,7 +629,7 @@ It is currently available **only on Linux x86-64 (amd64)**; on all other platfor
 To enable it, set the `use-simd-hashing` option:
 
 ```yaml
-## bee.yaml
+# bee.yaml
 use-simd-hashing: true
 ```
 
@@ -648,7 +648,7 @@ This feature is **disabled by default** and only applies to full nodes with cheq
 To enable chequebook verification, set `chequebook-verification` to `true`:
 
 ```yaml
-## bee.yaml
+# bee.yaml
 chequebook-verification: true
 ```
 
@@ -657,7 +657,7 @@ The value is set in the token's smallest unit (PLUR), where 1 BZZ = 10^16 PLUR,
 To configure a different threshold, set `chequebook-min-balance` accordingly:
 
 ```yaml
-## bee.yaml
+# bee.yaml
 chequebook-verification: true
 chequebook-min-balance: "110000000000000000" # 11 BZZ, expressed in PLUR
 ```
@@ -694,7 +694,7 @@ curl icanhazip.com
 Then configure your node, including your p2p port (default 1634).
 
 ```yaml
-## bee.yaml
+# bee.yaml
 nat-addr: "123.123.123.123:1634"
 ```
 
@@ -707,7 +707,7 @@ The [ENS](https://ens.domains/) domain resolution system is used to host website
 If you do not wish to run your own Ethereum node, you may use a blockchain RPC service provider such as [Infura](https://infura.io). After signing up for Infura, simply set your `--resolver-options` to `https://mainnet.infura.io/v3/your-api-key`.
 
 ```yaml
-## bee.yaml
+# bee.yaml
 resolver-options: ["https://mainnet.infura.io/v3/<<your-api-key>>"]
 ```
 

diff --git a/docs/bee/working-with-bee/logs-and-files.md b/docs/bee/working-with-bee/logs-and-files.md
@@ -4,8 +4,6 @@ id: logs-and-files
 description: Guides log access rotation verbosity levels and structured logging integration with monitoring tools like Prometheus and Grafana.
 ---
 
-# Logging in Bee
-
 This section provides an overview of logging in Bee, including log locations, exporting logs, managing verbosity levels, and using fine-grained control for specific loggers.
 
 :::info

diff --git a/docs/bee/working-with-bee/monitoring.md b/docs/bee/working-with-bee/monitoring.md
@@ -4,7 +4,7 @@ id: monitoring
 description: Explains how to monitor Bee node metrics using Prometheus and Grafana for tracking cheque rates and network performance.
 ---
 
-Your Bee node is equipped with tools to help you understand what your Bee has been up to!
+Bee nodes expose runtime metrics in Prometheus format, which you can collect and visualise with Grafana to understand what your Bee has been up to.
 
 Navigate to `http://localhost:1633/metrics`.
 

diff --git a/docs/bee/working-with-bee/node-types.md b/docs/bee/working-with-bee/node-types.md
@@ -13,7 +13,7 @@ Bee nodes can operate in three different modes depending on the user's needs, ra
 Choosing the right node type depends on your goals, whether it's participating in the Swarm network as a storage provider, developing applications that use Swarm's decentralized storage and messaging, or simply exploring the technology with minimal setup.
 
 
-## Node Types Overview
+## What are the Bee node types? {#node-types-overview}
 
 Bee can operate in different modes, each tailored to specific use cases:
 
@@ -28,14 +28,14 @@ Bee can operate in different modes, each tailored to specific use cases:
 | [PSS messaging](./../../develop/tools-and-features/pss.md)                   | ✅        | ❌         | ❌               |
 
 
-## Full Node
+## What is a full node? {#full-node}
 
 Full nodes are the most feature-rich nodes in the Swarm network. They provide full upload and download capabilities, store and serve data, and participate in storage and bandwidth incentives. Running a full node requires more system resources, but it allows users to fully engage with and support the network.
 
 Full nodes are ideal for users who want to contribute to the Swarm network and earn incentives, as well as developers who require access to all Bee features including messaging features such as PSS and GSOC.
 
 
-### Recommended Specifications
+### Full node specifications
 
 :::warning
 Full nodes require significant system resources, including storage and bandwidth. Additionally, they must be connected to the blockchain to participate in incentives. 
@@ -50,7 +50,7 @@ Requires significant storage and processing power compared to other node types:
 - **Storage**: 30 GB SSD (HDD not recommended).
 - **Internet**: High-speed and stable connection.
 
-### Configuration
+### Full node configuration
 
 To run Bee as a full node, set:
 
@@ -69,7 +69,7 @@ To run Bee as a full node, set:
 - Supports full PSS messaging and GSOC.
 
 
-## Light Node
+## What is a light node? {#light-node}
 
 Light nodes provide a balance between functionality and resource efficiency. They can upload and download data but do not participate in chunk forwarding or storage for other nodes.
 
@@ -81,11 +81,11 @@ Light node operators cannot earn xBZZ by participating in Swarm's incentives sys
 Light nodes do not benefit from plausible deniability when requesting data from the network. They are always the originator of requests.
 :::
 
-### Recommended Specifications
+### Light node specifications
 
 No specific hardware is required to run a light node. It can run well on practically any commercially available computer released in recent years, including lightweight single-board computers such as [Raspberry Pi](https://en.wikipedia.org/wiki/Raspberry_Pi). Your downloads / uploads may be limited by your network speed, however, so if you plan on interacting extensively with the Swarm network, you should take your connection speed into consideration.
 
-### Configuration
+### Light node configuration
 
 To run Bee as a light node, set:
 
@@ -109,7 +109,7 @@ To run Bee as a light node, set:
 - Can send outgoing GSOC updates but ***cannot*** receive them.
 
 
-## Ultra-Light Node
+## What is an ultra-light node? {#ultra-light-node}
 
 Ultra-light nodes allow users to run a node without requiring a blockchain RPC endpoint. These nodes can download data within the free consumption threshold set by full nodes (this threshold may vary since it is [configurable](./configuration.md) by full node operators using the `payment-tolerance-percent` and `payment-threshold` options).
 
@@ -123,11 +123,11 @@ As with light nodes, ultra-light nodes do not benefit from plausible deniability
 When running without a blockchain connection, [bandwidth incentive payments (SWAP)](./../../concepts/incentives/bandwidth-incentives.md) cannot be made, increasing the risk of being blocklisted by other peers for exceeding their free-tier download limits.
 :::
 
-### Recommended Specifications
+### Ultra-light node specifications
 
 As with the light node, there are no specific requirements to run an ultra-light node, and it will run on practically any commercially available hardware from recent years.   
 
-### Configuration
+### Ultra-light node configuration
 
 Bee will start in ultra-light mode by default, but in order to explicitly configure your node to run as an ultra-light node, use the following options:
 

diff --git a/docs/bee/working-with-bee/staking.md b/docs/bee/working-with-bee/staking.md
@@ -4,6 +4,8 @@ id: staking
 description: Walkthrough of depositing xBZZ to participate in the storage incentives redistribution game and earn network rewards.
 ---
 
+Staking locks up xBZZ so your full node can join the **redistribution game** and earn a share of the network's storage-rent rewards. Staking requires a fully synced full node and a minimum of 10 xBZZ, and the stake is non-refundable.
+
 ## Quickstart Guide
 
 This guide will walk you through **staking xBZZ** and participating in the **redistribution game** to earn storage incentives. 
@@ -123,7 +125,7 @@ Only stake your xBZZ if you intend to participate as a full node, as withdrawals
 
 ### Requirements
 
-- A [full node](./node-types.md) - see full node [recommend specs](./node-types.md#recommended-specifications).  
+- A [full node](./node-types.md) - see full node [recommend specs](./node-types.md#full-node-specifications).  
 - A [high-performance RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint) connection to Gnosis Chain.
 - A minimum of 10 xBZZ to be used as ***non-refundable*** stake (the requirement is increased if [reserve doubling](./staking.md#reserve-doubling) is used).
 
@@ -404,7 +406,7 @@ Copy the binary number returned from the API:
 Use the binary number you just copied and set it as a string value for the `target-neighborhood` option in your config. 
 
 ```bash
-## bee.yaml
+# bee.yaml
 target-neighborhood: "01100011110"
 ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,8 +4,6 @@ id: logs-and-files @@
     description: Guides log access rotation verbosity levels and structured logging integration with monitoring tools like Prometheus and Grafana.
     ---
-    # Logging in Bee
     This section provides an overview of logging in Bee, including log locations, exporting logs, managing verbosity levels, and using fine-grained control for specific loggers.
     :::info
@@ Expand Down @@