diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..13a97d0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,41 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`lthn/php-plug-chat` is a PHP library providing chat platform integrations (Discord, Slack, Telegram) for the Plug framework. It depends on `lthn/php` which supplies the core contracts and concerns.
+
+## Build & Install
+
+```bash
+composer install
+```
+
+No tests, linter, or CI are configured yet.
+
+## Architecture
+
+**Namespace:** `Core\Plug\Chat\` (PSR-4 mapped to `src/`)
+
+Each chat provider lives in its own subdirectory and implements contracts from `lthn/php` (`Core\Plug\Contract\*`):
+
+| Contract | Purpose | Discord | Slack | Telegram |
+|---|---|---|---|---|
+| `Authenticable` | Auth/credential validation | `Auth` | `Auth` | `Auth` |
+| `Postable` | Send messages | `Post` | `Post` | `Post` |
+| `Deletable` | Delete messages | `Delete` | — | `Delete` |
+| `Readable` | Read bot/chat info | — | — | `Read` |
+| `Listable` | List chats | — | — | `Chats` |
+
+**Shared concerns** (from `lthn/php`): `BuildsResponse`, `UsesHttp`, `ManagesTokens`. All classes use `BuildsResponse` + `UsesHttp`; Telegram classes that need stored credentials also use `ManagesTokens`.
+
+**Auth model:** Discord and Slack use webhook URLs (no OAuth). Telegram uses Bot API tokens.
+
+## Conventions
+
+- All files use `declare(strict_types=1)`
+- Fluent setters for configuration (e.g., `withWebhook()`, `withBotToken()`, `toChatId()`)
+- All public API methods return `Core\Plug\Response` via `$this->fromHttp()`, `$this->ok()`, or `$this->error()`
+- Response transform callbacks normalize API-specific data into flat associative arrays
+- Media is passed as `Illuminate\Support\Collection` items with `url`/`path` keys