feat: add A2A Agent Card for Swarm discovery

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

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.
 

static/.well-known/agent-card.json

@@ -0,0 +1,142 @@
+{
+  "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",
+  "mcpServerUrl": "https://github.com/ethersphere/swarm-mcp",
+  "llmsTxtUrl": "https://docs.ethswarm.org/llms.txt",
+  "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
+}

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