Two files, one repository
coollabsio/coolify ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ Cursor rules
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 54 | 28 | 0% |
| Commands | 2 | 22 | 3 | 7% |
| Section tags | 7 | 7 | 2 | 44% |
What each file covers
Sections
0 shared · 54 only in A · 28 only in B- − AGENTS.md
- − Project Overview
- − Design Reference
- − Development Environment
- − Start dev environment (uses docker-compose.dev.yml)
- − Common Commands
- − Tests (Pest 4)
- − Code formatting (Pint, Laravel preset)
- − Frontend
- − Browser Tests (Pest Browser Plugin)
- − Run all browser tests
- − Run a specific browser test file
- − Run a specific test by name
- − Writing Browser Tests
- − Architecture
- − Backend Structure (app/)
- − API Layer
- − Authorization
- − Event Broadcasting
- − Key Domain Concepts
- − Laravel 10 Structure (NOT Laravel 11+ slim structure)
- − Key Conventions
- − Git Workflow
- − Laravel Boost Guidelines
- − Foundational Context
- − Skills Activation
- − Conventions
- − Verification Scripts
- − Application Structure & Architecture
- − Frontend Bundling
- − Documentation Files
- − Replies
- − Laravel Boost
- − Tools
- − Searching Documentation (IMPORTANT)
- − Search Syntax
- − Artisan
- − Tinker
- − PHP
- − Deployment
- − Test Enforcement
- − Do Things the Laravel Way
- − Model Creation
- − APIs & Eloquent Resources
- − URL Generation
- − Testing
- − Vite Error
- − Laravel 12
- − Laravel 10 Structure
- − Database
- − Models
- − Livewire
- − Laravel Pint Code Formatter
- − Pest
- + Coolify AI Documentation
- + Quick Start
- + Documentation Structure
- + 📚 Core Documentation
- + 💻 Development
- + 🎨 Code Patterns
- + 📖 Meta
- + Quick Decision Tree
- + Running Commands
- + Writing Tests
- + Building UI
- + Database Work
- + Security & Authorization
- + Laravel-Specific
- + Version Numbers
- + Critical Patterns (Always Follow)
- + Testing Commands
- + Unit tests (no database, outside Docker)
- + Feature tests (requires database, inside Docker)
- + Form Authorization
- + Livewire Components
- + Code Style
- + Always run before committing
- + For AI Assistants
- + Important Notes
- + When to Use Which File
- + Maintaining Documentation
- + Migration Note
Commands
2 shared · 22 only in A · 3 only in B- − php artisan test --compact
- − php artisan test --compact --filter=testName
- − php artisan test --compact tests/Feature/SomeTest.php
- − php artisan test --compact tests/v4/Browser/
- − php artisan test --compact tests/v4/Browser/LoginTest.php
- − php artisan test --compact --filter='can login with valid credentials'
- − docker.php
- − php artisan make:
- − composer run dev
- − php artisan route:list
- − php artisan list
- − php artisan [command] --help
- − php artisan config:show app.name
- − php artisan config:show database.default
- − php artisan tinker --execute 'Your::code();'
- − php artisan tinker --execute 'User::where("active", true)->count();'
- − php artisan make:class
- − php artisan make:model --help
- − php artisan make:test [options] {name}
- − php artisan make:test --pest {name}
- − php artisan make:test --pest SomeFeatureTest
- − php artisan make:test --pest Feature/SomeFeatureTest
- + docker exec coolify php artisan test
- + php artisan serve
- + php artisan migrate
- npm run dev
- npm run build
Section tags
7 shared · 7 only in A · 2 only in B- − setup
- − lint-format
- − testing-strategy
- − git-pr
- − api
- − do-not
- − agent-behaviour
- + ui
- + deployment
- build
- test
- code-style
- architecture
- security
- database
- docs
Line diff
coollabsio/coolify · AGENTS.md
@@ −1 @@
1# AGENTS.md
2
3This file provides guidance to agentic coding tools when working with code in this repository.
4
5## Project Overview
6
7Coolify is an open-source, self-hostable PaaS (alternative to Heroku/Netlify/Vercel). It manages servers, applications, databases, and services via SSH. Built with Laravel 12 (using Laravel 10 file structure), Livewire 3, and Tailwind CSS v4.
8
9## Design Reference
10
11For UI/UX design specifications, principles, and visual standards, consult `DESIGN.md` in the [coollabsio/architecture](https://github.com/coollabsio/architecture) repo.
12
13## Development Environment
14
15Docker Compose-based dev setup with services: coolify (app), postgres, redis, soketi (WebSockets), vite, testing-host, mailpit, minio.
16
17```bash
18# Start dev environment (uses docker-compose.dev.yml)
19spin up # or: docker compose -f docker-compose.dev.yml up -d
20spin down # stop services
21```
22
23The app runs at `localhost:8000` by default. Vite dev server on port 5173.
24
25## Common Commands
26
27```bash
28# Tests (Pest 4)
29php artisan test --compact # all tests
30php artisan test --compact --filter=testName # single test
31php artisan test --compact tests/Feature/SomeTest.php # specific file
32
33# Code formatting (Pint, Laravel preset)
34vendor/bin/pint --dirty --format agent # format changed files
35
36# Frontend
37npm run dev # vite dev server
38npm run build # production build
39```
40
41## Browser Tests (Pest Browser Plugin)
42
43Uses `pestphp/pest-plugin-browser` with Laravel Dusk 8. New browser tests go in `tests/v4/Browser/`.
44
45```bash
46# Run all browser tests
47php artisan test --compact tests/v4/Browser/
48
49# Run a specific browser test file
50php artisan test --compact tests/v4/Browser/LoginTest.php
51
52# Run a specific test by name
53php artisan test --compact --filter='can login with valid credentials'
54```
55
56### Writing Browser Tests
57
58- Place new tests in `tests/v4/Browser/` — legacy Dusk tests in `tests/Browser/` should not be used as reference.
59- Use `RefreshDatabase` and seed required data (at minimum `InstanceSettings::create(['id' => 0])`) in `beforeEach`.
60- Key API: `visit()`, `fill(field, value)`, `click(text)`, `assertSee()`, `assertDontSee()`, `assertPathIs()`, `screenshot()`.
61- Always call `screenshot()` at the end of each test for debugging.
62- For authenticated tests, create a helper function that logs in via the UI:
63
64```php
65function loginAsRoot(): mixed
66{
67 return visit('/login')
68 ->fill('email', 'test@example.com')
69 ->fill('password', 'password')
70 ->click('Login');
71}
72```
73
74- See `tests/v4/Browser/LoginTest.php`, `tests/v4/Browser/DashboardTest.php`, and `tests/v4/Browser/RegistrationTest.php` for conventions.
75- Chrome driver runs on `localhost:4444`, app on `localhost:8000` (configured in `tests/DuskTestCase.php`).
76- Legacy Dusk macros in `app/Providers/DuskServiceProvider.php` use the old `type()`/`press()` API — do not mix with Pest Browser Plugin's `fill()`/`click()` API.
77
78## Architecture
79
80### Backend Structure (app/)
81- **Actions/** — Domain actions organized by area (Application, Database, Docker, Proxy, Server, Service, Shared, Stripe, User, CoolifyTask, Fortify). Uses `lorisleiva/laravel-actions` with `AsAction` trait — actions can be called as objects, dispatched as jobs, or used as controllers.
82- **Livewire/** — All UI components (Livewire 3). Pages organized by domain: Server, Project, Settings, Security, Notifications, Terminal, Subscription, SharedVariables. This is the primary UI layer — no traditional Blade controllers. Components listen to private team channels for real-time status updates via Soketi.
83- **Jobs/** — Queue jobs for deployments (`ApplicationDeploymentJob`), backups, Docker cleanup, server management, proxy configuration. Uses Redis queue with Horizon for monitoring.
84- **Models/** — Eloquent models extending `BaseModel` which provides auto-CUID2 UUID generation. Key models: `Server`, `Application`, `Service`, `Project`, `Environment`, `Team`, plus standalone database models (`StandalonePostgresql`, `StandaloneMysql`, etc.). Common traits: `HasConfiguration`, `HasMetrics`, `HasSafeStringAttribute`, `ClearsGlobalSearchCache`.
85- **Services/** — Business logic services (ConfigurationGenerator, DockerImageParser, ContainerStatusAggregator, HetznerService, etc.). Use Services for complex orchestration; use Actions for single-purpose domain operations.
86- **Helpers/** — Global helpers loaded via `bootstrap/includeHelpers.php` from `bootstrap/helpers/` — organized into `shared.php`, `constants.php`, `versions.php`, `subscriptions.php`, `domains.php`, `docker.php`, `services.php`, `github.php`, `proxy.php`, `notifications.php`.
87- **Data/** — Spatie Laravel Data DTOs (e.g., `ServerMetadata`).
88- **Enums/** — PHP enums (TitleCase keys). Key enums: `ProcessStatus`, `Role` (MEMBER/ADMIN/OWNER with rank comparison), `BuildPackTypes`, `ProxyTypes`, `ContainerStatusTypes`.
89- **Rules/** — Custom validation rules (`ValidGitRepositoryUrl`, `ValidServerIp`, `ValidHostname`, `DockerImageFormat`, etc.).
90
91### API Layer
92- REST API at `/api/v1/` with OpenAPI 3.0 attributes (`use OpenApi\Attributes as OA`) for auto-generated docs
93- Authentication via Laravel Sanctum with custom `ApiAbility` middleware for token abilities (read, write, deploy)
94- `ApiSensitiveData` middleware masks sensitive fields (IDs, credentials) in responses
95- API controllers in `app/Http/Controllers/Api/` use inline `Validator` (not Form Request classes)
96- Response serialization via `serializeApiResponse()` helper
97
98### Authorization
99- Policy-based authorization with ~15 model-to-policy mappings in `AuthServiceProvider`
100- Custom gates: `createAnyResource`, `canAccessTerminal`
101- Role hierarchy: `Role::MEMBER` (1) < `Role::ADMIN` (2) < `Role::OWNER` (3) with `lt()`/`gt()` comparison methods
102- Multi-tenancy via Teams — team auto-initializes notification settings on creation
103
104### Event Broadcasting
105- Soketi WebSocket server for real-time updates (ports 6001-6002 in dev)
106- Status change events: `ApplicationStatusChanged`, `ServiceStatusChanged`, `DatabaseStatusChanged`, `ProxyStatusChanged`
107- Livewire components subscribe to private team channels via `getListeners()`
108
109### Key Domain Concepts
110- **Server** — A managed host connected via SSH. Has settings, proxy config, and destinations.
111- **Application** — A deployed app (from Git or Docker image) with environment variables, previews, deployment queue.
112- **Service** — A pre-configured service stack from templates (`templates/service-templates-latest.json`).
113- **Standalone Databases** — Individual database instances (Postgres, MySQL, MariaDB, MongoDB, Redis, Clickhouse, KeyDB, Dragonfly).
114- **Project/Environment** — Organizational hierarchy: Team → Project → Environment → Resources.
115- **Proxy** — Traefik reverse proxy managed per server.
116
117### Frontend
118- Livewire 3 components with Alpine.js for client-side interactivity
119- Blade templates in `resources/views/livewire/`
120- Tailwind CSS v4 with `@tailwindcss/forms` and `@tailwindcss/typography`
121- Vite for asset bundling
122
123### Laravel 10 Structure (NOT Laravel 11+ slim structure)
124- Middleware in `app/Http/Middleware/` — custom middleware includes `CheckForcePasswordReset`, `DecideWhatToDoWithUser`, `ApiAbility`, `ApiSensitiveData`
125- Kernels: `app/Http/Kernel.php`, `app/Console/Kernel.php`
126- Exception handler: `app/Exceptions/Handler.php`
127- Service providers in `app/Providers/`
128
129## Key Conventions
130
131- Use `php artisan make:*` commands with `--no-interaction` to create files
132- Use Eloquent relationships, avoid `DB::` facade — prefer `Model::query()`
133- PHP 8.5: constructor property promotion, explicit return types, type hints
134- Validation uses inline `Validator` facade in controllers/Livewire components and custom rules in `app/Rules/` — not Form Request classes
135- Run `vendor/bin/pint --dirty --format agent` before finalizing changes
136- Every change must have tests — write or update tests, then run them. For bug fixes, follow TDD: write a failing test first, then fix the bug (see Test Enforcement below)
137- Check sibling files for conventions before creating new files
138
139## Git Workflow
140
141- Main branch: `v4.x`
142- Development branch: `next`
143- PRs should target `v4.x`
144
145<laravel-boost-guidelines>
146=== foundation rules ===
147
148# Laravel Boost Guidelines
149
150The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications.
151
152## Foundational Context
153
154This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.
155
156- php - 8.5
157- laravel/fortify (FORTIFY) - v1
158- laravel/framework (LARAVEL) - v12
159- laravel/horizon (HORIZON) - v5
160- laravel/mcp (MCP) - v0
161- laravel/nightwatch (NIGHTWATCH) - v1
162- laravel/pail (PAIL) - v1
163- laravel/prompts (PROMPTS) - v0
164- laravel/sanctum (SANCTUM) - v4
165- laravel/socialite (SOCIALITE) - v5
166- livewire/livewire (LIVEWIRE) - v3
167- laravel/boost (BOOST) - v2
168- laravel/dusk (DUSK) - v8
169- laravel/pint (PINT) - v1
170- laravel/telescope (TELESCOPE) - v5
171- pestphp/pest (PEST) - v4
172- phpunit/phpunit (PHPUNIT) - v12
173- rector/rector (RECTOR) - v2
174- tailwindcss (TAILWINDCSS) - v4
175
176## Skills Activation
177
178This project has domain-specific skills available in `**/skills/**`. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.
179
180## Conventions
181
182- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.
183- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.
184- Check for existing components to reuse before writing a new one.
185
186## Verification Scripts
187
188- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important.
189
190## Application Structure & Architecture
191
192- Stick to existing directory structure; don't create new base folders without approval.
193- Do not change the application's dependencies without approval.
194
195## Frontend Bundling
196
197- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them.
198
199## Documentation Files
200
201- You must only create documentation files if explicitly requested by the user.
202
203## Replies
204
205- Be concise in your explanations - focus on what's important rather than explaining obvious details.
206
207=== boost rules ===
208
209# Laravel Boost
210
211## Tools
212
213- Laravel Boost is an MCP server with tools designed specifically for this application. Prefer Boost tools over manual alternatives like shell commands or file reads.
214- Use `database-query` to run read-only queries against the database instead of writing raw SQL in tinker.
215- Use `database-schema` to inspect table structure before writing migrations or models.
216- Use `get-absolute-url` to resolve the correct scheme, domain, and port for project URLs. Always use this before sharing a URL with the user.
217- Use `browser-logs` to read browser logs, errors, and exceptions. Only recent logs are useful, ignore old entries.
218
219## Searching Documentation (IMPORTANT)
220
221- Always use `search-docs` before making code changes. Do not skip this step. It returns version-specific docs based on installed packages automatically.
222- Pass a `packages` array to scope results when you know which packages are relevant.
223- Use multiple broad, topic-based queries: `['rate limiting', 'routing rate limiting', 'routing']`. Expect the most relevant results first.
224- Do not add package names to queries because package info is already shared. Use `test resource table`, not `filament 4 test resource table`.
225
226### Search Syntax
227
2281. Use words for auto-stemmed AND logic: `rate limit` matches both "rate" AND "limit".
2292. Use `"quoted phrases"` for exact position matching: `"infinite scroll"` requires adjacent words in order.
2303. Combine words and phrases for mixed queries: `middleware "rate limit"`.
2314. Use multiple queries for OR logic: `queries=["authentication", "middleware"]`.
232
233## Artisan
234
235- Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters.
236- Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`.
237- Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory.
238
239## Tinker
240
241- Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code.
242- Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'`
243 - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'`
244
245=== php rules ===
246
247# PHP
248
249- Always use curly braces for control structures, even for single-line bodies.
250- Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private.
251- Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool`
252- Follow existing application Enum naming conventions.
253- Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic.
254- Use array shape type definitions in PHPDoc blocks.
255
256=== deployments rules ===
257
258# Deployment
259
260- Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications.
261
262=== tests rules ===
263
264# Test Enforcement
265
266- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
267- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter.
268
269=== laravel/core rules ===
270
271# Do Things the Laravel Way
272
273- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`.
274- If you're creating a generic PHP class, use `php artisan make:class`.
275- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
276
277### Model Creation
278
279- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options.
280
281## APIs & Eloquent Resources
282
283- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.
284
285## URL Generation
286
287- When generating links to other pages, prefer named routes and the `route()` function.
288
289## Testing
290
291- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
292- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
293- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
294
295## Vite Error
296
297- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.
298
299=== laravel/v12 rules ===
300
301# Laravel 12
302
303- CRITICAL: ALWAYS use `search-docs` tool for version-specific Laravel documentation and updated code examples.
304- This project upgraded from Laravel 10 without migrating to the new streamlined Laravel file structure.
305- This is perfectly fine and recommended by Laravel. Follow the existing structure from Laravel 10. We do not need to migrate to the new Laravel structure unless the user explicitly requests it.
306
307## Laravel 10 Structure
308
309- Middleware typically lives in `app/Http/Middleware/` and service providers in `app/Providers/`.
310- There is no `bootstrap/app.php` application configuration in a Laravel 10 structure:
311 - Middleware registration happens in `app/Http/Kernel.php`
312 - Exception handling is in `app/Exceptions/Handler.php`
313 - Console commands and schedule register in `app/Console/Kernel.php`
314 - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`
315
316## Database
317
318- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
319- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
320
321### Models
322
323- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.
324
325=== livewire/core rules ===
326
327# Livewire
328
329- Livewire allow to build dynamic, reactive interfaces in PHP without writing JavaScript.
330- You can use Alpine.js for client-side interactions instead of JavaScript frameworks.
331- Keep state server-side so the UI reflects it. Validate and authorize in actions as you would in HTTP requests.
332
333=== pint/core rules ===
334
335# Laravel Pint Code Formatter
336
337- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
338- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues.
339
340=== pest/core rules ===
341
342## Pest
343
344- This project uses Pest for testing. Create tests: `php artisan make:test --pest {name}`.
345- The `{name}` argument should not include the test suite directory. Use `php artisan make:test --pest SomeFeatureTest` instead of `php artisan make:test --pest Feature/SomeFeatureTest`.
346- Run tests: `php artisan test --compact` or filter: `php artisan test --compact --filter=testName`.
347- Do NOT delete tests without approval.
348
349</laravel-boost-guidelines>
350
coollabsio/coolify · .cursor/rules/coolify-ai-docs.mdc
@@ +1 @@
1---
2title: Coolify AI Documentation
3description: Master reference to all Coolify AI documentation in .ai/ directory
4globs: **/*
5alwaysApply: true
6---
7
8# Coolify AI Documentation
9
10All Coolify AI documentation has been consolidated in the **`.ai/`** directory for better organization and single source of truth.
11
12## Quick Start
13
14- **For Claude Code**: Start with `CLAUDE.md` in the root directory
15- **For Cursor IDE**: Start with `.ai/README.md` for navigation
16- **For All AI Tools**: Browse `.ai/` directory by topic
17
18## Documentation Structure
19
20All detailed documentation lives in `.ai/` with the following organization:
21
22### 📚 Core Documentation
23- **[Technology Stack](.ai/core/technology-stack.md)** - All versions, packages, dependencies (SINGLE SOURCE OF TRUTH for versions)
24- **[Project Overview](.ai/core/project-overview.md)** - What Coolify is, high-level architecture
25- **[Application Architecture](.ai/core/application-architecture.md)** - System design, components, relationships
26- **[Deployment Architecture](.ai/core/deployment-architecture.md)** - Deployment flows, Docker, proxies
27
28### 💻 Development
29- **[Development Workflow](.ai/development/development-workflow.md)** - Dev setup, commands, daily workflows
30- **[Testing Patterns](.ai/development/testing-patterns.md)** - How to write/run tests, Docker requirements
31- **[Laravel Boost](.ai/development/laravel-boost.md)** - Laravel-specific guidelines (SINGLE SOURCE for Laravel Boost)
32
33### 🎨 Code Patterns
34- **[Database Patterns](.ai/patterns/database-patterns.md)** - Eloquent, migrations, relationships
35- **[Frontend Patterns](.ai/patterns/frontend-patterns.md)** - Livewire, Alpine.js, Tailwind CSS
36- **[Security Patterns](.ai/patterns/security-patterns.md)** - Auth, authorization, security
37- **[Form Components](.ai/patterns/form-components.md)** - Enhanced forms with authorization
38- **[API & Routing](.ai/patterns/api-and-routing.md)** - API design, routing conventions
39
40### 📖 Meta
41- **[Maintaining Docs](.ai/meta/maintaining-docs.md)** - How to update/improve documentation
42- **[Sync Guide](.ai/meta/sync-guide.md)** - Keeping docs synchronized
43
44## Quick Decision Tree
45
46**What are you working on?**
47
48### Running Commands
49→ `.ai/development/development-workflow.md`
50- `npm run dev` / `npm run build` - Frontend
51- `php artisan serve` / `php artisan migrate` - Backend
52- `docker exec coolify php artisan test` - Feature tests (requires Docker)
53- `./vendor/bin/pest tests/Unit` - Unit tests (no Docker needed)
54- `./vendor/bin/pint` - Code formatting
55
56### Writing Tests
57→ `.ai/development/testing-patterns.md`
58- **Unit tests**: No database, use mocking, run outside Docker
59- **Feature tests**: Can use database, MUST run inside Docker
60- Critical: Docker execution requirements prevent database connection errors
61
62### Building UI
63→ `.ai/patterns/frontend-patterns.md` + `.ai/patterns/form-components.md`
64- Livewire 3.5.20 with server-side state
65- Alpine.js for client interactions
66- Tailwind CSS 4.1.4 styling
67- Form components with `canGate` authorization
68
69### Database Work
70→ `.ai/patterns/database-patterns.md`
71- Eloquent ORM patterns
72- Migration best practices
73- Relationship definitions
74- Query optimization
75
76### Security & Authorization
77→ `.ai/patterns/security-patterns.md` + `.ai/patterns/form-components.md`
78- Team-based access control
79- Policy and gate patterns
80- Form authorization (`canGate`, `canResource`)
81- API security with Sanctum
82
83### Laravel-Specific
84→ `.ai/development/laravel-boost.md`
85- Laravel 12.4.1 patterns
86- Livewire 3 best practices
87- Pest testing patterns
88- Laravel conventions
89
90### Version Numbers
91→ `.ai/core/technology-stack.md`
92- **SINGLE SOURCE OF TRUTH** for all version numbers
93- Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4, etc.
94- Never duplicate versions - always reference this file
95
96## Critical Patterns (Always Follow)
97
98### Testing Commands
99```bash
100# Unit tests (no database, outside Docker)
101./vendor/bin/pest tests/Unit
102
103# Feature tests (requires database, inside Docker)
104docker exec coolify php artisan test
105```
106
107**NEVER** run Feature tests outside Docker - they will fail with database connection errors.
108
109### Form Authorization
110ALWAYS include authorization on form components:
111```blade
112<x-forms.input canGate="update" :canResource="$resource" id="name" label="Name" />
113```
114
115### Livewire Components
116MUST have exactly ONE root element. No exceptions.
117
118### Version Numbers
119Use exact versions from `technology-stack.md`:
120- ✅ Laravel 12.4.1
121- ❌ Laravel 12 or "v12"
122
123### Code Style
124```bash
125# Always run before committing
126./vendor/bin/pint
127```
128
129## For AI Assistants
130
131### Important Notes
1321. **Single Source of Truth**: Each piece of information exists in ONE location only
1332. **Cross-Reference, Don't Duplicate**: Link to other files instead of copying content
1343. **Version Precision**: Always use exact versions from `technology-stack.md`
1354. **Docker for Feature Tests**: This is non-negotiable for database-dependent tests
1365. **Form Authorization**: Security requirement, not optional
137
138### When to Use Which File
139- **Quick commands**: `CLAUDE.md` or `development-workflow.md`
140- **Detailed patterns**: Topic-specific files in `.ai/patterns/`
141- **Testing**: `.ai/development/testing-patterns.md`
142- **Laravel specifics**: `.ai/development/laravel-boost.md`
143- **Versions**: `.ai/core/technology-stack.md`
144
145## Maintaining Documentation
146
147When updating documentation:
1481. Read `.ai/meta/maintaining-docs.md` first
1492. Follow single source of truth principle
1503. Update cross-references when moving content
1514. Test all links work
1525. See `.ai/meta/sync-guide.md` for sync guidelines
153
154## Migration Note
155
156This file replaces all previous `.cursor/rules/*.mdc` files. All content has been migrated to `.ai/` directory for better organization and to serve as single source of truth for all AI tools (Claude Code, Cursor IDE, etc.).
157
@@ −1 +1 @@
1−# AGENTS.md
1+---
2+title: Coolify AI Documentation
3+description: Master reference to all Coolify AI documentation in .ai/ directory
4+globs: **/*
5+alwaysApply: true
6+---
27
3−This file provides guidance to agentic coding tools when working with code in this repository.
8+# Coolify AI Documentation
49
5−## Project Overview
10+All Coolify AI documentation has been consolidated in the **`.ai/`** directory for better organization and single source of truth.
611
7−Coolify is an open-source, self-hostable PaaS (alternative to Heroku/Netlify/Vercel). It manages servers, applications, databases, and services via SSH. Built with Laravel 12 (using Laravel 10 file structure), Livewire 3, and Tailwind CSS v4.
12+## Quick Start
813
9−## Design Reference
14+- **For Claude Code**: Start with `CLAUDE.md` in the root directory
15+- **For Cursor IDE**: Start with `.ai/README.md` for navigation
16+- **For All AI Tools**: Browse `.ai/` directory by topic
1017
11−For UI/UX design specifications, principles, and visual standards, consult `DESIGN.md` in the [coollabsio/architecture](https://github.com/coollabsio/architecture) repo.
18+## Documentation Structure
1219
13−## Development Environment
20+All detailed documentation lives in `.ai/` with the following organization:
1421
15−Docker Compose-based dev setup with services: coolify (app), postgres, redis, soketi (WebSockets), vite, testing-host, mailpit, minio.
22+### 📚 Core Documentation
23+- **[Technology Stack](.ai/core/technology-stack.md)** - All versions, packages, dependencies (SINGLE SOURCE OF TRUTH for versions)
24+- **[Project Overview](.ai/core/project-overview.md)** - What Coolify is, high-level architecture
25+- **[Application Architecture](.ai/core/application-architecture.md)** - System design, components, relationships
26+- **[Deployment Architecture](.ai/core/deployment-architecture.md)** - Deployment flows, Docker, proxies
1627
17−```bash
18−# Start dev environment (uses docker-compose.dev.yml)
19−spin up # or: docker compose -f docker-compose.dev.yml up -d
20−spin down # stop services
21−```
28+### 💻 Development
29+- **[Development Workflow](.ai/development/development-workflow.md)** - Dev setup, commands, daily workflows
30+- **[Testing Patterns](.ai/development/testing-patterns.md)** - How to write/run tests, Docker requirements
31+- **[Laravel Boost](.ai/development/laravel-boost.md)** - Laravel-specific guidelines (SINGLE SOURCE for Laravel Boost)
2232
23−The app runs at `localhost:8000` by default. Vite dev server on port 5173.
33+### 🎨 Code Patterns
34+- **[Database Patterns](.ai/patterns/database-patterns.md)** - Eloquent, migrations, relationships
35+- **[Frontend Patterns](.ai/patterns/frontend-patterns.md)** - Livewire, Alpine.js, Tailwind CSS
36+- **[Security Patterns](.ai/patterns/security-patterns.md)** - Auth, authorization, security
37+- **[Form Components](.ai/patterns/form-components.md)** - Enhanced forms with authorization
38+- **[API & Routing](.ai/patterns/api-and-routing.md)** - API design, routing conventions
2439
25−## Common Commands
40+### 📖 Meta
41+- **[Maintaining Docs](.ai/meta/maintaining-docs.md)** - How to update/improve documentation
42+- **[Sync Guide](.ai/meta/sync-guide.md)** - Keeping docs synchronized
2643
27−```bash
28−# Tests (Pest 4)
29−php artisan test --compact # all tests
30−php artisan test --compact --filter=testName # single test
31−php artisan test --compact tests/Feature/SomeTest.php # specific file
44+## Quick Decision Tree
3245
33−# Code formatting (Pint, Laravel preset)
34−vendor/bin/pint --dirty --format agent # format changed files
46+**What are you working on?**
3547
36−# Frontend
37−npm run dev # vite dev server
38−npm run build # production build
39−```
48+### Running Commands
49+→ `.ai/development/development-workflow.md`
50+- `npm run dev` / `npm run build` - Frontend
51+- `php artisan serve` / `php artisan migrate` - Backend
52+- `docker exec coolify php artisan test` - Feature tests (requires Docker)
53+- `./vendor/bin/pest tests/Unit` - Unit tests (no Docker needed)
54+- `./vendor/bin/pint` - Code formatting
4055
41−## Browser Tests (Pest Browser Plugin)
56+### Writing Tests
57+→ `.ai/development/testing-patterns.md`
58+- **Unit tests**: No database, use mocking, run outside Docker
59+- **Feature tests**: Can use database, MUST run inside Docker
60+- Critical: Docker execution requirements prevent database connection errors
4261
43−Uses `pestphp/pest-plugin-browser` with Laravel Dusk 8. New browser tests go in `tests/v4/Browser/`.
62+### Building UI
63+→ `.ai/patterns/frontend-patterns.md` + `.ai/patterns/form-components.md`
64+- Livewire 3.5.20 with server-side state
65+- Alpine.js for client interactions
66+- Tailwind CSS 4.1.4 styling
67+- Form components with `canGate` authorization
4468
45−```bash
46−# Run all browser tests
47−php artisan test --compact tests/v4/Browser/
69+### Database Work
70+→ `.ai/patterns/database-patterns.md`
71+- Eloquent ORM patterns
72+- Migration best practices
73+- Relationship definitions
74+- Query optimization
4875
49−# Run a specific browser test file
50−php artisan test --compact tests/v4/Browser/LoginTest.php
76+### Security & Authorization
77+→ `.ai/patterns/security-patterns.md` + `.ai/patterns/form-components.md`
78+- Team-based access control
79+- Policy and gate patterns
80+- Form authorization (`canGate`, `canResource`)
81+- API security with Sanctum
5182
52−# Run a specific test by name
53−php artisan test --compact --filter='can login with valid credentials'
54−```
83+### Laravel-Specific
84+→ `.ai/development/laravel-boost.md`
85+- Laravel 12.4.1 patterns
86+- Livewire 3 best practices
87+- Pest testing patterns
88+- Laravel conventions
5589
56−### Writing Browser Tests
90+### Version Numbers
91+→ `.ai/core/technology-stack.md`
92+- **SINGLE SOURCE OF TRUTH** for all version numbers
93+- Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4, etc.
94+- Never duplicate versions - always reference this file
5795
58−- Place new tests in `tests/v4/Browser/` — legacy Dusk tests in `tests/Browser/` should not be used as reference.
59−- Use `RefreshDatabase` and seed required data (at minimum `InstanceSettings::create(['id' => 0])`) in `beforeEach`.
60−- Key API: `visit()`, `fill(field, value)`, `click(text)`, `assertSee()`, `assertDontSee()`, `assertPathIs()`, `screenshot()`.
61−- Always call `screenshot()` at the end of each test for debugging.
62−- For authenticated tests, create a helper function that logs in via the UI:
96+## Critical Patterns (Always Follow)
6397
64−```php
65−function loginAsRoot(): mixed
66−{
67− return visit('/login')
68− ->fill('email', 'test@example.com')
69− ->fill('password', 'password')
70− ->click('Login');
71−}
98+### Testing Commands
99+```bash
100+# Unit tests (no database, outside Docker)
101+./vendor/bin/pest tests/Unit
102+
103+# Feature tests (requires database, inside Docker)
104+docker exec coolify php artisan test
72105 ```
73106
74−- See `tests/v4/Browser/LoginTest.php`, `tests/v4/Browser/DashboardTest.php`, and `tests/v4/Browser/RegistrationTest.php` for conventions.
75−- Chrome driver runs on `localhost:4444`, app on `localhost:8000` (configured in `tests/DuskTestCase.php`).
76−- Legacy Dusk macros in `app/Providers/DuskServiceProvider.php` use the old `type()`/`press()` API — do not mix with Pest Browser Plugin's `fill()`/`click()` API.
107+**NEVER** run Feature tests outside Docker - they will fail with database connection errors.
77108
78−## Architecture
109+### Form Authorization
110+ALWAYS include authorization on form components:
111+```blade
112+<x-forms.input canGate="update" :canResource="$resource" id="name" label="Name" />
113+```
79114
80−### Backend Structure (app/)
81−- **Actions/** — Domain actions organized by area (Application, Database, Docker, Proxy, Server, Service, Shared, Stripe, User, CoolifyTask, Fortify). Uses `lorisleiva/laravel-actions` with `AsAction` trait — actions can be called as objects, dispatched as jobs, or used as controllers.
82−- **Livewire/** — All UI components (Livewire 3). Pages organized by domain: Server, Project, Settings, Security, Notifications, Terminal, Subscription, SharedVariables. This is the primary UI layer — no traditional Blade controllers. Components listen to private team channels for real-time status updates via Soketi.
83−- **Jobs/** — Queue jobs for deployments (`ApplicationDeploymentJob`), backups, Docker cleanup, server management, proxy configuration. Uses Redis queue with Horizon for monitoring.
84−- **Models/** — Eloquent models extending `BaseModel` which provides auto-CUID2 UUID generation. Key models: `Server`, `Application`, `Service`, `Project`, `Environment`, `Team`, plus standalone database models (`StandalonePostgresql`, `StandaloneMysql`, etc.). Common traits: `HasConfiguration`, `HasMetrics`, `HasSafeStringAttribute`, `ClearsGlobalSearchCache`.
85−- **Services/** — Business logic services (ConfigurationGenerator, DockerImageParser, ContainerStatusAggregator, HetznerService, etc.). Use Services for complex orchestration; use Actions for single-purpose domain operations.
86−- **Helpers/** — Global helpers loaded via `bootstrap/includeHelpers.php` from `bootstrap/helpers/` — organized into `shared.php`, `constants.php`, `versions.php`, `subscriptions.php`, `domains.php`, `docker.php`, `services.php`, `github.php`, `proxy.php`, `notifications.php`.
87−- **Data/** — Spatie Laravel Data DTOs (e.g., `ServerMetadata`).
88−- **Enums/** — PHP enums (TitleCase keys). Key enums: `ProcessStatus`, `Role` (MEMBER/ADMIN/OWNER with rank comparison), `BuildPackTypes`, `ProxyTypes`, `ContainerStatusTypes`.
89−- **Rules/** — Custom validation rules (`ValidGitRepositoryUrl`, `ValidServerIp`, `ValidHostname`, `DockerImageFormat`, etc.).
115+### Livewire Components
116+MUST have exactly ONE root element. No exceptions.
90117
91−### API Layer
92−- REST API at `/api/v1/` with OpenAPI 3.0 attributes (`use OpenApi\Attributes as OA`) for auto-generated docs
93−- Authentication via Laravel Sanctum with custom `ApiAbility` middleware for token abilities (read, write, deploy)
94−- `ApiSensitiveData` middleware masks sensitive fields (IDs, credentials) in responses
95−- API controllers in `app/Http/Controllers/Api/` use inline `Validator` (not Form Request classes)
96−- Response serialization via `serializeApiResponse()` helper
118+### Version Numbers
119+Use exact versions from `technology-stack.md`:
120+- ✅ Laravel 12.4.1
121+- ❌ Laravel 12 or "v12"
97122
98−### Authorization
99−- Policy-based authorization with ~15 model-to-policy mappings in `AuthServiceProvider`
100−- Custom gates: `createAnyResource`, `canAccessTerminal`
101−- Role hierarchy: `Role::MEMBER` (1) < `Role::ADMIN` (2) < `Role::OWNER` (3) with `lt()`/`gt()` comparison methods
102−- Multi-tenancy via Teams — team auto-initializes notification settings on creation
123+### Code Style
124+```bash
125+# Always run before committing
126+./vendor/bin/pint
127+```
103128
104−### Event Broadcasting
105−- Soketi WebSocket server for real-time updates (ports 6001-6002 in dev)
106−- Status change events: `ApplicationStatusChanged`, `ServiceStatusChanged`, `DatabaseStatusChanged`, `ProxyStatusChanged`
107−- Livewire components subscribe to private team channels via `getListeners()`
129+## For AI Assistants
108130
109−### Key Domain Concepts
110−- **Server** — A managed host connected via SSH. Has settings, proxy config, and destinations.
111−- **Application** — A deployed app (from Git or Docker image) with environment variables, previews, deployment queue.
112−- **Service** — A pre-configured service stack from templates (`templates/service-templates-latest.json`).
113−- **Standalone Databases** — Individual database instances (Postgres, MySQL, MariaDB, MongoDB, Redis, Clickhouse, KeyDB, Dragonfly).
114−- **Project/Environment** — Organizational hierarchy: Team → Project → Environment → Resources.
115−- **Proxy** — Traefik reverse proxy managed per server.
131+### Important Notes
132+1. **Single Source of Truth**: Each piece of information exists in ONE location only
133+2. **Cross-Reference, Don't Duplicate**: Link to other files instead of copying content
134+3. **Version Precision**: Always use exact versions from `technology-stack.md`
135+4. **Docker for Feature Tests**: This is non-negotiable for database-dependent tests
136+5. **Form Authorization**: Security requirement, not optional
116137
117−### Frontend
118−- Livewire 3 components with Alpine.js for client-side interactivity
119−- Blade templates in `resources/views/livewire/`
120−- Tailwind CSS v4 with `@tailwindcss/forms` and `@tailwindcss/typography`
121−- Vite for asset bundling
138+### When to Use Which File
139+- **Quick commands**: `CLAUDE.md` or `development-workflow.md`
140+- **Detailed patterns**: Topic-specific files in `.ai/patterns/`
141+- **Testing**: `.ai/development/testing-patterns.md`
142+- **Laravel specifics**: `.ai/development/laravel-boost.md`
143+- **Versions**: `.ai/core/technology-stack.md`
122144
123−### Laravel 10 Structure (NOT Laravel 11+ slim structure)
124−- Middleware in `app/Http/Middleware/` — custom middleware includes `CheckForcePasswordReset`, `DecideWhatToDoWithUser`, `ApiAbility`, `ApiSensitiveData`
125−- Kernels: `app/Http/Kernel.php`, `app/Console/Kernel.php`
126−- Exception handler: `app/Exceptions/Handler.php`
127−- Service providers in `app/Providers/`
145+## Maintaining Documentation
128146
129−## Key Conventions
147+When updating documentation:
148+1. Read `.ai/meta/maintaining-docs.md` first
149+2. Follow single source of truth principle
150+3. Update cross-references when moving content
151+4. Test all links work
152+5. See `.ai/meta/sync-guide.md` for sync guidelines
130153
131−- Use `php artisan make:*` commands with `--no-interaction` to create files
132−- Use Eloquent relationships, avoid `DB::` facade — prefer `Model::query()`
133−- PHP 8.5: constructor property promotion, explicit return types, type hints
134−- Validation uses inline `Validator` facade in controllers/Livewire components and custom rules in `app/Rules/` — not Form Request classes
135−- Run `vendor/bin/pint --dirty --format agent` before finalizing changes
136−- Every change must have tests — write or update tests, then run them. For bug fixes, follow TDD: write a failing test first, then fix the bug (see Test Enforcement below)
137−- Check sibling files for conventions before creating new files
154+## Migration Note
138155
139−## Git Workflow
140−
141−- Main branch: `v4.x`
142−- Development branch: `next`
143−- PRs should target `v4.x`
144−
145−<laravel-boost-guidelines>
146−=== foundation rules ===
147−
148−# Laravel Boost Guidelines
149−
150−The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to ensure the best experience when building Laravel applications.
151−
152−## Foundational Context
153−
154−This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.
155−
156−- php - 8.5
157−- laravel/fortify (FORTIFY) - v1
158−- laravel/framework (LARAVEL) - v12
159−- laravel/horizon (HORIZON) - v5
160−- laravel/mcp (MCP) - v0
161−- laravel/nightwatch (NIGHTWATCH) - v1
162−- laravel/pail (PAIL) - v1
163−- laravel/prompts (PROMPTS) - v0
164−- laravel/sanctum (SANCTUM) - v4
165−- laravel/socialite (SOCIALITE) - v5
166−- livewire/livewire (LIVEWIRE) - v3
167−- laravel/boost (BOOST) - v2
168−- laravel/dusk (DUSK) - v8
169−- laravel/pint (PINT) - v1
170−- laravel/telescope (TELESCOPE) - v5
171−- pestphp/pest (PEST) - v4
172−- phpunit/phpunit (PHPUNIT) - v12
173−- rector/rector (RECTOR) - v2
174−- tailwindcss (TAILWINDCSS) - v4
175−
176−## Skills Activation
177−
178−This project has domain-specific skills available in `**/skills/**`. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.
179−
180−## Conventions
181−
182−- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.
183−- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.
184−- Check for existing components to reuse before writing a new one.
185−
186−## Verification Scripts
187−
188−- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important.
189−
190−## Application Structure & Architecture
191−
192−- Stick to existing directory structure; don't create new base folders without approval.
193−- Do not change the application's dependencies without approval.
194−
195−## Frontend Bundling
196−
197−- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `npm run build`, `npm run dev`, or `composer run dev`. Ask them.
198−
199−## Documentation Files
200−
201−- You must only create documentation files if explicitly requested by the user.
202−
203−## Replies
204−
205−- Be concise in your explanations - focus on what's important rather than explaining obvious details.
206−
207−=== boost rules ===
208−
209−# Laravel Boost
210−
211−## Tools
212−
213−- Laravel Boost is an MCP server with tools designed specifically for this application. Prefer Boost tools over manual alternatives like shell commands or file reads.
214−- Use `database-query` to run read-only queries against the database instead of writing raw SQL in tinker.
215−- Use `database-schema` to inspect table structure before writing migrations or models.
216−- Use `get-absolute-url` to resolve the correct scheme, domain, and port for project URLs. Always use this before sharing a URL with the user.
217−- Use `browser-logs` to read browser logs, errors, and exceptions. Only recent logs are useful, ignore old entries.
218−
219−## Searching Documentation (IMPORTANT)
220−
221−- Always use `search-docs` before making code changes. Do not skip this step. It returns version-specific docs based on installed packages automatically.
222−- Pass a `packages` array to scope results when you know which packages are relevant.
223−- Use multiple broad, topic-based queries: `['rate limiting', 'routing rate limiting', 'routing']`. Expect the most relevant results first.
224−- Do not add package names to queries because package info is already shared. Use `test resource table`, not `filament 4 test resource table`.
225−
226−### Search Syntax
227−
228−1. Use words for auto-stemmed AND logic: `rate limit` matches both "rate" AND "limit".
229−2. Use `"quoted phrases"` for exact position matching: `"infinite scroll"` requires adjacent words in order.
230−3. Combine words and phrases for mixed queries: `middleware "rate limit"`.
231−4. Use multiple queries for OR logic: `queries=["authentication", "middleware"]`.
232−
233−## Artisan
234−
235−- Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters.
236−- Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`.
237−- Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory.
238−
239−## Tinker
240−
241−- Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code.
242−- Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'`
243− - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'`
244−
245−=== php rules ===
246−
247−# PHP
248−
249−- Always use curly braces for control structures, even for single-line bodies.
250−- Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private.
251−- Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool`
252−- Follow existing application Enum naming conventions.
253−- Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic.
254−- Use array shape type definitions in PHPDoc blocks.
255−
256−=== deployments rules ===
257−
258−# Deployment
259−
260−- Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications.
261−
262−=== tests rules ===
263−
264−# Test Enforcement
265−
266−- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
267−- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter.
268−
269−=== laravel/core rules ===
270−
271−# Do Things the Laravel Way
272−
273−- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`.
274−- If you're creating a generic PHP class, use `php artisan make:class`.
275−- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
276−
277−### Model Creation
278−
279−- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options.
280−
281−## APIs & Eloquent Resources
282−
283−- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.
284−
285−## URL Generation
286−
287−- When generating links to other pages, prefer named routes and the `route()` function.
288−
289−## Testing
290−
291−- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
292−- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
293−- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
294−
295−## Vite Error
296−
297−- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.
298−
299−=== laravel/v12 rules ===
300−
301−# Laravel 12
302−
303−- CRITICAL: ALWAYS use `search-docs` tool for version-specific Laravel documentation and updated code examples.
304−- This project upgraded from Laravel 10 without migrating to the new streamlined Laravel file structure.
305−- This is perfectly fine and recommended by Laravel. Follow the existing structure from Laravel 10. We do not need to migrate to the new Laravel structure unless the user explicitly requests it.
306−
307−## Laravel 10 Structure
308−
309−- Middleware typically lives in `app/Http/Middleware/` and service providers in `app/Providers/`.
310−- There is no `bootstrap/app.php` application configuration in a Laravel 10 structure:
311− - Middleware registration happens in `app/Http/Kernel.php`
312− - Exception handling is in `app/Exceptions/Handler.php`
313− - Console commands and schedule register in `app/Console/Kernel.php`
314− - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`
315−
316−## Database
317−
318−- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
319−- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
320−
321−### Models
322−
323−- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.
324−
325−=== livewire/core rules ===
326−
327−# Livewire
328−
329−- Livewire allow to build dynamic, reactive interfaces in PHP without writing JavaScript.
330−- You can use Alpine.js for client-side interactions instead of JavaScript frameworks.
331−- Keep state server-side so the UI reflects it. Validate and authorize in actions as you would in HTTP requests.
332−
333−=== pint/core rules ===
334−
335−# Laravel Pint Code Formatter
336−
337−- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
338−- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues.
339−
340−=== pest/core rules ===
341−
342−## Pest
343−
344−- This project uses Pest for testing. Create tests: `php artisan make:test --pest {name}`.
345−- The `{name}` argument should not include the test suite directory. Use `php artisan make:test --pest SomeFeatureTest` instead of `php artisan make:test --pest Feature/SomeFeatureTest`.
346−- Run tests: `php artisan test --compact` or filter: `php artisan test --compact --filter=testName`.
347−- Do NOT delete tests without approval.
348−
349−</laravel-boost-guidelines>
156+This file replaces all previous `.cursor/rules/*.mdc` files. All content has been migrated to `.ai/` directory for better organization and to serve as single source of truth for all AI tools (Claude Code, Cursor IDE, etc.).
350157
