diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a07d96b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+PHP Composer library (`lthn/php-plug-web3`) providing decentralised/Web3 social media provider integrations for the Plug framework. Depends on `lthn/php` which supplies the base contracts, concerns, and `Response` class.
+
+## Commands
+
+No build step — this is a library. Install dependencies:
+```bash
+composer install
+```
+
+No test suite or linter is configured in this repository.
+
+## Architecture
+
+**Namespace:** `Core\Plug\Web3\` (PSR-4 from `src/`)
+
+**Six providers**, each under `src/{Provider}/`:
+- **Bluesky** — AT Protocol, app passwords, optional custom PDS via `withPds()`
+- **Farcaster** — Neynar API, managed signers via `withSigner()` + `withApiKey()`
+- **Lemmy** — REST API v3, username/password JWT auth, federated via `forInstance()`
+- **Mastodon** — REST API v1, OAuth 2.0, federated via `forInstance()`
+- **Nostr** — Cryptographic key pairs (secp256k1), relay-based publishing, no HTTP auth
+- **Threads** — Meta Graph API, OAuth 2.0, two-step container+publish flow
+
+**Each provider has up to 5 classes** implementing contracts from `Core\Plug\Contract\`:
+- `Auth` implements `Authenticable` — authentication/token exchange
+- `Post` implements `Postable` — publishing content (`publish(string $text, Collection $media, array $params)`)
+- `Read` implements `Readable` — fetching content (`get()`, `me()`, `list()`)
+- `Delete` implements `Deletable` — removing content
+- `Media` implements `MediaUploadable` — file uploads (Mastodon, Bluesky only)
+- Lemmy also has `Comment` and `Communities` (implements `Listable`)
+
+**Shared behaviour via concerns** from `Core\Plug\Concern\`:
+- `BuildsResponse` — wraps API responses into `Core\Plug\Response` (`fromHttp()`, `ok()`, `error()`)
+- `UsesHttp` — provides `$this->http()` (Laravel HTTP client)
+- `ManagesTokens` — `withToken()`, `accessToken()`, `getToken()`
+
+**Key patterns:**
+- All public methods return `Core\Plug\Response`
+- Federated providers (Mastodon, Lemmy) require instance URL set via `forInstance()` before API calls
+- `Post::publish()` has a uniform signature across all providers; provider-specific options go in `$params`
+- Each provider has static `externalPostUrl()` and `externalAccountUrl()` helpers for generating web URLs
+- Strict types declared in every file; PHP 8.2+ required