ethersphere · EchinopsisM · May 27, 2026 · May 25, 2026 · May 26, 2026 · May 26, 2026
diff --git a/dynamic-content/.env.example b/dynamic-content/.env.example
@@ -0,0 +1,2 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
diff --git a/dynamic-content/README.md b/dynamic-content/README.md
@@ -0,0 +1,33 @@
+# Dynamic Content (Feeds)
+
+Companion code for the [**Dynamic Content**](https://docs.ethswarm.org/docs/develop/dynamic-content) guide. Demonstrates feeds — Swarm's mutable-pointer layer on top of immutable storage — through three small scripts.
+
+For the complete blog project that puts these concepts together, see the [`simple-blog/`](../simple-blog) example.
+
+## What it does
+
+- `script-01.js` — the immutability problem: uploading the same content twice with a small change produces different hashes
+- `script-02.js` — write a Swarm reference to a feed, read it back, then update the feed with new content
+- `script-03.js` — wrap a feed in a feed manifest to get a stable URL that always resolves to the latest entry
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL and BATCH_ID in .env
+```
+
+## Run
+
+```bash
+npm run script:01
+npm run script:02
+npm run script:03
+```
+
+## Requirements
+
+- A running Bee node (default: `http://localhost:1633`)
+- A funded **immutable** postage stamp batch (feeds break on mutable batches when they fill up)
+- Node.js 18+
diff --git a/dynamic-content/package.json b/dynamic-content/package.json
@@ -3,6 +3,11 @@
   "version": "1.0.0",
   "description": "Example scripts for the Dynamic Content guide — demonstrates immutability, feeds, and feed manifests.",
   "type": "module",
+  "scripts": {
+    "script:01": "node script-01.js",
+    "script:02": "node script-02.js",
+    "script:03": "node script-03.js"
+  },
   "dependencies": {
     "@ethersphere/bee-js": "^9.1.1",
     "dotenv": "^16.4.7"

diff --git a/filesystem/.env.example b/filesystem/.env.example
@@ -0,0 +1,5 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
+UPLOAD_DIR=./folder
+SCRIPT_02_MANIFEST=
+SCRIPT_03_MANIFEST=
diff --git a/filesystem/.gitignore b/filesystem/.gitignore
@@ -1 +1,2 @@
 node_modules
+.env
diff --git a/filesystem/README.md b/filesystem/README.md
@@ -0,0 +1,35 @@
+# Filesystem (Manage Files)
+
+Companion code for the [**Manage Files**](https://docs.ethswarm.org/docs/develop/files) guide. Demonstrates how manifests provide filesystem-like behavior on Swarm — inspecting a manifest, adding a file without re-uploading, and moving a file by remapping a path.
+
+## What it does
+
+- `script-01.js` — uploads `./folder/` and prints the resulting manifest tree
+- `script-02.js` — adds a new file (`new.txt`) to the existing manifest without re-uploading the directory
+- `script-03.js` — moves `new.txt` from the root to `nested/deeper/new.txt` by editing the manifest
+
+Each script prints a new manifest reference. You'll feed the reference from each step into the next via the `SCRIPT_*_MANIFEST` env vars.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL, BATCH_ID, and UPLOAD_DIR in .env
+```
+
+## Run
+
+```bash
+node script-01.js
+# Copy the printed manifest reference into SCRIPT_02_MANIFEST in .env
+node script-02.js
+# Copy the new manifest reference into SCRIPT_03_MANIFEST in .env
+node script-03.js
+```
+
+## Requirements
+
+- A running Bee node (default: `http://localhost:1633`)
+- A funded postage stamp batch
+- Node.js 18+
diff --git a/multi-author-blog/.env.example b/multi-author-blog/.env.example
@@ -0,0 +1,2 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
diff --git a/multi-author-blog/.gitignore b/multi-author-blog/.gitignore
@@ -1,4 +1,5 @@
 node_modules/
+.env
 config.json
 alice-posts.json
 bob-posts.json

diff --git a/multi-author-blog/README.md b/multi-author-blog/README.md
@@ -0,0 +1,38 @@
+# Multi-Author Blog
+
+Companion code for the [**Multi-Author Blog**](https://docs.ethswarm.org/docs/develop/multi-author-blog) guide. Extends the [simple-blog](../simple-blog) pattern into a multi-author system: each author independently controls their own feed, and an admin maintains a master index feed that links them all together — feeds referencing other feeds.
+
+## What it does
+
+- `init.js` — one-time setup: generates keys for admin + initial authors, creates per-author feeds and a master index feed
+- `add-post.js <author> "<title>" "<body>"` — author publishes a new post to their feed
+- `update-index.js` — admin reads all author feeds, aggregates them into a homepage, and publishes the homepage feed
+- `add-author.js <name>` — admin adds a new author (new key, new per-author feed, appended to the index)
+- `read.js` — reads the index and every author's latest post without needing private keys
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL and BATCH_ID in .env
+```
+
+## Run (full flow)
+
+```bash
+npm run init
+npm run add-post -- alice "Hello from Alice" "Alice's first post."
+npm run add-post -- bob "Hello from Bob" "Bob's first post."
+npm run update-index
+npm run read
+npm run add-author -- charlie
+```
+
+`init.js` writes keys, manifest hashes, and per-author post lists to local JSON files.
+
+## Requirements
+
+- A running Bee node (default: `http://localhost:1633`)
+- A funded **immutable** postage stamp batch
+- Node.js 18+
diff --git a/multi-author-blog/package.json b/multi-author-blog/package.json
@@ -3,6 +3,13 @@
   "version": "1.0.0",
   "description": "Example scripts for the Multi-Author Blog guide — demonstrates composable feeds where each author publishes independently and an admin aggregates posts into a homepage.",
   "type": "module",
+  "scripts": {
+    "init": "node init.js",
+    "add-post": "node add-post.js",
+    "update-index": "node update-index.js",
+    "add-author": "node add-author.js",
+    "read": "node read.js"
+  },
   "dependencies": {
     "@ethersphere/bee-js": "^9.1.1",
     "dotenv": "^16.4.7"

diff --git a/routing-manifest/.env.example b/routing-manifest/.env.example
@@ -0,0 +1,4 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
+UPLOAD_DIR=./site
+BASE_MANIFEST=
diff --git a/routing-manifest/.gitignore b/routing-manifest/.gitignore
@@ -1 +1,2 @@
-node_modules
+node_modules
+.env
diff --git a/routing-manifest/README.md b/routing-manifest/README.md
@@ -1,25 +1,39 @@
-# Swarm Routing Demo (Strategy A)
+# Routing (Manifest-Based)
 
-This is a minimal static website intended for **Manifest-Based Routing** with **Strategy A (aliases)**.
+Companion code for the [**Website Routing**](https://docs.ethswarm.org/docs/develop/routing#manifest-based-routing) guide's manifest-based routing section. Adds clean URLs (e.g. `/about` resolving to `/about.html`) by editing the manifest directly — no React, no client-side router.
 
-## What it includes
-- `index.html`, `about.html`, `contact.html`
-- `404.html` (for `errorDocument`)
-- `new-page.html` (for "redirect-like" remapping)
-- `assets/` (CSS + a tiny nav helper)
+For the hash-routing approach using `HashRouter` in a React SPA, see [`routing/`](../routing).
 
-## How it maps to your guide
-Upload the `site/` folder with:
+## What it does
 
-```ts
-const { reference } = await bee.uploadFilesFromDirectory(batchId, "./site", {
-  indexDocument: "index.html",
-  errorDocument: "404.html"
-});
+- `upload.js` — uploads `./site/` with `indexDocument: index.html` and `errorDocument: 404.html`
+- `updateManifest.js` — adds manifest forks so `/about` and `/about/` resolve to the same content as `/about.html`
+- `removeAndAddRoutes.js` — removes the old `/about*` routes and adds `/moved-about` aliases (demonstrates that routes are mutable through manifest edits)
+
+Each script prints a new manifest reference. Set `BASE_MANIFEST` in `.env` to the reference from the previous step before running the next.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL and BATCH_ID in .env
 ```
 
-Then, in your manifest manipulation step, add aliases like:
-- `about` and `about/` → the same entry as `about.html`
-- `contact` and `contact/` → the same entry as `contact.html`
+## Run
+
+```bash
+node upload.js
+# Copy the printed manifest reference into BASE_MANIFEST in .env
+node updateManifest.js
+# Copy the new reference into BASE_MANIFEST
+node removeAndAddRoutes.js
+```
+
+Verify by opening `http://localhost:1633/bzz/<REFERENCE>/about` in your browser at each step.
+
+## Requirements
 
-This allows clean URLs without changing the file structure.
+- A running Bee node (default: `http://localhost:1633`)
+- A funded postage stamp batch
+- Node.js 18+
diff --git a/routing/.env.example b/routing/.env.example
@@ -0,0 +1,3 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
+UPLOAD_DIR=./dist
diff --git a/routing/.gitignore b/routing/.gitignore
@@ -1,2 +1,3 @@
 node_modules
-dist
+dist
+.env
diff --git a/routing/README.md b/routing/README.md
@@ -0,0 +1,34 @@
+# Routing (Hash-Based Client-Side)
+
+Companion code for the [**Website Routing**](https://docs.ethswarm.org/docs/develop/routing) guide. A minimal Vite + React app using `HashRouter` to give a Swarm-hosted site clean, hash-based URLs (e.g. `/#/about`) that work without any server-side routing.
+
+For the manifest-based routing approach (no React, server-side-style URLs via manifest edits), see the [`routing-manifest/`](../routing-manifest) example.
+
+## What it does
+
+- Builds a small SPA with Home, About, and NotFound pages
+- Builds to `./dist/` via Vite
+- `upload.js` uploads `./dist/` to Swarm and publishes the result as a feed entry (stable URL across re-uploads)
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL, BATCH_ID, and PUBLISHER_KEY in .env
+```
+
+## Build and upload
+
+```bash
+npm run build       # Vite build into ./dist
+npm run upload      # Upload ./dist to Swarm and publish to a feed
+```
+
+The upload prints two hashes: the website reference and a feed manifest. Open the feed manifest URL (`http://localhost:1633/bzz/<FEED_MANIFEST>/`) in a browser. `/#/about` should resolve to the About page.
+
+## Requirements
+
+- A running Bee node (default: `http://localhost:1633`)
+- A funded postage stamp batch
+- Node.js 18+
diff --git a/routing/package-lock.json b/routing/package-lock.json
diff --git a/routing/package.json b/routing/package.json
@@ -1,13 +1,16 @@
 {
     "name": "swarm-routing",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "vite",
         "build": "vite build --base=./",
-        "check": "tsc --noEmit"
+        "check": "tsc --noEmit",
+        "upload": "node upload.js"
     },
     "license": "ISC",
     "dependencies": {
+        "dotenv": "^16.4.7",
         "@ethersphere/bee-js": "^9.8.1",
         "react": "^19.1.1",
         "react-dom": "^19.1.1",

diff --git a/routing/upload.js b/routing/upload.js
@@ -1,3 +1,6 @@
+import dotenv from "dotenv";
+dotenv.config();
+
 import { uploadToSwarm } from "../utils/upload-site.js";
 
 uploadToSwarm();
diff --git a/simple-blog/.env.example b/simple-blog/.env.example
@@ -0,0 +1,2 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
diff --git a/simple-blog/README.md b/simple-blog/README.md
@@ -0,0 +1,37 @@
+# Simple Blog
+
+Companion code for the [**Dynamic Content**](https://docs.ethswarm.org/docs/develop/dynamic-content#example-project--simple-blog) guide's example project. A single-author blog built on a Swarm feed: each post regenerates the full blog HTML and publishes it as the next feed entry, while the feed manifest URL stays stable.
+
+For the multi-author extension (authors with their own feeds + a shared index feed), see [`multi-author-blog/`](../multi-author-blog).
+
+## What it does
+
+- `init.js` — generates a publisher key, creates an empty blog, publishes it to a feed, and prints the feed manifest URL
+- `post.js create <slug> "<title>" "<body>"` — adds a new post and publishes the updated blog
+- `post.js edit <slug> "<title>" "<body>"` — replaces an existing post and re-publishes
+- `post.js delete <slug>` — removes a post and re-publishes
+- `read.js` — reads the latest feed entry without needing a private key
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL and BATCH_ID in .env
+```
+
+## Run
+
+```bash
+npm run init
+npm run post -- create hello "Hello Swarm" "This is my first post."
+npm run read
+```
+
+`init.js` writes the generated publisher key, posts list, and config to local JSON files alongside the scripts.
+
+## Requirements
+
+- A running Bee node (default: `http://localhost:1633`)
+- A funded **immutable** postage stamp batch
+- Node.js 18+
diff --git a/upload-and-download/.env.example b/upload-and-download/.env.example
@@ -0,0 +1,2 @@
+BEE_URL=http://localhost:1633
+BATCH_ID=<YOUR_BATCH_ID>
diff --git a/upload-and-download/.gitignore b/upload-and-download/.gitignore
@@ -0,0 +1,2 @@
+node_modules
+.env
diff --git a/upload-and-download/README.md b/upload-and-download/README.md
@@ -0,0 +1,29 @@
+# Upload and Download
+
+Companion code for the [**Upload and Download**](https://docs.ethswarm.org/docs/develop/upload-and-download) guide. The first step in the Swarm developer guide series — uploading a file or directory and downloading it back through your Bee node.
+
+## What it does
+
+- `script-01.js` — uploads a single string as `hello.txt`, downloads it back, and prints the content
+- `script-02.js` — uploads the `./sample-files/` directory and retrieves files by path (including from a subfolder)
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in BEE_URL and BATCH_ID in .env
+```
+
+## Run
+
+```bash
+npm run script:01
+npm run script:02
+```
+
+## Requirements
+
+- A running Bee node (default: `http://localhost:1633`)
+- A funded postage stamp batch
+- Node.js 18+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		BEE_URL=http://localhost:1633
		BATCH_ID=<YOUR_BATCH_ID>