# 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