diff --git a/AGENTS.md b/AGENTS.md
index 0df3c0a8..0e0a1c64 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,6 +59,27 @@ This project has domain-specific skills available. You MUST activate the relevan
 
 - Be concise in your explanations - focus on what's important rather than explaining obvious details.
 
+=== invoiceshelf rules ===
+
+# InvoiceShelf Architecture
+
+## Service Pattern (Required)
+All business logic must live in Service classes (`app/Services/`). This is mandatory — do not put business logic in Models or Controllers.
+- **Controllers** are thin: authorize, call the service, return a response.
+- **Models** only contain relationships, scopes, accessors, mutators, and constants.
+- **Services** are injected into controllers via constructor injection.
+- Check existing services in `app/Services/` for patterns before creating new ones.
+
+## Testing (TDD)
+InvoiceShelf follows TDD development style. Every new feature or bug fix must have tests.
+- **Feature tests** (`tests/Feature/`) — test API routes end-to-end (HTTP requests, responses, database assertions). These are the primary test type.
+- **Unit tests** (`tests/Unit/`) — test service classes and business logic in isolation.
+- Write tests before or alongside implementation, not after.
+
+## Roles
+- **`super admin`** — global platform admin role (unscoped, manages all companies)
+- **`owner`** — company-level admin role (scoped to a specific company via Bouncer, full access to that company)
+
 === boost rules ===
 
 # Laravel Boost
diff --git a/CLAUDE.md b/CLAUDE.md
index 48ddc293..dec71db3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -66,13 +66,22 @@ Three guards: `web` (session), `api` (Sanctum tokens for `/api/v1/`), `customer`
 ### Database
 Supports MySQL, PostgreSQL, and SQLite. Prefer Eloquent over raw queries. Use `Model::query()` instead of `DB::`. Use eager loading to prevent N+1 queries.
 
+### Service Pattern
+All business logic must live in Service classes (`app/Services/`), not in Models or Controllers. Controllers are thin — they authorize, call the service, and return a response. Models only contain relationships, scopes, accessors, mutators, and constants. Services are injected via constructor injection.
+
+### Testing (TDD)
+InvoiceShelf follows TDD development style:
+- **Feature tests** (`tests/Feature/`) — test API routes end-to-end (HTTP requests, responses, database assertions)
+- **Unit tests** (`tests/Unit/`) — test service classes and business logic in isolation
+- Write tests before or alongside implementation. Every new feature or bug fix must have tests.
+
 ## Code Conventions
 
 - PHP: snake_case, constructor property promotion, explicit return types, PHPDoc blocks over inline comments
 - JS: camelCase
 - Always check sibling files for patterns before creating new ones
 - Use `config()` helper, never `env()` outside config files
-- Every change must have tests (feature tests preferred over unit tests)
+- Every change must have tests
 - Run `vendor/bin/pint --dirty --format agent` after modifying PHP files
 
 ## CI Pipeline