v4.0.0-beta.445 (#7257)

Author: andrasbacsai

.AI_INSTRUCTIONS_SYNC.md

@@ -1,156 +1,41 @@
 # AI Instructions Synchronization Guide
 
-This document explains how AI instructions are organized and synchronized across different AI tools used with Coolify.
+**This file has moved!**
 
-## Overview
+All AI documentation and synchronization guidelines are now in the `.ai/` directory.
 
-Coolify maintains AI instructions in two parallel systems:
+## New Locations
 
-1. **CLAUDE.md** - For Claude Code (claude.ai/code)
-2. **.cursor/rules/** - For Cursor IDE and other AI assistants
+- **Sync Guide**: [.ai/meta/sync-guide.md](.ai/meta/sync-guide.md)
+- **Maintaining Docs**: [.ai/meta/maintaining-docs.md](.ai/meta/maintaining-docs.md)
+- **Documentation Hub**: [.ai/README.md](.ai/README.md)
 
-Both systems share core principles but are optimized for their respective workflows.
+## Quick Overview
 
-## Structure
-
-### CLAUDE.md
-- **Purpose**: Condensed, workflow-focused guide for Claude Code
-- **Format**: Single markdown file
-- **Includes**:
-  - Quick-reference development commands
-  - High-level architecture overview
-  - Core patterns and guidelines
-  - Embedded Laravel Boost guidelines
-  - References to detailed .cursor/rules/ documentation
-
-### .cursor/rules/
-- **Purpose**: Detailed, topic-specific documentation
-- **Format**: Multiple .mdc files organized by topic
-- **Structure**:
-  - `README.mdc` - Main index and overview
-  - `cursor_rules.mdc` - Maintenance guidelines
-  - Topic-specific files (testing-patterns.mdc, security-patterns.mdc, etc.)
-- **Used by**: Cursor IDE, Claude Code (for detailed reference), other AI assistants
-
-## Cross-References
-
-Both systems reference each other:
-
-- **CLAUDE.md** → references `.cursor/rules/` for detailed documentation
-- **.cursor/rules/README.mdc** → references `CLAUDE.md` for Claude Code workflow
-- **.cursor/rules/cursor_rules.mdc** → notes that changes should sync with CLAUDE.md
-
-## Maintaining Consistency
-
-When updating AI instructions, follow these guidelines:
-
-### 1. Core Principles (MUST be consistent)
-- Laravel version (currently Laravel 12)
-- PHP version (8.4)
-- Testing execution rules (Docker for Feature tests, mocking for Unit tests)
-- Security patterns and authorization requirements
-- Code style requirements (Pint, PSR-12)
-
-### 2. Where to Make Changes
-
-**For workflow changes** (how to run commands, development setup):
-- Primary: `CLAUDE.md`
-- Secondary: `.cursor/rules/development-workflow.mdc`
-
-**For architectural patterns** (how code should be structured):
-- Primary: `.cursor/rules/` topic files
-- Secondary: Reference in `CLAUDE.md` "Additional Documentation" section
-
-**For testing patterns**:
-- Both: Must be synchronized
-- `CLAUDE.md` - Contains condensed testing execution rules
-- `.cursor/rules/testing-patterns.mdc` - Contains detailed examples and patterns
-
-### 3. Update Checklist
-
-When making significant changes:
-
-- [ ] Identify if change affects core principles (version numbers, critical patterns)
-- [ ] Update primary location (CLAUDE.md or .cursor/rules/)
-- [ ] Check if update affects cross-referenced content
-- [ ] Update secondary location if needed
-- [ ] Verify cross-references are still accurate
-- [ ] Run: `./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc` (if applicable)
-
-### 4. Common Inconsistencies to Watch
-
-- **Version numbers**: Laravel, PHP, package versions
-- **Testing instructions**: Docker execution requirements
-- **File paths**: Ensure relative paths work from root
-- **Command syntax**: Docker commands, artisan commands
-- **Architecture decisions**: Laravel 10 structure vs Laravel 12+ structure
-
-## File Organization
+All AI instructions are now organized in `.ai/` directory:
 
 ```
-/
-├── CLAUDE.md                          # Claude Code instructions (condensed)
-├── .AI_INSTRUCTIONS_SYNC.md          # This file
-└── .cursor/
-    └── rules/
-        ├── README.mdc                 # Index and overview
-        ├── cursor_rules.mdc           # Maintenance guide
-        ├── testing-patterns.mdc       # Testing details
-        ├── development-workflow.mdc   # Dev setup details
-        ├── security-patterns.mdc      # Security details
-        ├── application-architecture.mdc
-        ├── deployment-architecture.mdc
-        ├── database-patterns.mdc
-        ├── frontend-patterns.mdc
-        ├── api-and-routing.mdc
-        ├── form-components.mdc
-        ├── technology-stack.mdc
-        ├── project-overview.mdc
-        └── laravel-boost.mdc          # Laravel-specific patterns
+.ai/
+├── README.md                    # Navigation hub
+├── core/                        # Project information
+├── development/                 # Dev workflows
+├── patterns/                    # Code patterns
+└── meta/                       # Documentation guides
 ```
 
-## Recent Updates
-
-### 2025-10-07
-- ✅ Added cross-references between CLAUDE.md and .cursor/rules/
-- ✅ Synchronized Laravel version (12) across all files
-- ✅ Added comprehensive testing execution rules (Docker for Feature tests)
-- ✅ Added test design philosophy (prefer mocking over database)
-- ✅ Fixed inconsistencies in testing documentation
-- ✅ Created this synchronization guide
-
-## Maintenance Commands
-
-```bash
-# Check for version inconsistencies
-grep -r "Laravel [0-9]" CLAUDE.md .cursor/rules/*.mdc
-
-# Check for PHP version consistency
-grep -r "PHP [0-9]" CLAUDE.md .cursor/rules/*.mdc
-
-# Format all documentation
-./vendor/bin/pint CLAUDE.md .cursor/rules/*.mdc
-
-# Search for specific patterns across all docs
-grep -r "pattern_to_check" CLAUDE.md .cursor/rules/
-```
-
-## Contributing
-
-When contributing documentation:
+### For AI Assistants
 
-1. Check both CLAUDE.md and .cursor/rules/ for existing documentation
-2. Add to appropriate location(s) based on guidelines above
-3. Add cross-references if creating new patterns
-4. Update this file if changing organizational structure
-5. Verify consistency before submitting PR
+- **Claude Code**: Use `CLAUDE.md` (references `.ai/` files)
+- **Cursor IDE**: Use `.cursor/rules/coolify-ai-docs.mdc` (references `.ai/` files)
+- **All Tools**: Browse `.ai/` directory for detailed documentation
 
-## Questions?
+### Key Principles
 
-If unsure about where to document something:
+1. **Single Source of Truth**: Each piece of information exists in ONE file only
+2. **Cross-Reference**: Other files reference the source, don't duplicate
+3. **Organized by Topic**: Core, Development, Patterns, Meta
+4. **Version Consistency**: All versions in `.ai/core/technology-stack.md`
 
-- **Quick reference / workflow** → CLAUDE.md
-- **Detailed patterns / examples** → .cursor/rules/[topic].mdc
-- **Both?** → Start with .cursor/rules/, then reference in CLAUDE.md
+## For More Information
 
-When in doubt, prefer detailed documentation in .cursor/rules/ and concise references in CLAUDE.md.
+See [.ai/meta/sync-guide.md](.ai/meta/sync-guide.md) for complete synchronization guidelines and [.ai/meta/maintaining-docs.md](.ai/meta/maintaining-docs.md) for documentation maintenance instructions.

.ai/README.md

@@ -0,0 +1,148 @@
+# Coolify AI Documentation
+
+Welcome to the Coolify AI documentation hub. This directory contains all AI assistant instructions organized by topic for easy navigation and maintenance.
+
+## Quick Start
+
+- **For Claude Code**: Start with [CLAUDE.md in root directory](../CLAUDE.md)
+- **For Cursor IDE**: Check `.cursor/rules/coolify-ai-docs.mdc` which references this directory
+- **For Other AI Tools**: Continue reading below
+
+## Documentation Structure
+
+### 📚 Core Documentation
+Essential project information and architecture:
+
+- **[Technology Stack](core/technology-stack.md)** - All versions, packages, and dependencies (Laravel 12.4.1, PHP 8.4.7, etc.)
+- **[Project Overview](core/project-overview.md)** - What Coolify is and how it works
+- **[Application Architecture](core/application-architecture.md)** - System design and component relationships
+- **[Deployment Architecture](core/deployment-architecture.md)** - How deployments work end-to-end, including Coolify Docker Compose extensions (custom fields)
+
+### 💻 Development
+Day-to-day development practices:
+
+- **[Workflow](development/development-workflow.md)** - Development setup, commands, and daily workflows
+- **[Testing Patterns](development/testing-patterns.md)** - How to write and run tests (Unit vs Feature, Docker requirements)
+- **[Laravel Boost](development/laravel-boost.md)** - Laravel-specific guidelines and best practices
+
+### 🎨 Patterns
+Code patterns and best practices by domain:
+
+- **[Database Patterns](patterns/database-patterns.md)** - Eloquent, migrations, relationships
+- **[Frontend Patterns](patterns/frontend-patterns.md)** - Livewire, Alpine.js, Tailwind CSS
+- **[Security Patterns](patterns/security-patterns.md)** - Authentication, authorization, security best practices
+- **[Form Components](patterns/form-components.md)** - Enhanced form components with authorization
+- **[API & Routing](patterns/api-and-routing.md)** - API design, routing conventions, REST patterns
+
+### 📖 Meta
+Documentation about documentation:
+
+- **[Maintaining Docs](meta/maintaining-docs.md)** - How to update and improve this documentation
+- **[Sync Guide](meta/sync-guide.md)** - Keeping documentation synchronized across tools
+
+## Quick Decision Tree
+
+**What do you need help with?**
+
+### Running Commands
+→ [development/development-workflow.md](development/development-workflow.md)
+- Frontend: `npm run dev`, `npm run build`
+- Backend: `php artisan serve`, `php artisan migrate`
+- Tests: Docker for Feature tests, mocking for Unit tests
+- Code quality: `./vendor/bin/pint`, `./vendor/bin/phpstan`
+
+### Writing Tests
+→ [development/testing-patterns.md](development/testing-patterns.md)
+- **Unit tests**: No database, use mocking, run outside Docker
+- **Feature tests**: Can use database, must run inside Docker
+- Command: `docker exec coolify php artisan test`
+
+### Building UI
+→ [patterns/frontend-patterns.md](patterns/frontend-patterns.md) or [patterns/form-components.md](patterns/form-components.md)
+- Livewire components with server-side state
+- Alpine.js for client-side interactivity
+- Tailwind CSS 4.1.4 for styling
+- Form components with built-in authorization
+
+### Database Work
+→ [patterns/database-patterns.md](patterns/database-patterns.md)
+- Eloquent ORM patterns
+- Migration best practices
+- Relationship definitions
+- Query optimization
+
+### Security & Auth
+→ [patterns/security-patterns.md](patterns/security-patterns.md)
+- Team-based access control
+- Policy and gate patterns
+- Form authorization (canGate, canResource)
+- API security
+
+### Laravel-Specific Questions
+→ [development/laravel-boost.md](development/laravel-boost.md)
+- Laravel 12 patterns
+- Livewire 3 best practices
+- Pest testing patterns
+- Laravel conventions
+
+### Docker Compose Extensions
+→ [core/deployment-architecture.md](core/deployment-architecture.md#coolify-docker-compose-extensions)
+- Custom fields: `exclude_from_hc`, `content`, `isDirectory`
+- How to use inline file content
+- Health check exclusion patterns
+- Volume creation control
+
+### Version Numbers
+→ [core/technology-stack.md](core/technology-stack.md)
+- **Single source of truth** for all version numbers
+- Don't duplicate versions elsewhere, reference this file
+
+## Navigation Tips
+
+1. **Start broad**: Begin with project-overview or ../CLAUDE.md
+2. **Get specific**: Navigate to topic-specific files for details
+3. **Cross-reference**: Files link to related topics
+4. **Single source**: Version numbers and critical data exist in ONE place only
+
+## For AI Assistants
+
+### Important Patterns to Follow
+
+**Testing Commands:**
+- Unit tests: `./vendor/bin/pest tests/Unit` (no database, outside Docker)
+- Feature tests: `docker exec coolify php artisan test` (requires database, inside Docker)
+- NEVER run Feature tests outside Docker - they will fail with database connection errors
+
+**Version Numbers:**
+- Always use exact versions from [technology-stack.md](core/technology-stack.md)
+- Laravel 12.4.1, PHP 8.4.7, Tailwind 4.1.4
+- Don't use "v12" or "8.4" - be precise
+
+**Form Authorization:**
+- ALWAYS include `canGate` and `:canResource` on form components
+- See [form-components.md](patterns/form-components.md) for examples
+
+**Livewire Components:**
+- MUST have exactly ONE root element
+- See [frontend-patterns.md](patterns/frontend-patterns.md) for details
+
+**Code Style:**
+- Run `./vendor/bin/pint` before finalizing changes
+- Follow PSR-12 standards
+- Use PHP 8.4 features (constructor promotion, typed properties, etc.)
+
+## Contributing
+
+When updating documentation:
+1. Read [meta/maintaining-docs.md](meta/maintaining-docs.md)
+2. Follow the single source of truth principle
+3. Update cross-references when moving content
+4. Test all links work
+5. Run Pint on markdown files if applicable
+
+## Questions?
+
+- **Claude Code users**: Check [../CLAUDE.md](../CLAUDE.md) first
+- **Cursor IDE users**: Check `.cursor/rules/coolify-ai-docs.mdc`
+- **Documentation issues**: See [meta/maintaining-docs.md](meta/maintaining-docs.md)
+- **Sync issues**: See [meta/sync-guide.md](meta/sync-guide.md)