diff --git a/AGENTS.md b/AGENTS.md
index fa46ce9..58feb8b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,4 +1,37 @@
 <laravel-boost-guidelines>
+=== project rules ===
+
+# Hybrid Architecture: Legacy vs. Modern
+
+The project is currently in a transition phase from a legacy Laravel 8 architecture to a modern Laravel 12 setup. It is CRITICAL to distinguish between these two "worlds":
+
+### 1. Legacy World (Maintenance Only)
+- **Technology Stack**: jQuery, Bootstrap, Laravel Mix (`webpack.mix.js`), DataTables, Mustache.js.
+- **Entry Point**: `resources/views/layout/core.blade.php`, `/legacy` routes, and controllers using standard Blade views.
+- **Assets**: Managed via `mix()`. Files located in `resources/js/` (excluding `modern` subfolder).
+- **Rule**: ONLY touch these for bug fixes or minor adjustments. DO NOT implement new features here unless explicitly requested.
+
+### 2. Modern World (Primary Development)
+- **Technology Stack**: Laravel 12, Filament v4 (TALL stack: Tailwind, Alpine.js, Laravel, Livewire), Vite (`vite.config.js`).
+- **Entry Point**: `/admin` (Filament Dashboard), `resources/modern/` folder.
+- **Assets**: Managed via `vite()`. Tailwind CSS v4 is used for styling.
+- **Rule**: ALL new features should be implemented using Filament resources/pages or modern Livewire components.
+
+### 3. Transition & Modernization
+- **Clean Cut Approach**: We are systematically replacing legacy jQuery solutions with modern Laravel 12 equivalents.
+- **Auditing**: Use `BaseAuditable` for all new models to ensure consistent tracking.
+- **Refactoring**: If a legacy controller/view needs a significant overhaul, propose moving it to a Filament Resource.
+
+# Project Specific Rules
+
+- **API Responses**: Use `flugger/laravel-responder` (`responder()` helper) for all API responses. Follow the existing pattern in `OrderController.php`.
+- **API Versioning**: Parse API versions from namespaces using the `parseAPIVersionFromNamespace(__NAMESPACE__)` helper.
+- **Documentation**: Use Scribe for API documentation. Use `@group`, `@authenticated`, `@bodyParam`, and `@responseField` annotations in controllers.
+- **Models**: New models should typically extend `BaseAuditable` instead of the base Eloquent `Model` if auditing is required.
+- **Helpers**: Use project-specific helpers defined in `app/helpers.php` (e.g., `formatterPhoneNumber`, `formatterDateTime`, `getSql`).
+- **Translations**: Use `laravel-lang/lang` for multi-language support.
+- **Enums**: Use `bensampo/laravel-enum` for type-safe enumerations (e.g., `OrderStatusEnum`, `OrderType`).
+
 === foundation rules ===
 
 # Laravel Boost Guidelines