diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..cf2b7a3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Laravel package (`lthn/php-plug-altum`) providing PHP API clients for four AltumCode self-hosted products: 66analytics, 66biolinks, 66pusher, and 66socialproof. Licensed EUPL-1.2.
+
+## Commands
+
+```bash
+# Install dependencies
+composer install
+
+# Run all tests
+./vendor/bin/pest
+
+# Run a single test file
+./vendor/bin/pest tests/AltumClientTest.php
+
+# Run a specific test by name
+./vendor/bin/pest --filter="creates user with named params"
+```
+
+## Architecture
+
+**Namespace:** `Core\Plug\Altum\` (PSR-4 mapped to `src/`)
+
+### Key design decisions
+
+- **`AltumClient`** is the base class containing all HTTP transport and both Admin API (`/admin-api/`) and User API (`/api/{resource}/`) methods. Product clients extend it.
+- **Product clients** (`Analytics\Client`, `Biolinks\Client`, `Pusher\Client`, `Socialproof\Client`) are thin wrappers that call inherited `listResource()`, `getResource()`, `createResource()`, `updateResource()`, `deleteResource()` methods with product-specific resource names.
+- **`AltumManager`** is a factory that reads config and instantiates the correct product client. Resolved as a singleton via `AltumServiceProvider`.
+- **`AltumWebhookVerifier`** implements `Core\Webhook\WebhookVerifier` (from the parent framework). Currently only checks User-Agent header since AltumCode doesn't yet sign webhooks.
+- **Immutable cloning:** `withUserKey()` returns a new client instance rather than mutating state.
+
+### AltumCode API quirks (important for new endpoints)
+
+- POST is used for both creates and updates (never PUT/PATCH).
+- POST bodies are form-encoded (`asForm()`), not JSON.
+- Admin endpoints: `/admin-api/...` with admin API key.
+- User endpoints: `/api/{resource}/` with per-user API key.
+- Errors return `['error' => true, ...]` arrays instead of throwing exceptions.
+
+### Laravel integration
+
+- Auto-discovered via `extra.laravel.providers` in composer.json.
+- Config expected at `services.altum` with structure: `['analytics' => ['url' => '...', 'admin_key' => '...'], ...]`.
+- Webhook verifiers bound as `webhook.verifier.altum-{product}` for each product.
+
+## Testing
+
+Uses Pest 3 with Laravel's `Http::fake()` for all HTTP mocking. Tests mirror the `src/` directory structure under `tests/`. No real API calls are made.