Current state

.copilot/skinbase-category-links.md

@@ -0,0 +1,240 @@
+# SkinBase – Category Link Building (AUTHORITATIVE SPEC)
+
+This document defines the **ONLY valid way** to build public category and artwork URLs in SkinBase.
+Copilot AI Agent MUST follow this specification exactly.
+
+---
+
+## 🎯 Goal
+
+- SEO-friendly URLs
+- No numeric IDs in public routes
+- Unlimited category depth
+- Predictable and deterministic link building
+- One canonical URL per resource
+
+---
+
+## 🚫 Forbidden Concepts
+
+Copilot MUST NOT:
+- expose numeric IDs in URLs
+- use legacy paths (`/Photography/3`)
+- infer hierarchy from URL text
+- mix `content_type_id` and `parent_id`
+- create alternative URL formats
+- generate uppercase URLs
+
+---
+
+## 🧱 Data Model (Authoritative)
+
+### content_types
+- `id`
+- `slug` → FIRST URL segment
+
+Examples:
+```
+
+photography
+wallpapers
+skins
+other
+
+```
+
+---
+
+### categories
+- `id`
+- `content_type_id`
+- `parent_id`
+- `slug`
+
+Rules:
+- `parent_id = NULL` → root category
+- `parent_id != NULL` → child category
+- `parent_id` MUST reference `categories.id`
+- `content_type_id` MUST reference `content_types.id`
+
+---
+
+## 🧭 URL Structure (MANDATORY)
+
+### Category URLs
+
+```
+
+/{content_type.slug}/{category-path}
+
+```
+
+Where:
+- `category-path` is built from category slugs in hierarchy order
+
+Examples:
+```
+
+/photography
+/photography/abstract
+/photography/abstract/dark
+/skins/media-players
+/other/art
+
+```
+
+---
+
+### Artwork URLs
+
+```
+
+/{content_type.slug}/{category-path}/{artwork.slug}
+
+```
+
+Examples:
+```
+
+/photography/abstract/dark/night-city
+/skins/media-players/zoom-player-dark
+
+```
+
+Rules:
+- Artwork MUST belong to the last category in the path
+- Artwork slug is ALWAYS the final segment
+
+---
+
+## 🧠 Category Path Construction (STRICT RULE)
+
+Category paths MUST be constructed by walking parents.
+
+Algorithm (conceptual):
+
+1. Start with current category
+2. Collect its `slug`
+3. Move to `parent`
+4. Repeat until `parent_id = NULL`
+5. Reverse collected slugs
+6. Join with `/`
+
+Example:
+```
+
+Photography
+└── Abstract
+└── Dark
+
+```
+
+Produces:
+```
+
+abstract/dark
+
+```
+
+Final URL:
+```
+
+/photography/abstract/dark
+
+````
+
+---
+
+## 🧩 Laravel Helper Contract
+
+Category model MUST expose:
+```php
+$category->full_slug_path
+````
+
+Which returns:
+
+```
+abstract/dark
+```
+
+Final URL generation:
+
+```php
+'/' . $category->contentType->slug . '/' . $category->full_slug_path
+```
+
+---
+
+## 🧭 Breadcrumb Rules
+
+Breadcrumbs MUST reflect hierarchy exactly:
+
+Example:
+
+```
+Home → Photography → Abstract → Dark
+```
+
+Each breadcrumb link MUST use the same slug-based URL logic.
+
+---
+
+## 🔐 Canonical URL RULE (SEO)
+
+Every category and artwork page MUST include:
+
+```html
+<link rel="canonical" href="https://skinbase.org/{full-slug-url}">
+```
+
+Canonical URL MUST be:
+
+* lowercase
+* slug-based
+* without IDs
+* without query parameters
+
+---
+
+## 🧨 Legacy URL Handling
+
+Legacy URLs MUST be handled ONLY via **301 redirects**.
+
+Examples:
+
+```
+/Photography/3
+/Photography/Business/564
+```
+
+Redirect to:
+
+```
+/photography/business
+```
+
+Copilot MUST NOT generate new legacy URLs.
+
+---
+
+## ✅ Validation Rules
+
+Copilot MUST ensure:
+
+* all URLs are lowercase
+* slugs are used exclusively
+* depth is unlimited
+* parent relationships are respected
+* only ONE URL exists per resource
+
+---
+
+## 🏁 FINAL STATEMENT
+
+This document is the **single source of truth** for SkinBase category link building.
+
+If any instruction conflicts with older code, documentation, or assumptions,
+THIS DOCUMENT WINS.
+
+END OF SPEC