Align developer guide series into a progressive, bee-js-focused path

docs/develop/files.md

@@ -5,11 +5,11 @@ sidebar_label: Manage Files
 description: Guide for working with file operations including chunking and handling in Swarm applications.
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
 
 # Manage Files
 
+In the [Host a Webpage](/docs/develop/host-your-website) guide you uploaded a directory and got back a single Swarm reference that serves your site. That reference points to a **manifest** — a data structure that maps relative paths to content. This guide explores manifests directly: how to inspect them, add a file without re-uploading everything, and move a file by remapping a path.
+
 Swarm does not have a traditional filesystem — there are no mutable directories, in-place updates, or a built-in directory structure that preserves relationships between files. Instead, these capabilities are provided through the use of [manifests](./tools-and-features/manifests.md), which map relative paths (such as `/images/cat.jpg`) to immutable Swarm content references. When you upload a directory, Bee creates a manifest automatically and returns its reference. Files can then be accessed using paths that are relative to that manifest reference, based on the original directory structure. This provides filesystem-like behavior for your data, and the directory structure can later be changed by publishing a new version of the manifest with the desired updates.
 
 ## Usage and Example Scripts
@@ -41,14 +41,18 @@ cd examples/filesystem
 npm install
 ```
 
-Update the `<BATCH_ID>` in the `.env` file with a valid batch ID, and make sure that `BEE_URL` is set to the RPC endpoint for your Bee node:
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
 
 ```bash
 BEE_URL=http://localhost:1633 # or http://127.0.0.1:1633  
-BATCH_ID=<BATCH_ID>
+BATCH_ID=<YOUR_BATCH_ID>
 UPLOAD_DIR=./folder
-SCRIPT_02_MANIFEST=<MANIFEST_REFERENCE>
-SCRIPT_03_MANIFEST=<MANIFEST_REFERENCE>
+SCRIPT_02_MANIFEST=
+SCRIPT_03_MANIFEST=
 ```
 
 ## Script 1: Upload Folder and Inspect Manifest
@@ -437,3 +441,6 @@ No data is duplicated, the `new.txt` file has not been modified, only the path m
 
 With these tools, you can treat Swarm directories much like a filesystem — while still preserving immutability and content addressing.
 
+---
+
+**Next:** [Website Routing](/docs/develop/routing) — put manifest path mapping to practical use by setting up clean URL routing for a Swarm-hosted site.

docs/develop/gateway.md

@@ -4,7 +4,9 @@ id: gateway-proxy
 description: Explains Bee gateway functionality for accessing Swarm content through HTTP interfaces.
 ---
 
-This guide explains how to use the [swarm-gateway](https://github.com/ethersphere/swarm-gateway) tool to set up your node in gateway mode. Running your node in gateway mode exposes it publicly, allowing access through any typical browser or http API. 
+At this point you can build and deploy complete Swarm-hosted websites with working routing. This guide is an **operational step**: it shows how to make those sites accessible to the public web through an HTTP gateway, so that anyone with a browser can reach them without running their own Bee node.
+
+This guide explains how to use the [swarm-gateway](https://github.com/ethersphere/swarm-gateway) tool to set up your node in gateway mode. Running your node in gateway mode exposes it publicly, allowing access through any typical browser or http API.
 
 It is divided into several parts:
 
@@ -65,14 +67,12 @@ This part of the guide does not cover setting up TLS, so your gateway will be ac
 
 ### 1. Configure DNS for your domain
 
-Create an A record in your DNS provider:
+Create an A record in your DNS provider pointing your domain to your server's IP address:
 
 ```text
 your-domain.example -> <your-server-ip>
 ```
 
-ADD SCREENSHOT 
-
 After DNS propagation, verify that the domain resolves to your server (this may take some time, to verify more quickly, try pinging from a different machine or VPS):
 
 ```bash
@@ -101,7 +101,7 @@ The output should list `bee-1` as an attached container.
 ### 3. Pull the gateway image
 
 ```bash
-docker pull ethersphere/swarm-gateway:0.1.3
+docker pull ethersphere/swarm-gateway:0.1.6
 ```
 
 ### 4. Run the gateway
@@ -116,7 +116,7 @@ docker run -d --restart unless-stopped \
   -e HOSTNAME="your-domain.example" \
   -e BEE_API_URL="http://bee-1:1633" \
   -e DATABASE_CONFIG="{}" \
-  ethersphere/swarm-gateway:0.1.3
+  ethersphere/swarm-gateway:0.1.6
 ```
 
 In this configuration, database-backed features such as subdomain rewrites and moderation are not configured.
@@ -135,24 +135,25 @@ Expected output:
 OK
 ```
 
-### 6. Test with uploaded content
+### 6. Test with existing content
 
-Upload a file using Bee:
+To confirm the gateway is correctly serving content from Swarm, request a reference that is already on the network. The following hash points to a small JSON file:
 
-```bash
-echo "hello swarm" > test.txt
-swarm-cli upload test.txt
+```text
+http://your-domain.example/bzz/f3f5e25c90824876c2468b9bdf0d842cd05dc5f0974681789b9729bc155c4f65/
 ```
 
-This will print a Swarm reference.
-
-Open the file through the gateway:
+Expected output:
 
-```text
-http://your-domain.example/bzz/<REFERENCE>/
+```json
+{
+  "octalmage.com": "bzz://45f0f1e13b70e2919e59fdc5bcf3a99bcbe19dc1be6ebdebe3f89794b77c19ab/",
+  "o8.is": "bzz://4cd43b1c0ebc257f79cc45ebd9774e1251e34f08026325c78ef2ca46972935cc/",
+  "dist.o8.is": "bzz://0890110b61109aee2b6f0d071cedce584868bb29dcb7e41b1c0388d6cf775ace/"
+}
 ```
 
-The file contents should be returned.
+If the JSON is returned, your gateway is correctly fetching and serving content from Swarm. To serve your own content, upload a file or website through your Bee node (see the [Upload and Download](/docs/develop/upload-and-download) and [Host a Webpage](/docs/develop/host-your-website) guides) and use the resulting reference in place of the one above.
 
 ### 7. Optional: restrict uploads using authentication
 
@@ -228,7 +229,7 @@ docker run -d --restart unless-stopped \
   -e HOSTNAME="your-domain.example" \
   -e BEE_API_URL="http://bee-1:1633" \
   -e DATABASE_CONFIG="{}" \
-  ethersphere/swarm-gateway:0.1.3
+  ethersphere/swarm-gateway:0.1.6
 ```
 
 The gateway is now only accessible from within the Docker network.
@@ -300,3 +301,6 @@ You can also verify that HTTP is redirected to HTTPS:
 curl -I http://your-domain.example/health
 ```
 
+---
+
+**Next:** [Dynamic Content](/docs/develop/dynamic-content) — return to app development and learn how feeds add a mutable pointer layer on top of Swarm's immutable storage.