From 955b47bfd26fae717350d409cc21a5f9200342ff Mon Sep 17 00:00:00 2001 From: Crt Ahlin Date: Thu, 23 Apr 2026 10:25:38 +0200 Subject: [PATCH 1/5] Sync: 2026-04-23 --- CLAUDE.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..f4310415 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,60 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Role + +You are an experienced documentation expert. Take care to write accurate, precise, complete yet concise documentation. You are especially proud of the correctness and usefulness of the API documentation. + +## Project Overview + +This is the **Swarm documentation website** (docs.ethswarm.org), built with **Docusaurus 3.9.x**. It documents the Bee client (Go implementation of the Swarm protocol) and the broader Swarm ecosystem. + +## Commands + +- `npm ci` — Install dependencies (preferred over `npm install`) +- `npm start` — Start local dev server with hot reload +- `npm run build` — Production build (runs `prebuild` script first to fetch external content, then generates static site in `/build`) +- `npm run serve` — Serve the built static site locally + +There are no test or lint commands. The build process validates markdown links and routes (broken links produce warnings, duplicate routes produce errors). + +## Architecture + +**Content** lives in `docs/` as Markdown/MDX files organized into five sections: +- `concepts/` — Theoretical documentation (DISC storage, incentives, PSS, access control) +- `bee/` — Bee client guides (installation, working with Bee) +- `develop/` — Developer guides (tools, features, contributing) +- `desktop/` — Desktop app documentation +- `references/` — Glossary, tokens, community, FAQ + +**Navigation** is defined in `sidebars.js`. The Docusaurus config is `docusaurus.config.mjs`. + +**Custom React components** in `src/components/` provide interactive calculators (storage amount/depth, redundancy, volume/duration, parities). + +**OpenAPI specs** in `openapi/` (`Swarm.yaml`, `SwarmCommon.yaml`) are rendered via the redocusaurus plugin. These are manually mirrored from the Bee repo and need manual updates. + +**Build-time script** `scripts/fetch-awesome-swarm.mjs` fetches the awesome-swarm README from GitHub during `prebuild` and writes it to `docs/references/awesome-list.mdx` (auto-generated, gitignored). + +**Theme customization**: The SearchBar component is swizzled from the lunr-search plugin (`src/theme/SearchBar/`). Must be re-swizzled after Docusaurus theme upgrades. + +**Search**: Algolia (primary) with lunr as local fallback. + +**Math/diagrams**: KaTeX for math rendering, Mermaid for diagrams. + +## Deployment + +CI runs on GitHub Actions. Pushes/PRs to `master` trigger a build check (`build.yaml`). Version tags (`v*.*.*`) trigger deployment to GitHub Pages (`gh-pages.yaml`). + +## Important Rules + +- **Never mention Claude** in any commit messages, issue titles, issue bodies, branch names, or any other visible output. Do not reference AI assistance. +- **Always use the `crtahlin` fork/repo** for creating issues, branches, and all GitHub operations — never the upstream `ethersphere` repo. + +## Conventions + +- **Node 20+** required (see `.nvmrc`), npm >= 9.6.0 +- Use `npm ci` by default; only commit `package-lock.json` changes when intentional +- Wrap long lines in markdown with newlines to reduce merge conflicts +- Avoid unnecessary formatting changes in PRs (e.g., re-indentation unrelated to the fix) +- Terminology: `Swarm` (capital) = the project/network; `swarm` (lowercase) = network of bee nodes; `Bee` (capital) = the Go client; `bee` (lowercase) = any worker/client implementation From fbce5e915d9ae13571daadf0e40306db002c855a Mon Sep 17 00:00:00 2001 From: Crt Ahlin Date: Wed, 13 May 2026 16:25:47 +0200 Subject: [PATCH 2/5] feat: add A2A Agent Card for Swarm agent discovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Deploy an A2A protocol Agent Card at /.well-known/agent-card.json following the A2A spec (Linux Foundation). Enables programmatic discovery of Swarm's storage capabilities by other AI agents. Describes 12 skills: upload/download data and files, feeds, postage stamp lifecycle, and upload progress monitoring. Static card only — no live agent service endpoint. The card advertises capabilities available via the swarm-mcp toolset. Refs: ethersphere/DevRel#831 --- static/.well-known/agent-card.json | 140 +++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 static/.well-known/agent-card.json diff --git a/static/.well-known/agent-card.json b/static/.well-known/agent-card.json new file mode 100644 index 00000000..be8b4f69 --- /dev/null +++ b/static/.well-known/agent-card.json @@ -0,0 +1,140 @@ +{ + "name": "Ethereum Swarm Storage Agent", + "description": "Decentralized storage agent powered by Ethereum Swarm. Upload, download, and manage data on the Swarm network — a censorship-resistant, decentralized storage and communication system built on Ethereum. Supports raw data, files, folders, mutable feeds, and postage stamp lifecycle management via the swarm-mcp toolset.", + "url": "https://docs.ethswarm.org", + "provider": { + "organization": "Ethersphere", + "url": "https://www.ethswarm.org" + }, + "version": "0.1.0", + "documentationUrl": "https://docs.ethswarm.org", + "capabilities": { + "streaming": false, + "pushNotifications": false + }, + "defaultInputModes": ["application/json"], + "defaultOutputModes": ["application/json"], + "skills": [ + { + "id": "upload-data", + "name": "Upload Data", + "description": "Upload text data to Swarm. Returns an immutable content-addressed reference hash. Optional: redundancyLevel (0-4) for fault tolerance, postageBatchId to specify a pre-purchased stamp.", + "tags": ["decentralized-storage", "ethereum", "swarm", "upload"], + "examples": [ + "Store this text on Swarm", + "Upload data to decentralized storage" + ] + }, + { + "id": "download-data", + "name": "Download Data", + "description": "Download immutable data from Swarm using a content-addressed reference hash. Returns the original text data stored at that address.", + "tags": ["decentralized-storage", "ethereum", "swarm", "download"], + "examples": [ + "Retrieve data from Swarm by reference hash", + "Download content from decentralized storage" + ] + }, + { + "id": "upload-file", + "name": "Upload File", + "description": "Upload a file to Swarm from base64-encoded content or a local file path. Optional: redundancyLevel (0-4) for fault tolerance, postageBatchId. Returns a Swarm reference hash.", + "tags": ["decentralized-storage", "ethereum", "swarm", "upload", "files"], + "examples": [ + "Upload this file to Swarm", + "Store a file on decentralized storage" + ] + }, + { + "id": "upload-folder", + "name": "Upload Folder", + "description": "Upload an entire folder to Swarm. Requires a local folder path. Optional: redundancyLevel (0-4), postageBatchId. Returns a Swarm reference hash for the folder manifest.", + "tags": ["decentralized-storage", "ethereum", "swarm", "upload", "files"], + "examples": [ + "Upload this directory to Swarm", + "Store a folder on decentralized storage" + ] + }, + { + "id": "download-files", + "name": "Download Files", + "description": "Download files or folders from Swarm using a reference hash. Prioritized over download-data for unknown data types. Optional: filePath for local destination.", + "tags": ["decentralized-storage", "ethereum", "swarm", "download", "files"], + "examples": [ + "Download files from this Swarm reference", + "Retrieve a folder from decentralized storage" + ] + }, + { + "id": "update-feed", + "name": "Update Feed", + "description": "Update a mutable Swarm feed with new data for a given topic. Feeds provide mutable pointers to immutable content, enabling updatable resources on Swarm. Requires data and memoryTopic. Optional: postageBatchId.", + "tags": ["decentralized-storage", "ethereum", "swarm", "feeds", "mutable"], + "examples": [ + "Update my Swarm feed with new content", + "Write to a mutable feed topic" + ] + }, + { + "id": "read-feed", + "name": "Read Feed", + "description": "Retrieve the latest data from a Swarm feed by topic. Optionally specify an owner Ethereum address to read another account's feed.", + "tags": ["decentralized-storage", "ethereum", "swarm", "feeds"], + "examples": [ + "Read the latest data from my Swarm feed", + "Get the current value of a feed topic" + ] + }, + { + "id": "create-postage-stamp", + "name": "Create Postage Stamp", + "description": "Buy a postage stamp (storage voucher) based on required storage size in MB and duration (e.g. '1d', '1w', '1month'). Postage stamps are required to upload data to Swarm. Optional: label for human-readable identification.", + "tags": ["decentralized-storage", "ethereum", "swarm", "postage", "payments"], + "examples": [ + "Buy a postage stamp for 100 MB lasting 1 month", + "Create a storage voucher for Swarm uploads" + ] + }, + { + "id": "get-postage-stamp", + "name": "Get Postage Stamp", + "description": "Retrieve details of a specific postage stamp by its batch ID, including remaining capacity and expiry information.", + "tags": ["decentralized-storage", "ethereum", "swarm", "postage"], + "examples": [ + "Check the status of my postage stamp", + "Get details for this batch ID" + ] + }, + { + "id": "list-postage-stamps", + "name": "List Postage Stamps", + "description": "List available postage stamps with optional filtering. Options: leastUsed (sort order), limit (max results), minUsage/maxUsage (percentage filters).", + "tags": ["decentralized-storage", "ethereum", "swarm", "postage"], + "examples": [ + "Show my available postage stamps", + "List stamps with less than 50% usage" + ] + }, + { + "id": "extend-postage-stamp", + "name": "Extend Postage Stamp", + "description": "Increase the duration or storage capacity of an existing postage stamp by batch ID. Specify additional size in MB and/or additional duration.", + "tags": ["decentralized-storage", "ethereum", "swarm", "postage", "payments"], + "examples": [ + "Extend my postage stamp by 1 week", + "Add 50 MB to this batch" + ] + }, + { + "id": "query-upload-progress", + "name": "Query Upload Progress", + "description": "Check the upload progress of a deferred upload using a tag ID returned by upload_file or upload_folder operations. Used for monitoring large uploads that exceed the 5 MB sync threshold.", + "tags": ["decentralized-storage", "ethereum", "swarm", "upload", "monitoring"], + "examples": [ + "Check the progress of my upload", + "Query upload status by tag ID" + ] + } + ], + "supportsAuthenticatedExtendedCard": false +} From f51709d3fe0a94f7a6ae79181238c6e3dc2eb590 Mon Sep 17 00:00:00 2001 From: Crt Ahlin Date: Wed, 13 May 2026 16:31:25 +0200 Subject: [PATCH 3/5] feat: add mcpServerUrl and llmsTxtUrl to agent card Point agents to the swarm-mcp repo (how to set up tooling) and llms.txt (machine-readable documentation) so discovery leads to action. --- static/.well-known/agent-card.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/static/.well-known/agent-card.json b/static/.well-known/agent-card.json index be8b4f69..c4cf38ef 100644 --- a/static/.well-known/agent-card.json +++ b/static/.well-known/agent-card.json @@ -8,6 +8,8 @@ }, "version": "0.1.0", "documentationUrl": "https://docs.ethswarm.org", + "mcpServerUrl": "https://github.com/ethersphere/swarm-mcp", + "llmsTxtUrl": "https://docs.ethswarm.org/llms.txt", "capabilities": { "streaming": false, "pushNotifications": false From 77ac7727b5ba7f2ead7bf8056402941ce9151275 Mon Sep 17 00:00:00 2001 From: Crt Ahlin Date: Wed, 13 May 2026 16:34:50 +0200 Subject: [PATCH 4/5] feat: reference agent card and swarm-mcp in llms.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add discovery path: agents reading llms.txt can find the A2A agent card and the swarm-mcp repo, closing the loop from docs → capabilities → tooling. --- static/llms.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/static/llms.txt b/static/llms.txt index 5f2b397b..b7f4c7b7 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -9,6 +9,8 @@ This is the documentation for [Swarm](https://www.ethswarm.org/) and its referen - [bee-js documentation](https://bee-js.ethswarm.org/): JavaScript/TypeScript SDK for Swarm - [The Book of Swarm](https://www.ethswarm.org/The-Book-of-Swarm.pdf): Comprehensive technical reference - [Swarm Whitepaper](https://www.ethswarm.org/swarm-whitepaper.pdf): Original design paper +- [A2A Agent Card](https://docs.ethswarm.org/.well-known/agent-card.json): Machine-readable agent capabilities for A2A protocol discovery +- [Swarm MCP Server](https://github.com/ethersphere/swarm-mcp): MCP server for AI agents to interact with Swarm programmatically ## Install and run a Bee node From 8dc9ee5d3f63aede375717e5a2dad6b056512e9e Mon Sep 17 00:00:00 2001 From: Crt Ahlin Date: Wed, 13 May 2026 16:41:55 +0200 Subject: [PATCH 5/5] Sync: 2026-05-13 --- docs/references/awesome-list.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/references/awesome-list.mdx b/docs/references/awesome-list.mdx index 49d9eb6a..a0f502ed 100644 --- a/docs/references/awesome-list.mdx +++ b/docs/references/awesome-list.mdx @@ -44,7 +44,7 @@ See [CONTRIBUTING.md](https://github.com/ethersphere/awesome-swarm/blob/master/C [Bee Dashboard](https://github.com/ethersphere/bee-dashboard) - React project to troubleshoot and interact with your Bee node. -[Gateway](https://github.com/ethersphere/gateway-ui) - Gateway to the Swarm project, for uploading, downloading and sharing assets on the network. +[Gateway](https://github.com/ethersphere/gateway) - Gateway to the Swarm project, for uploading, downloading and sharing assets on the network. [Swarmy](https://swarmy.cloud/) - Swarm as a service, makes it simple to store and retrieve data on Swarm. @@ -54,7 +54,6 @@ See [CONTRIBUTING.md](https://github.com/ethersphere/awesome-swarm/blob/master/C [buzzMint](https://buzzmint.io/) - A decentralised NFT creator. -[Bchan](https://github.com/Cafe137/bchan-public) - A private message board allowing users to post images, text, and links across various threads. ### Tools @@ -121,17 +120,18 @@ See [CONTRIBUTING.md](https://github.com/ethersphere/awesome-swarm/blob/master/C [Fairdrive code](https://github.com/fairDataSociety/fairdrive-theapp) - Code for decentralised and unstoppable "Dropbox" for end-users and developers using Fair Data Protocol. -[SwarmScan](https://swarmscan.io/) - Get network insights. + +[SwarmScan](https://swarmscan.resenje.org/) - Get network insights. [Etherna.io](https://etherna.io/) - Decentralised media platform on Swarm. [SwarmNFT library](https://github.com/igar1991/SwarmNFT) - JavaScript library for creating NFTs on Ethereum-compatible blockchains and storing content on Swarm. -[videoNFT](https://github.com/pblvrt/videoNFT) - NFT live streaming with Swarm (winner of EthBerlin3 2022 Freedom to Transact Track). +[videoNFT](https://github.com/pabloVoorvaart/videoNFT/) - NFT live streaming with Swarm (winner of EthBerlin3 2022 Freedom to Transact Track). -[DeBoot](https://github.com/debootdevs/deboot) - DeBoot is a project to research and implement approaches to bootloading OS images from a decentralized storage network such as Swarm or IPFS. +[DeBoot](https://github.com/awmacpherson/deboot) - DeBoot is a project to research and implement approaches to bootloading OS images from a decentralized storage network such as Swarm or IPFS. -[Swarm DAppNode Package](https://github.com/w3rkspacelabs/DAppNodePackage-Swarm) - Swarm DAppNode package for Swarm Mainnet with multi-platform (x86_64 and arm64) support. +[Swarm DAppNode Package](https://github.com/rndlabs/dappnodepackage-swarm) - Swarm DAppNode package for Swarm Mainnet with multi-platform (x86_64 and arm64) support. [Mipasa Swarm Connector](https://github.com/MiPasa/mipasa-swarm-connector/) - MiPasa connector for Swarm (BZZ) distributed storage network.