diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e87cd20
--- /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.
+
+## Overview
+
+This is `lthn/php-plug-content`, a PHP library providing content platform integrations for the Plug framework. It wraps the APIs of Dev.to, Hashnode, Medium, and WordPress into a uniform interface using contracts from `lthn/php` (the core Plug library).
+
+## Build / Install
+
+```bash
+composer install
+```
+
+No test suite, linter, or build step exists in this repo currently.
+
+## Architecture
+
+**Namespace:** `Core\Plug\Content\` (PSR-4 mapped to `src/`)
+
+Each platform is a subdirectory (`Devto/`, `Hashnode/`, `Medium/`, `Wordpress/`) containing classes that implement contracts from the core `Core\Plug` package:
+
+| Class | Contract | Purpose |
+|-------|----------|---------|
+| `Auth` | `Authenticable` | Credential validation and auth URL generation |
+| `Post` | `Postable` | Publishing and updating content |
+| `Read` | `Readable` | Fetching posts and user profiles |
+| `Delete` | `Deletable` | Removing/unpublishing content |
+| `Publications` | `Listable` | Listing publications (Hashnode, Medium only) |
+| `Media` | `MediaUploadable` | File uploads (WordPress only) |
+
+**Shared traits** (from `Core\Plug\Concern`):
+- `BuildsResponse` — wraps results into `Core\Plug\Response` objects via `fromHttp()` and `error()`
+- `UsesHttp` — provides `http()` for HTTP client access (Laravel HTTP facade style)
+- `ManagesTokens` — provides `accessToken()` for token storage/retrieval
+
+**Key patterns:**
+- All public API methods return `Core\Plug\Response`
+- Response data is normalized via closure-based transformers passed to `fromHttp($response, fn ($data) => [...])`
+- Fluent builder pattern for configuration (e.g., `->forSite()->withCredentials()`)
+- Auth classes expose `identifier()` and `name()` static methods for platform registration
+
+## Platform-Specific Notes
+
+- **WordPress** uses Basic Auth (application passwords) and REST API; requires `siteUrl` on all operations
+- **Hashnode** uses GraphQL (`gql.hashnode.com`) with PAT auth via `Authorization` header (no Bearer prefix)
+- **Medium** uses OAuth 2.0 with REST API; limited read capabilities (no post retrieval or listing)
+- **Dev.to** uses API key auth via `api-key` header; delete is implemented as unpublish (API limitation)