diff --git a/README.md b/README.md
index e2ce6c0..7d00c97 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,66 @@
-# MokoSuiteStorage
+<!--
+ Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ SPDX-License-Identifier: GPL-3.0-or-later
+-->
 
-Layer 2 — Self-storage facility management, unit tracking, tenant leases, access control, and payments
\ No newline at end of file
+# MokoSuite Storage
+
+Self-storage facility management, unit inventory, gate access, and billing module for MokoSuite on Joomla 6.
+
+## Overview
+
+MokoSuiteStorage is a Layer 2 module in the MokoSuite platform, building on MokoSuiteClient (Layer 0) and MokoSuiteCRM (Layer 1) to provide complete self-storage operations management.
+
+## Package Contents
+
+| Extension | Type | Description |
+|---|---|---|
+| plg_system_mokosuitestorage | System Plugin | Schema, configuration, event handling |
+| com_mokosuitestorage | Component | Admin views for storage management |
+| plg_webservices_mokosuitestorage | Webservices Plugin | REST API routes |
+
+## Features
+
+- **Facility Management** -- multi-site facilities with address, manager, and operating hours
+- **Unit Inventory** -- dimensioned units with climate control, floor level, and multi-tier rates
+- **Tenant Management** -- CRM-linked tenants with ID verification and emergency contacts
+- **Lease Management** -- monthly/annual/prepaid leases with auto-renew and move-in/move-out tracking
+- **Payment Processing** -- payment tracking with cash, check, card, ACH, and autopay methods
+- **Gate Access Log** -- entry/exit tracking with gate codes and daily access limits
+- **Lien Actions** -- overlock, lien filing, and auction scheduling for delinquent accounts
+- **Billing** -- configurable billing cycles, late fees, and auto-lock on nonpayment
+
+## Database Schema
+
+| Table | Description |
+|---|---|
+| #__mokosuitestorage_facilities | Storage facility sites |
+| #__mokosuitestorage_units | Individual storage units with rates |
+| #__mokosuitestorage_tenants | Tenant profiles linked to CRM |
+| #__mokosuitestorage_leases | Unit lease agreements |
+| #__mokosuitestorage_payments | Payment records |
+| #__mokosuitestorage_access_log | Gate access entries |
+| #__mokosuitestorage_lien_actions | Lien and auction records |
+
+## Requirements
+
+- Joomla 6.x
+- PHP 8.3+
+- MokoSuiteClient (Layer 0)
+- MokoSuiteCRM (Layer 1)
+
+## Installation
+
+Install via Joomla Extension Manager using the package file `pkg_mokosuitestorage.zip`.
+
+Updates are delivered via [MokoGitea update server](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteStorage/updates.xml).
+
+## License
+
+GNU General Public License v3.0 or later -- see [LICENSE](LICENSE).
+
+## Links
+
+- [Documentation](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteStorage/wiki)
+- [Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteStorage/issues)
+- [MokoSuite Platform](https://mokoconsulting.tech)
\ No newline at end of file