Current state

.copilot/inctructions.md

@@ -0,0 +1,293 @@
+# Copilot Instructions – Artworks Module (SkinBase)
+
+> **This file defines HOW Copilot must generate code.**
+> It is a strict instruction set.
+> If there is a conflict between generated code and these rules,
+> **these rules override everything.**
+
+---
+
+## 1. Global Rules (MANDATORY)
+
+Copilot MUST:
+
+* Target **Laravel 12**
+* Use **PHP 8.3+ syntax**
+* Follow **Eloquent best practices**
+* Respect **SoftDeletes**
+* Respect **FK relationships**
+* Generate **clean, readable, maintainable code**
+
+Copilot MUST NOT:
+
+* Reference legacy tables (`wallz`, old categories, old views)
+* Generate MyISAM tables
+* Generate hard deletes for user content
+* Put counters on hot tables
+* Use IDs in URLs
+* Mix responsibilities across models
+
+---
+
+## 2. Authoritative Schema Reference
+
+The canonical schema for artworks is defined in:
+
+```
+.copilot/artworks.md
+```
+
+Copilot MUST:
+
+* Read this file before generating any code
+* Match table names, columns, relations exactly
+* Never invent fields or tables unless explicitly allowed
+
+---
+
+## 3. Models Generation Rules
+
+When generating Eloquent models:
+
+### Required models
+
+Copilot MUST generate:
+
+* `App\Models\Artwork`
+* `App\Models\ArtworkTranslation`
+* `App\Models\ArtworkStats`
+* `App\Models\ArtworkComment`
+* `App\Models\ArtworkDownload`
+
+### Model requirements
+
+Each model MUST:
+
+* Declare `$fillable`
+* Define all relationships
+* Use `SoftDeletes` **only when allowed**
+* Include PHPDoc blocks for relations
+* Use type-hinted return values
+
+### Forbidden
+
+Copilot MUST NOT:
+
+* Add business logic into models
+* Perform stat mutations in models
+* Use observers unless explicitly requested
+
+---
+
+## 4. Relationships (STRICT)
+
+Copilot MUST implement these exact relations:
+
+### Artwork
+
+```php
+belongsTo(User::class)
+hasMany(ArtworkTranslation::class)
+hasOne(ArtworkStats::class)
+belongsToMany(Category::class)
+hasMany(ArtworkComment::class)
+hasMany(ArtworkDownload::class)
+```
+
+### ArtworkTranslation
+
+```php
+belongsTo(Artwork::class)
+```
+
+### ArtworkStats
+
+```php
+belongsTo(Artwork::class)
+```
+
+### ArtworkComment
+
+```php
+belongsTo(Artwork::class)
+belongsTo(User::class)
+```
+
+### ArtworkDownload
+
+```php
+belongsTo(Artwork::class)
+```
+
+---
+
+## 5. Query & Scope Rules
+
+Copilot MUST define these scopes on `Artwork`:
+
+```php
+scopePublic($query)
+scopeApproved($query)
+scopePublished($query)
+```
+
+Public queries MUST always include:
+
+```php
+deleted_at IS NULL
+is_public = true
+is_approved = true
+```
+
+Copilot MUST NOT:
+
+* Eager-load stats in list views
+* Use `offset` pagination for feeds
+* Load unnecessary relations by default
+
+---
+
+## 6. Controller Generation Rules
+
+When generating controllers:
+
+Copilot MUST:
+
+* Use **thin controllers**
+* Delegate logic to services/actions if needed
+* Validate input using Form Requests
+* Use route-model binding with `slug`
+* Handle soft-deleted content properly
+
+Copilot MUST NOT:
+
+* Query raw DB tables directly
+* Bypass scopes
+* Return unfiltered content
+
+---
+
+## 7. Routing Rules
+
+Routes MUST:
+
+* Use **slug-based routing**
+* Never expose numeric IDs
+* Respect category hierarchy
+* Be SEO-friendly
+
+Example (valid):
+
+```
+/photography/abstract/dark/night-city
+```
+
+Invalid:
+
+```
+/artwork/123
+```
+
+---
+
+## 8. Soft Delete Rules
+
+Copilot MUST:
+
+* Use `delete()` (soft delete) for user content
+* Use `restore()` for recovery
+* Use `forceDelete()` **only** when explicitly requested
+
+When content is soft-deleted:
+
+* It must disappear from public browsing
+* It must remain accessible to admins
+
+---
+
+## 9. Stats & High-Load Rules
+
+Copilot MUST:
+
+* Treat stats as **derived data**
+* Update stats via jobs / services
+* Never increment counters inline in controllers
+* Assume Redis may be present
+
+Copilot MUST NOT:
+
+* Store counters on `artworks`
+* Use `increment()` directly on hot rows
+
+---
+
+## 10. Search Rules
+
+Copilot MAY:
+
+* Use MySQL FULLTEXT
+* Use external search engines (if requested)
+
+Copilot MUST NOT:
+
+* Search file paths
+* Search binary metadata
+* Assume Elasticsearch exists unless specified
+
+---
+
+## 11. Forbidden Patterns (NEVER GENERATE)
+
+❌ Hard deletes on artworks
+❌ Legacy column names
+❌ Polymorphic abuse
+❌ Fat controllers
+❌ Magic numbers
+❌ Inline SQL in controllers
+❌ Business logic in migrations
+
+---
+
+## 12. Extension Rules
+
+Copilot MAY generate new features ONLY if:
+
+* They do not modify core tables
+* They follow the same architectural principles
+* They are isolated in new tables/services
+
+Allowed examples:
+
+* tags
+* EXIF metadata
+* versioning
+* reporting/flagging
+* API resources
+
+---
+
+## 13. Error Handling
+
+Copilot MUST:
+
+* Throw meaningful exceptions
+* Return proper HTTP codes
+* Use 404 for missing public content
+* Use 410 or 301 for deleted content (if requested)
+
+---
+
+## 14. Final Instruction (ABSOLUTE)
+
+> **Copilot must treat this file and `artworks.md`
+> as non-negotiable contracts.**
+
+If unsure:
+
+* ask for clarification
+* do NOT guess
+* do NOT invent schema
+
+---
+
+### ✅ End of Copilot Instructions