diff --git a/CLAUDE.md b/CLAUDE.md
index 83c432b..d7b94ad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,47 +1,59 @@
-# CLAUDE.md
+# MokoSuiteAuto
 
-This file provides guidance to Claude Code when working with this repository.
+Auto dealership management for Joomla 6 — VIN inventory, sales deals, F&I, trade-ins, test drives, financing, service department.
 
-## Project Overview
-
-**Template-Joomla** -- Unified Joomla extension scaffolding templates — plugin, template, module, component, package, library
+## Quick Reference
 
 | Field | Value |
 |---|---|
-| **Platform** | template |
-| **Language** | Markdown |
-| **Default branch** | main |
-| **License** | GPL-3.0-or-later |
-| **Wiki** | [Template-Joomla Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-Joomla/wiki) |
-| **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) |
-
-## Common Commands
-
-```bash
-make build        # Build the project
-make lint         # Run linters
-make validate     # Validate structure
-make release      # Full release pipeline
-make minify       # Minify CSS/JS assets
-make clean        # Clean build artifacts
-```
-
-```bash
-composer install  # Install PHP dependencies
-```
+| **Package** | `pkg_mokosuiteauto` |
+| **Layer** | 4 (requires: Client → CRM → ERP → POS) |
+| **Language** | PHP 8.3+ |
+| **Branch** | develop on `dev`, merge to `main` (protected) |
+| **Wiki** | [MokoSuiteAuto Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteAuto/wiki) |
 
 ## Architecture
 
-This is a project template. Files are copied when creating new repos.
-- Edit files here to change defaults for new projects
-- `.mokogitea/workflows/` -- CI/CD workflow templates
-- `Makefile` -- build targets inherited by new projects
+Joomla **package** (`pkg_mokosuiteauto`) — Layer 4 add-on extending MokoSuitePOS.
+
+### Dependencies
+- MokoSuiteClient (Layer 0) — base platform
+- MokoSuiteCRM (Layer 1) — contacts, deals, invoicing
+- MokoSuiteERP (Layer 2) — inventory, accounting
+- MokoSuitePOS (Layer 3) — transactions, cash register
+
+### Helpers (6)
+- `VehicleHelper` — inventory filters, VIN lookup, dashboard, aging report
+- `DealHelper` — deal creation, gross profit (front+back), sales dashboard
+- `TradeInHelper` — appraisal, equity calculation, pending review
+- `TestDriveHelper` — scheduling, mileage check-out/in, vehicle history
+- `FinancingHelper` — loan calculator, term comparison, deal desking
+- `ServiceDeptHelper` — repair orders, VIN history, service dashboard
+
+### Key Patterns
+- VIN format: `[A-HJ-NPR-Z0-9]{17}` (post-1981, excludes I/O/Q per NHTSA)
+- Gross profit: `Front = Sale - Invoice - Recon - Trade` / `Back = SUM(F&I profits)`
+- Negative trade equity rolls into financed amount
+- Deal workflow: `prospect → negotiating → pending_finance → approved → delivered → unwound`
+
+## Source Directory
+
+- `source/pkg_mokosuiteauto.xml` — package manifest
+- `source/packages/` — sub-extensions
 
 ## 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)
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
+- **Attribution**: `Authored-by: Moko Consulting`
+- **Workflow directory**: `.mokogitea/`
+- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoCLI/wiki)
+- **Changelog**: `[Unreleased]` only — release system assigns versions
+- **No upstream references**: never reference competitor products
+
+## Coding Standards
+
+- PHP 8.3+ / Joomla 6 patterns
+- `$this->getDatabase()` in models, `Factory::getContainer()->get(DatabaseInterface::class)` in helpers
+- `Factory::getApplication()->getIdentity()` for user
+- `FOR UPDATE` inside transactions for race-condition-prone operations