diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..bd1dead7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+**MokoWaaS** -- MokoWaaS is a Joomla 5.x / 6.x system plugin that provides a configurable white-label identity layer for the MokoWaaS platform.
+
+| Field | Value |
+|---|---|
+| **Platform** | joomla |
+| **Language** | PHP |
+| **Default branch** | main |
+| **License** | GPL-3.0-or-later |
+| **Wiki** | [MokoWaaS Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki) |
+| **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) |
+
+## Common Commands
+
+```bash
+composer install  # Install PHP dependencies
+```
+
+## Architecture
+
+This is a Joomla extension. Key directories:
+- `src/` -- extension source (deployed to Joomla)
+- `src/*.xml` -- manifest file (version, files, params)
+- `src/src/` or `src/services/` -- PHP classes
+- `src/language/` -- translation strings
+- `src/media/` -- CSS/JS/images
+
+## Rules
+
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, or `*.min.css`/`*.min.js`
+- **Attribution**: use `Authored-by: Moko Consulting` in commits
+- **Branch strategy**: develop on `dev`, merge to `main` for release
+- **Minification**: handled at build time (CI) and runtime (MokoMinifyHelper for Joomla templates)
+- **Wiki**: documentation lives in the Gitea wiki, not in `docs/` files
+- **Standards**: this repo follows [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)