feat: artwork share system with modal, native Web Share API, and tracking

- Add ArtworkShareModal with glassmorphism UI (Facebook, X, Pinterest, Email, Copy Link, Embed Code)
- Add ArtworkShareButton with lazy-loaded modal and native share fallback
- Add useWebShare hook abstracting navigator.share with AbortError handling
- Add ShareToast auto-dismissing notification component
- Add share() endpoint to ArtworkInteractionController (POST /api/artworks/{id}/share)
- Add artwork_shares migration for Phase 2 share tracking
- Refactor ArtworkActionBar to use new ArtworkShareButton component

.copilot/categories-analysis.md

@@ -0,0 +1,49 @@
+Current DB & Models Analysis — 2026-02-10
+
+Summary
+- `content_types` is the master namespace (see screenshot). Rows: e.g. id=1 Photography (slug `photography`), id=2 Wallpapers, id=3 Skins, id=544 Members.
+- `categories` references `content_types` through `content_type_id`; hierarchical parent/child relation via `parent_id`.
+
+Observed DB columns (categories)
+- id, content_type_id, parent_id, name, slug, description, image, is_active, sort_order, created_at, updated_at, deleted_at
+
+Models verified
+- `ContentType` (app/Models/ContentType.php)
+  - hasMany `categories()` and `rootCategories()`
+  - uses `slug` for route binding
+  - Status: OK and aligns with DB
+
+- `Category` (app/Models/Category.php)
+  - belongsTo `contentType()`
+  - self-referential `parent()` / `children()` (ordered by `sort_order`, then `name`)
+  - `descendants()` recursive helper
+  - `seo()` relation, `artworks()` pivot
+  - scopes: `active()`, `roots()`
+  - accessors: `full_slug_path`, `url`, `canonical_url`, `breadcrumbs`
+  - slug validation enforced in `boot()` (lowercase; only a-z0-9- and dashes)
+  - Status: OK and consistent with screenshots
+
+Key behaviors and checks
+- URL formation: `$category->url` -> `/{content_type.slug}/{category_path}`; canonical URL -> `https://skinbase.org{url}`
+- Slug policy: generation with `Str::slug()` + model validation. Do not bypass.
+- Ordering: use `children()` (sort_order then name) for deterministic menus.
+- Soft deletes: model uses `SoftDeletes`; be explicit when you need trashed categories.
+- Eager-loading: `full_slug_path` walks parents — eager-load `parent` (or ancestors) to avoid N+1 when computing multiple paths.
+
+Copilot / Dev rules (short checklist)
+- Always look up content types by `slug`, not by numeric ID.
+- Use `->roots()->active()->with('children')` for public category lists.
+- Use `$category->url` and `$category->canonical_url` for links and canonical tags.
+- Maintain slug rules: lowercase, only `a-z0-9-`.
+- When reparenting categories, consider invalidating any cached derived paths for descendants.
+- Avoid using legacy `artworks_categories` directly in new controllers; create an adapter if you must read old data.
+
+Suggested next steps
+- Add a PHPUnit test asserting slug validation and `url` generation for nested categories.
+- (Optional) Generate a small ER diagram showing `content_types -> categories -> artwork_category`.
+
+Files referenced
+- [app/Models/ContentType.php](app/Models/ContentType.php)
+- [app/Models/Category.php](app/Models/Category.php)
+
+If you want, I can now add the PHPUnit test or generate the ER diagram.

.env.example

@@ -45,6 +45,150 @@ BROADCAST_CONNECTION=log
 FILESYSTEM_DISK=local
 QUEUE_CONNECTION=database
 
+# Upload UI feature flag (legacy upload remains default unless explicitly enabled)
+SKINBASE_UPLOADS_V2=false
+
+# Draft abuse prevention controls
+SKINBASE_MAX_DRAFTS=10
+SKINBASE_MAX_DRAFT_STORAGE_MB=1024
+SKINBASE_DUPLICATE_HASH_POLICY=block
+
+# Vision / AI auto-tagging (local defaults)
+VISION_ENABLED=true
+VISION_QUEUE=default
+VISION_IMAGE_VARIANT=md
+
+# CLIP service (set base URL to enable CLIP calls)
+CLIP_BASE_URL=
+CLIP_ANALYZE_ENDPOINT=/analyze
+CLIP_TIMEOUT_SECONDS=8
+CLIP_CONNECT_TIMEOUT_SECONDS=2
+CLIP_HTTP_RETRIES=1
+CLIP_HTTP_RETRY_DELAY_MS=200
+CLIP_EMBED_ENDPOINT=/embed
+CLIP_EMBED_TIMEOUT_SECONDS=8
+CLIP_EMBED_CONNECT_TIMEOUT_SECONDS=2
+CLIP_EMBED_HTTP_RETRIES=1
+CLIP_EMBED_HTTP_RETRY_DELAY_MS=200
+
+# Similar artworks / embedding pipeline
+RECOMMENDATIONS_QUEUE=${VISION_QUEUE}
+RECOMMENDATIONS_EMBEDDING_ENABLED=true
+RECOMMENDATIONS_EMBEDDING_MODEL=clip
+RECOMMENDATIONS_EMBEDDING_MODEL_VERSION=v1
+RECOMMENDATIONS_ALGO_VERSION=clip-cosine-v1
+RECOMMENDATIONS_AB_ALGO_VERSIONS=clip-cosine-v1
+RECOMMENDATIONS_MIN_DIM=64
+RECOMMENDATIONS_MAX_DIM=4096
+RECOMMENDATIONS_BACKFILL_BATCH=200
+
+# Personalized discovery foundation (Phase 8)
+DISCOVERY_QUEUE=${RECOMMENDATIONS_QUEUE}
+DISCOVERY_PROFILE_VERSION=profile-v1
+DISCOVERY_EVENT_VERSION=event-v1
+DISCOVERY_ALGO_VERSION=${RECOMMENDATIONS_ALGO_VERSION}
+DISCOVERY_CACHE_VERSION=cache-v1
+DISCOVERY_DECAY_HALF_LIFE_HOURS=72
+DISCOVERY_WEIGHT_VIEW=1
+DISCOVERY_WEIGHT_CLICK=2
+DISCOVERY_WEIGHT_FAVORITE=4
+DISCOVERY_WEIGHT_DOWNLOAD=3
+DISCOVERY_CACHE_TTL_MINUTES=60
+DISCOVERY_RANKING_WEIGHTS_VERSION=rank-w-v1
+DISCOVERY_RANKING_W1=0.65
+DISCOVERY_RANKING_W2=0.20
+DISCOVERY_RANKING_W3=0.10
+DISCOVERY_RANKING_W4=0.05
+DISCOVERY_RANKING_WEIGHTS_VERSION_CLIP_COSINE_V1=rank-w-v1
+DISCOVERY_RANKING_W1_CLIP_COSINE_V1=0.65
+DISCOVERY_RANKING_W2_CLIP_COSINE_V1=0.20
+DISCOVERY_RANKING_W3_CLIP_COSINE_V1=0.10
+DISCOVERY_RANKING_W4_CLIP_COSINE_V1=0.05
+DISCOVERY_RANKING_WEIGHTS_VERSION_CLIP_COSINE_V2=rank-w-v2-prod-1
+DISCOVERY_RANKING_W1_CLIP_COSINE_V2=0.52
+DISCOVERY_RANKING_W2_CLIP_COSINE_V2=0.23
+DISCOVERY_RANKING_W3_CLIP_COSINE_V2=0.15
+DISCOVERY_RANKING_W4_CLIP_COSINE_V2=0.10
+DISCOVERY_ROLLOUT_ENABLED=false
+DISCOVERY_ROLLOUT_BASELINE_ALGO_VERSION=clip-cosine-v1
+DISCOVERY_ROLLOUT_CANDIDATE_ALGO_VERSION=clip-cosine-v2
+DISCOVERY_ROLLOUT_ACTIVE_GATE=g10
+DISCOVERY_ROLLOUT_GATE_10_PERCENT=10
+DISCOVERY_ROLLOUT_GATE_50_PERCENT=50
+DISCOVERY_ROLLOUT_GATE_100_PERCENT=100
+DISCOVERY_FORCE_ALGO_VERSION=
+DISCOVERY_ROLLOUT_WARN_CTR_DROP_PCT=3
+DISCOVERY_ROLLOUT_ROLLBACK_CTR_DROP_PCT=5
+DISCOVERY_ROLLOUT_WARN_LONG_DWELL_DROP_PCT=4
+DISCOVERY_ROLLOUT_ROLLBACK_LONG_DWELL_DROP_PCT=8
+DISCOVERY_ROLLOUT_WARN_DIVERSITY_CONCENTRATION_RISE_PCT=10
+DISCOVERY_ROLLOUT_ROLLBACK_DIVERSITY_CONCENTRATION_RISE_PCT=15
+DISCOVERY_EVAL_WEIGHT_CTR=0.45
+DISCOVERY_EVAL_WEIGHT_SAVE_RATE=0.35
+DISCOVERY_EVAL_WEIGHT_LONG_DWELL=0.25
+DISCOVERY_EVAL_WEIGHT_BOUNCE_PENALTY=0.15
+DISCOVERY_EVAL_SAVE_RATE_INFORMATIONAL=true
+
+# YOLO service (optional)
+YOLO_ENABLED=true
+YOLO_BASE_URL=
+YOLO_ANALYZE_ENDPOINT=/analyze
+YOLO_TIMEOUT_SECONDS=8
+YOLO_CONNECT_TIMEOUT_SECONDS=2
+YOLO_HTTP_RETRIES=1
+YOLO_HTTP_RETRY_DELAY_MS=200
+YOLO_PHOTOGRAPHY_ONLY=true
+
+# -----------------------------------------------------------------------------
+# Production examples (uncomment and adjust)
+# -----------------------------------------------------------------------------
+# VISION_ENABLED=true
+# VISION_QUEUE=vision
+# VISION_IMAGE_VARIANT=md
+#
+# CLIP_BASE_URL=https://clip.internal
+# CLIP_ANALYZE_ENDPOINT=/analyze
+# CLIP_TIMEOUT_SECONDS=5
+# CLIP_CONNECT_TIMEOUT_SECONDS=1
+# CLIP_HTTP_RETRIES=1
+# CLIP_HTTP_RETRY_DELAY_MS=150
+# CLIP_EMBED_ENDPOINT=/embed
+# CLIP_EMBED_TIMEOUT_SECONDS=5
+# CLIP_EMBED_CONNECT_TIMEOUT_SECONDS=1
+# CLIP_EMBED_HTTP_RETRIES=1
+# CLIP_EMBED_HTTP_RETRY_DELAY_MS=150
+# RECOMMENDATIONS_QUEUE=vision
+# RECOMMENDATIONS_EMBEDDING_ENABLED=true
+# RECOMMENDATIONS_EMBEDDING_MODEL=clip
+# RECOMMENDATIONS_EMBEDDING_MODEL_VERSION=v1
+# RECOMMENDATIONS_ALGO_VERSION=clip-cosine-v1
+# RECOMMENDATIONS_AB_ALGO_VERSIONS=clip-cosine-v1,clip-cosine-v2
+# RECOMMENDATIONS_BACKFILL_BATCH=250
+# DISCOVERY_QUEUE=vision
+# DISCOVERY_PROFILE_VERSION=profile-v1
+# DISCOVERY_EVENT_VERSION=event-v1
+# DISCOVERY_ALGO_VERSION=clip-cosine-v1
+# DISCOVERY_CACHE_VERSION=cache-v1
+# DISCOVERY_DECAY_HALF_LIFE_HOURS=72
+# DISCOVERY_WEIGHT_VIEW=1
+# DISCOVERY_WEIGHT_CLICK=2
+# DISCOVERY_WEIGHT_FAVORITE=4
+# DISCOVERY_WEIGHT_DOWNLOAD=3
+# DISCOVERY_RANKING_WEIGHTS_VERSION=rank-w-v1
+# DISCOVERY_RANKING_W1=0.65
+# DISCOVERY_RANKING_W2=0.20
+# DISCOVERY_RANKING_W3=0.10
+# DISCOVERY_RANKING_W4=0.05
+#
+# YOLO_ENABLED=true
+# YOLO_BASE_URL=https://yolo.internal
+# YOLO_ANALYZE_ENDPOINT=/analyze
+# YOLO_TIMEOUT_SECONDS=5
+# YOLO_CONNECT_TIMEOUT_SECONDS=1
+# YOLO_HTTP_RETRIES=1
+# YOLO_HTTP_RETRY_DELAY_MS=150
+# YOLO_PHOTOGRAPHY_ONLY=true
+
 CACHE_STORE=database
 # CACHE_PREFIX=
 
@@ -64,6 +208,23 @@ MAIL_PASSWORD=null
 MAIL_FROM_ADDRESS="hello@example.com"
 MAIL_FROM_NAME="${APP_NAME}"
 
+# Registration anti-spam
+REGISTRATION_IP_PER_MINUTE_LIMIT=3
+REGISTRATION_IP_PER_DAY_LIMIT=20
+REGISTRATION_EMAIL_PER_MINUTE_LIMIT=6
+REGISTRATION_EMAIL_COOLDOWN_MINUTES=30
+REGISTRATION_VERIFY_TOKEN_TTL_HOURS=24
+REGISTRATION_ENABLE_TURNSTILE=true
+REGISTRATION_DISPOSABLE_DOMAINS_ENABLED=true
+REGISTRATION_TURNSTILE_SUSPICIOUS_ATTEMPTS=2
+REGISTRATION_TURNSTILE_ATTEMPT_WINDOW_MINUTES=30
+REGISTRATION_EMAIL_GLOBAL_SEND_PER_MINUTE=30
+REGISTRATION_MONTHLY_EMAIL_LIMIT=10000
+TURNSTILE_SITE_KEY=
+TURNSTILE_SECRET_KEY=
+TURNSTILE_VERIFY_URL=https://challenges.cloudflare.com/turnstile/v0/siteverify
+TURNSTILE_TIMEOUT=5
+
 AWS_ACCESS_KEY_ID=
 AWS_SECRET_ACCESS_KEY=
 AWS_DEFAULT_REGION=us-east-1

.gitignore

@@ -16,6 +16,7 @@
 /public/build
 /public/hot
 /public/storage
+/public/files
 /storage/*.key
 /storage/pail
 /vendor

PR_REGISTRATION_ANTISPAM.md

@@ -0,0 +1,43 @@
+# PR Title
+feat(auth): complete registration anti-spam + email quota protection
+
+## Summary
+Implements the registration anti-spam and quota hardening spec end-to-end for the email-first onboarding flow.
+
+### What changed
+- Added registration anti-spam config and disposable domain config.
+- Added progressive Turnstile verification service and wiring.
+- Added registration rate limiters and route middleware (`register-ip`, `register-ip-daily`).
+- Implemented per-email cooldown and generic anti-enumeration responses.
+- Added queued verification sending job with global throttle + quota circuit breaker.
+- Added quota and disposable-domain services.
+- Hardened verification tokens (hashed storage lookup, expiry, one-time use).
+- Added/updated migrations:
+  - cooldown fields on `users`
+  - `email_send_events`
+  - `system_email_quota`
+  - token column hardening (`token` -> `token_hash`)
+  - rollout safety migration to ensure `user_verification_tokens` table exists
+- Added models: `EmailSendEvent`, `SystemEmailQuota`.
+- Added/updated auth registration tests and runbook docs.
+
+## Verification
+- `php artisan migrate` ✅
+- `php artisan test` ✅
+- Focused token hardening tests ✅ (`RegistrationTokenVerificationTest`)
+
+## Notes
+- Current local branch: `feat/registration-antispam-complete`
+- Local commit: `b239af9`
+- Push/PR creation is currently blocked because this repo has no configured git remote and `gh` CLI is not installed.
+
+## Commands to finish PR after remote setup
+```bash
+git remote add origin <your-repo-url>
+git push -u origin feat/registration-antispam-complete
+```
+
+Then open PR in your Git host UI using:
+- Base: `main` (or your default branch)
+- Compare: `feat/registration-antispam-complete`
+- Body: copy this file

README.md

@@ -54,6 +54,373 @@ In order to ensure that the Laravel community is welcoming to all, please review
 
 If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
 
+## Vision & AI Auto-Tagging Integration
+
+## Upload UI Feature Flag (`uploads.v2`)
+
+The new React upload wizard is behind a feature flag and is **disabled by default**.
+
+- Flag env var: `SKINBASE_UPLOADS_V2`
+- Config key: `features.uploads_v2`
+- Client flags source: `window.SKINBASE_FLAGS`
+
+### Default behavior
+
+- `SKINBASE_UPLOADS_V2=false` → legacy upload UI is rendered.
+- `SKINBASE_UPLOADS_V2=true` → `UploadWizard` is rendered.
+
+### Setup
+
+In `.env` (or `.env.example` for project defaults):
+
+```dotenv
+SKINBASE_UPLOADS_V2=false
+```
+
+Enable explicitly when ready:
+
+```dotenv
+SKINBASE_UPLOADS_V2=true
+```
+
+After changing env values, clear/reload config as usual:
+
+```bash
+php artisan config:clear
+```
+
+The system intentionally keeps legacy upload as the default until the flag is explicitly turned on.
+
+## Upload Moderation UI Flow
+
+Admin moderation for draft uploads is available through a dedicated queue page.
+
+- Page route: `/admin/uploads/moderation`
+- Access: authenticated users with `role=admin` or `role=moderator`
+- Data source: `GET /api/admin/uploads/pending`
+
+### Queue behavior
+
+1. The page loads pending draft uploads (`moderation_status=pending`).
+2. Moderators can enter an optional note per upload.
+3. Approve action calls:
+
+  - `POST /api/admin/uploads/{id}/approve`
+  - Sets moderation to approved and records moderator + timestamp.
+
+4. Reject action calls:
+
+  - `POST /api/admin/uploads/{id}/reject`
+  - Sets upload status/processing state to rejected and stores note.
+
+### Publish gate
+
+- Normal users can publish only when `moderation_status=approved`.
+- Admin users can publish with override behavior.
+
+## Similar Artworks Analytics (A/B Evaluation)
+
+The artwork page similar-items block emits two event types:
+
+- `impression` (block rendered)
+- `click` (item clicked)
+
+Events are stored in `similar_artwork_events` and aggregated daily into `similar_artwork_daily_metrics` by `algo_version`.
+
+- Ingest endpoint: `POST /api/analytics/similar-artworks`
+- Aggregation command: `php artisan analytics:aggregate-similar-artworks --date=YYYY-MM-DD`
+- Scheduler: runs daily at `03:10`
+
+## Personalized Discovery Foundation (Phase 8)
+
+This foundation adds versioned, async-only ingestion and profile normalization for personalized discovery.
+
+- Tables:
+  - `user_interest_profiles`
+  - `user_discovery_events`
+  - `user_recommendation_cache`
+- Ingest endpoint: `POST /api/discovery/events` (auth required)
+- Supported event types: `view`, `click`, `favorite`, `download`
+- Processing model: non-blocking queue job (`IngestUserDiscoveryEventJob`)
+- Normalization: recency-decay + score normalization in `UserInterestProfileService`
+
+No feed ranking/UI behavior is introduced in this foundation step.
+
+### Feed Endpoint Skeleton
+
+The backend now exposes a personalized feed API skeleton:
+
+- Endpoint: `GET /api/v1/feed` (auth required)
+- Query params:
+  - `limit` (1-50, default 24)
+  - `cursor` (opaque cursor token for pagination)
+  - `algo_version` (optional override)
+- Response includes `data` items and `meta.next_cursor` for cursor pagination.
+
+Behavior:
+
+- Reads `user_recommendation_cache` by `user_id + algo_version`.
+- On cache miss/stale, returns immediate fallback results and dispatches async regeneration job.
+- Regeneration runs in queue (`RegenerateUserRecommendationCacheJob`) and writes refreshed cache.
+- Includes cold-start fallback (`popular + similar`) and a diversity guard to avoid near-duplicates.
+
+## Feed Analytics Instrumentation
+
+Feed analytics now track:
+
+- `feed_impression`
+- `feed_click`
+
+Payload dimensions:
+
+- `user_id` (derived from auth session)
+- `artwork_id`
+- `position`
+- `algo_version`
+- `source` (`personalized`, `cold_start`, `fallback`)
+
+Optional:
+
+- `dwell_seconds` (for click dwell bucket metrics)
+
+Endpoints:
+
+- Ingest: `POST /api/analytics/feed` (auth required)
+- Daily aggregation: `php artisan analytics:aggregate-feed --date=YYYY-MM-DD`
+- Admin report: `GET /api/admin/reports/feed-performance`
+
+Daily metrics include CTR, save-rate, and dwell buckets.
+
+For non-blocking client transport, use `navigator.sendBeacon` with `fetch(..., { keepalive: true })` fallback.
+Reference helper: `resources/js/lib/feedAnalytics.js`.
+
+## Phase 8B: Ranking Weight Tuning (Manual + Data-Driven)
+
+Discovery ranking now supports versioned blend weights per `algo_version` in `config/discovery.php`.
+
+- Blend terms: `w1` interest, `w2` recency, `w3` popularity, `w4` novelty
+- Per-algo sets: `discovery.ranking.algo_weight_sets`
+- Safe rollout: deterministic traffic split by `algo_version` with config gates (`g10`, `g50`, `g100`)
+- Emergency rollback: `DISCOVERY_FORCE_ALGO_VERSION=clip-cosine-v1`
+
+Offline evaluator and A/B helper:
+
+- Evaluate objective across one/all algos:
+  - `php artisan analytics:evaluate-feed-weights --from=YYYY-MM-DD --to=YYYY-MM-DD`
+  - Optional: `--algo=clip-cosine-v1`
+- Baseline vs candidate comparison:
+  - `php artisan analytics:compare-feed-ab clip-cosine-v1 clip-cosine-v2 --from=YYYY-MM-DD --to=YYYY-MM-DD`
+
+Objective score uses `feed_daily_metrics` and configurable objective weights in `discovery.evaluation.objective_weights`.
+
+Temporary production policy: set `DISCOVERY_EVAL_SAVE_RATE_INFORMATIONAL=true` to keep `save_rate` visible but excluded from objective score until save-event ingestion is verified.
+
+Operational runbook: `docs/feed-rollout-runbook.md`.
+
+## Operations / Runbooks
+
+- Upload UI v2 rollout, post-deploy monitoring, and rollback: `docs/ui/upload-v2-rollout-runbook.md`
+- Feed rollout and rollback: `docs/feed-rollout-runbook.md`
+- Registration anti-spam and email quota protection: `docs/registration-antispam.md`
+
+No automatic tuning is enabled in this phase.
+
+Skinbase uses asynchronous AI tagging via `AutoTagArtworkJob`.
+The job calls external vision services (CLIP and optional YOLO), normalizes tags, and attaches them through `TagService` as AI tags with confidence values.
+
+### Critical Safety Rule
+
+⚠️ **Publish must never depend on vision services.**
+
+- Upload/publish flow dispatches AI tagging to queue after publish work.
+- Vision failures, timeouts, or service outages must not block artwork publish.
+- If AI tagging fails, artwork remains published and can be tagged later (retry/manual/batch).
+
+### Environment Variables (Vision)
+
+Set these in `.env` (all are optional; defaults are in `config/vision.php`):
+
+#### Global
+
+- `VISION_ENABLED` (default: `true`)
+  - Master switch for all AI auto-tagging.
+- `VISION_QUEUE` (default: `default`)
+  - Queue name used by `AutoTagArtworkJob`.
+- `VISION_IMAGE_VARIANT` (default: `md`)
+  - Derivative variant sent to vision services (e.g. `md`, `lg`).
+
+#### CLIP
+
+- `CLIP_BASE_URL` (default: empty)
+  - Base URL for CLIP service (example: `https://clip.internal`).
+  - If empty, CLIP call is skipped.
+- `CLIP_ANALYZE_ENDPOINT` (default: `/analyze`)
+  - Path appended to `CLIP_BASE_URL`.
+- `CLIP_TIMEOUT_SECONDS` (default: `8`)
+  - Request timeout for CLIP calls.
+- `CLIP_CONNECT_TIMEOUT_SECONDS` (default: `2`)
+  - Connection timeout for CLIP calls.
+- `CLIP_HTTP_RETRIES` (default: `1`)
+  - HTTP retry attempts for CLIP requests.
+- `CLIP_HTTP_RETRY_DELAY_MS` (default: `200`)
+  - Delay between CLIP retries.
+
+#### YOLO (optional)
+
+- `YOLO_ENABLED` (default: `true`)
+  - Enables YOLO integration.
+- `YOLO_BASE_URL` (default: empty)
+  - Base URL for YOLO service. If empty, YOLO call is skipped.
+- `YOLO_ANALYZE_ENDPOINT` (default: `/analyze`)
+  - Path appended to `YOLO_BASE_URL`.
+- `YOLO_TIMEOUT_SECONDS` (default: `8`)
+  - Request timeout for YOLO calls.
+- `YOLO_CONNECT_TIMEOUT_SECONDS` (default: `2`)
+  - Connection timeout for YOLO calls.
+- `YOLO_HTTP_RETRIES` (default: `1`)
+  - HTTP retry attempts for YOLO requests.
+- `YOLO_HTTP_RETRY_DELAY_MS` (default: `200`)
+  - Delay between YOLO retries.
+- `YOLO_PHOTOGRAPHY_ONLY` (default: `true`)
+  - When `true`, YOLO is called only for artworks in photography content type.
+
+### Expected CLIP Response Format
+
+CLIP `/analyze` should return tags as either a direct list or under `tags` / `data`:
+
+```json
+[
+  { "tag": "cyberpunk", "confidence": 0.42 },
+  { "tag": "city", "confidence": 0.31 }
+]
+```
+
+Also accepted:
+
+```json
+{
+  "tags": [
+    { "tag": "cyberpunk", "confidence": 0.42 }
+  ]
+}
+```
+
+or
+
+```json
+{
+  "data": [
+    { "tag": "cyberpunk", "confidence": 0.42 }
+  ]
+}
+```
+
+### Expected YOLO Response Format
+
+YOLO may return the same tag list format as CLIP, or object detections:
+
+```json
+{
+  "objects": [
+    { "label": "person", "confidence": 0.91 },
+    { "label": "camera", "confidence": 0.67 }
+  ]
+}
+```
+
+`label` values are converted to tags, confidence is preserved when present.
+
+### AutoTagArtworkJob Behavior
+
+- Calls CLIP `/analyze` when `VISION_ENABLED=true` and `CLIP_BASE_URL` is set.
+- Optionally calls YOLO based on `YOLO_ENABLED` and `YOLO_PHOTOGRAPHY_ONLY`.
+- Merges CLIP + YOLO tags and keeps highest confidence for duplicates.
+- Normalizes tags before attach (lowercase, cleanup, slug-safe format).
+- Uses `TagService::attachAiTags()` to store pivot data:
+  - `source = ai`
+  - `confidence = <float|null>`
+- Runs with queue retry + timeout safety (`tries`, `backoff`, `timeout`).
+- Logs failures with reference/context for troubleshooting.
+- On non-retriable response scenarios (e.g. 4xx), job exits safely without blocking publish.
+
+### Queue / Worker Requirements (`VISION_QUEUE`)
+
+- Ensure a worker is running for the configured queue.
+- Example worker command:
+
+```bash
+php artisan queue:work --queue=default
+```
+
+- If `VISION_QUEUE=vision`, run worker for that queue:
+
+```bash
+php artisan queue:work --queue=vision
+```
+
+- In production, use Supervisor/systemd/Horizon to keep workers alive.
+- Without an active worker, auto-tagging jobs remain queued and will not execute.
+
+### Local vs Production Notes
+
+#### Local development
+
+- For fully offline local work, set `VISION_ENABLED=false`.
+- Or set only `CLIP_BASE_URL`/`YOLO_BASE_URL` you can reach locally.
+- Prefer short timeouts to avoid slow dev feedback loops.
+
+#### Production
+
+- Use internal/private service endpoints for CLIP/YOLO when possible.
+- Keep conservative timeouts and low retry counts to prevent queue congestion.
+- Monitor failed jobs and logs for vision service reliability.
+- Scale queue workers based on upload volume and service latency.
+
+### Verify Setup (Health + Test Call)
+
+After configuring env vars and restarting workers, verify in this order:
+
+Quick helper (PowerShell):
+
+```powershell
+pwsh -File ./scripts/vision-smoke.ps1
+```
+
+Optional flags:
+
+```powershell
+pwsh -File ./scripts/vision-smoke.ps1 -EnvFile ".env" -SampleImageUrl "https://files.skinbase.org/img/aa/bb/cc/md.webp"
+pwsh -File ./scripts/vision-smoke.ps1 -SkipAnalyze
+```
+
+1. Confirm queue worker is consuming `VISION_QUEUE`.
+
+```bash
+php artisan queue:work --queue=default
+```
+
+1. Check CLIP/YOLO health endpoints (replace host/port as needed):
+
+```bash
+curl -fsS "$CLIP_BASE_URL/health"
+curl -fsS "$YOLO_BASE_URL/health"
+```
+
+1. Make a direct analyze test call (CLIP example):
+
+```bash
+curl -X POST "$CLIP_BASE_URL$CLIP_ANALYZE_ENDPOINT" \
+  -H "Content-Type: application/json" \
+  -d '{"image_url":"https://files.skinbase.org/img/aa/bb/cc/md.webp"}'
+```
+
+1. Trigger an upload/publish and confirm:
+
+- Publish response succeeds even if CLIP/YOLO is down.
+- `AutoTagArtworkJob` is queued/executed asynchronously.
+- AI tags appear on the artwork when services are healthy.
+- Failures are logged, but publish is unaffected.
+
 ## License
 
 The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

app/Banner.php

@@ -6,11 +6,11 @@ class Banner
 {
     public static function ShowResponsiveAd()
     {
-        echo '<div class="responsive_ad">';
-        echo '<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>';
-        echo '<ins class="adsbygoogle" style="display:block" data-ad-client="ca-pub-6457864535683080" data-ad-slot="9918154676" data-ad-format="auto"></ins>';
-        echo '<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>';
-        echo '</div>';
+        #echo '<div class="responsive_ad">';
+        #echo '<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>';
+        #echo '<ins class="adsbygoogle" style="display:block" data-ad-client="ca-pub-6457864535683080" data-ad-slot="9918154676" data-ad-format="auto"></ins>';
+        #echo '<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>';
+        #echo '</div>';
     }
 
     public static function ShowBanner300x250()

app/Console/Commands/AggregateFeedAnalyticsCommand.php

@@ -0,0 +1,106 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+
+final class AggregateFeedAnalyticsCommand extends Command
+{
+    protected $signature = 'analytics:aggregate-feed {--date= : Date (Y-m-d), defaults to yesterday}';
+
+    protected $description = 'Aggregate feed analytics into daily metrics by algo version and source';
+
+    public function handle(): int
+    {
+        $date = $this->option('date')
+            ? (string) $this->option('date')
+            : now()->subDay()->toDateString();
+
+        $rows = DB::table('feed_events')
+            ->selectRaw('algo_version, source')
+            ->selectRaw("SUM(CASE WHEN event_type = 'feed_impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN event_type = 'feed_click' THEN 1 ELSE 0 END) AS clicks")
+            ->selectRaw("SUM(CASE WHEN event_type = 'feed_click' AND dwell_seconds IS NOT NULL AND dwell_seconds < 5 THEN 1 ELSE 0 END) AS dwell_0_5")
+            ->selectRaw("SUM(CASE WHEN event_type = 'feed_click' AND dwell_seconds >= 5 AND dwell_seconds < 30 THEN 1 ELSE 0 END) AS dwell_5_30")
+            ->selectRaw("SUM(CASE WHEN event_type = 'feed_click' AND dwell_seconds >= 30 AND dwell_seconds < 120 THEN 1 ELSE 0 END) AS dwell_30_120")
+            ->selectRaw("SUM(CASE WHEN event_type = 'feed_click' AND dwell_seconds >= 120 THEN 1 ELSE 0 END) AS dwell_120_plus")
+            ->whereDate('event_date', $date)
+            ->groupBy('algo_version', 'source')
+            ->get();
+
+        foreach ($rows as $row) {
+            $algoVersion = (string) $row->algo_version;
+            $source = (string) $row->source;
+            $impressions = (int) ($row->impressions ?? 0);
+            $clicks = (int) ($row->clicks ?? 0);
+
+            $saves = $this->countSavesForGroup($date, $algoVersion, $source);
+
+            $ctr = $impressions > 0 ? $clicks / $impressions : 0.0;
+            $saveRate = $clicks > 0 ? $saves / $clicks : 0.0;
+
+            DB::table('feed_daily_metrics')->updateOrInsert(
+                [
+                    'metric_date' => $date,
+                    'algo_version' => $algoVersion,
+                    'source' => $source,
+                ],
+                [
+                    'impressions' => $impressions,
+                    'clicks' => $clicks,
+                    'saves' => $saves,
+                    'ctr' => $ctr,
+                    'save_rate' => $saveRate,
+                    'dwell_0_5' => (int) ($row->dwell_0_5 ?? 0),
+                    'dwell_5_30' => (int) ($row->dwell_5_30 ?? 0),
+                    'dwell_30_120' => (int) ($row->dwell_30_120 ?? 0),
+                    'dwell_120_plus' => (int) ($row->dwell_120_plus ?? 0),
+                    'updated_at' => now(),
+                    'created_at' => now(),
+                ]
+            );
+        }
+
+        $this->info("Aggregated feed analytics for {$date}.");
+
+        return self::SUCCESS;
+    }
+
+    private function countSavesForGroup(string $date, string $algoVersion, string $source): int
+    {
+        /** @var Collection<int, object{user_id:int,artwork_id:int}> $clickedPairs */
+        $clickedPairs = DB::table('feed_events')
+            ->select('user_id', 'artwork_id')
+            ->whereDate('event_date', $date)
+            ->where('event_type', 'feed_click')
+            ->where('algo_version', $algoVersion)
+            ->where('source', $source)
+            ->groupBy('user_id', 'artwork_id')
+            ->get();
+
+        if ($clickedPairs->isEmpty()) {
+            return 0;
+        }
+
+        $saves = 0;
+        foreach ($clickedPairs as $pair) {
+            $hasSave = DB::table('user_discovery_events')
+                ->whereDate('event_date', $date)
+                ->where('user_id', (int) $pair->user_id)
+                ->where('artwork_id', (int) $pair->artwork_id)
+                ->where('algo_version', $algoVersion)
+                ->whereIn('event_type', ['favorite', 'download'])
+                ->exists();
+
+            if ($hasSave) {
+                $saves++;
+            }
+        }
+
+        return $saves;
+    }
+}

app/Console/Commands/AggregateSimilarArtworkAnalyticsCommand.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+final class AggregateSimilarArtworkAnalyticsCommand extends Command
+{
+    protected $signature = 'analytics:aggregate-similar-artworks {--date= : Date (Y-m-d), defaults to yesterday}';
+
+    protected $description = 'Aggregate similar artwork analytics into daily counts by algo version';
+
+    public function handle(): int
+    {
+        $date = $this->option('date')
+            ? (string) $this->option('date')
+            : now()->subDay()->toDateString();
+
+        $rows = DB::table('similar_artwork_events')
+            ->selectRaw('algo_version')
+            ->selectRaw("SUM(CASE WHEN event_type = 'impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN event_type = 'click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereDate('event_date', $date)
+            ->groupBy('algo_version')
+            ->get();
+
+        foreach ($rows as $row) {
+            $impressions = (int) ($row->impressions ?? 0);
+            $clicks = (int) ($row->clicks ?? 0);
+            $ctr = $impressions > 0 ? $clicks / $impressions : 0.0;
+
+            DB::table('similar_artwork_daily_metrics')->updateOrInsert(
+                [
+                    'metric_date' => $date,
+                    'algo_version' => (string) $row->algo_version,
+                ],
+                [
+                    'impressions' => $impressions,
+                    'clicks' => $clicks,
+                    'ctr' => $ctr,
+                    'updated_at' => now(),
+                    'created_at' => now(),
+                ]
+            );
+        }
+
+        $this->info("Aggregated similar artwork analytics for {$date}.");
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/AiTagArtworksCommand.php

@@ -0,0 +1,436 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\Artwork;
+use App\Services\TagService;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+use Throwable;
+
+/**
+ * Generate AI tags for artworks using a local LM Studio vision model.
+ *
+ * Usage:
+ *   php artisan artworks:ai-tag
+ *   php artisan artworks:ai-tag --after-id=1000 --chunk=20 --dry-run
+ *   php artisan artworks:ai-tag --limit=100 --skip-tagged
+ *   php artisan artworks:ai-tag --artwork-id=242     # process a single artwork by ID
+ *   php artisan artworks:ai-tag --artwork-id=242 --dump-curl  # print equivalent curl command (no API call made)
+ *   php artisan artworks:ai-tag --artwork-id=242 --debug      # print CDN URL, file size, magic bytes and data-URI prefix
+ *   php artisan artworks:ai-tag --url=http://192.168.1.5:8200 --model=google/gemma-3-4b
+ */
+final class AiTagArtworksCommand extends Command
+{
+    protected $signature = 'artworks:ai-tag
+        {--artwork-id=     : Process only this single artwork ID (bypasses public/approved scope)}
+        {--after-id=0      : Skip artworks with ID ≤ this value (useful for resuming)}
+        {--limit=          : Stop after processing this many artworks}
+        {--chunk=50        : DB chunk size}
+        {--dry-run         : Print tags but do not persist them}
+        {--skip-tagged     : Skip artworks that already have at least one AI tag}
+        {--url-only        : Send CDN URL instead of base64 (only works if LM Studio can reach the CDN)}
+        {--dump-curl       : Print the equivalent curl command for the API call and skip the actual request}
+        {--debug           : Print CDN URL, file size, magic bytes and data-URI prefix for each image}
+        {--url=            : LM Studio base URL (overrides config/env)}
+        {--model=          : Model identifier (overrides config/env)}
+        {--clear-ai-tags   : Delete existing AI tags for each artwork before re-tagging}
+    ';
+
+    protected $description = 'Generate tags for artworks via a local LM Studio vision model';
+
+    // -------------------------------------------------------------------------
+    // Prompt
+    // -------------------------------------------------------------------------
+
+    private const SYSTEM_PROMPT = <<<'PROMPT'
+You are an expert at analysing visual artwork and generating concise, descriptive tags.
+PROMPT;
+
+    private const USER_PROMPT = <<<'PROMPT'
+Analyse the artwork image and return a JSON array of relevant tags.
+Cover: art style, subject/theme, dominant colours, mood, technique, and medium where visible.
+
+Rules:
+- Return ONLY a valid JSON array of lowercase strings — no markdown, no explanation.
+- Each tag must be 1–4 words, no punctuation except hyphens.
+- Between 6 and 12 tags total.
+
+Example output:
+["digital painting","fantasy","portrait","dark tones","glowing eyes","detailed","dramatic lighting"]
+PROMPT;
+
+    // -------------------------------------------------------------------------
+
+    public function __construct(private readonly TagService $tagService)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $artworkId  = $this->option('artwork-id') !== null ? (int) $this->option('artwork-id') : null;
+        $afterId    = max(0, (int) $this->option('after-id'));
+        $limit      = $this->option('limit') !== null ? max(1, (int) $this->option('limit')) : null;
+        $chunk      = max(1, min((int) $this->option('chunk'), 200));
+        $dryRun      = (bool) $this->option('dry-run');
+        $skipTagged  = (bool) $this->option('skip-tagged');
+        $dumpCurl    = (bool) $this->option('dump-curl');
+        $verbose     = (bool) $this->option('debug');
+        $useBase64   = !(bool) $this->option('url-only');
+        $clearAiTags = (bool) $this->option('clear-ai-tags');
+
+        $baseUrl = rtrim((string) ($this->option('url') ?: config('vision.lm_studio.base_url')), '/');
+        $model   = (string) ($this->option('model') ?: config('vision.lm_studio.model'));
+        $maxTags = (int) config('vision.lm_studio.max_tags', 12);
+
+        $this->info("LM Studio  : {$baseUrl}");
+        $this->info("Model      : {$model}");
+        $this->info("Image mode : " . ($useBase64 ? 'base64 (default)' : 'CDN URL (--url-only)'));
+        $this->info("Dry run    : " . ($dryRun ? 'YES' : 'no'));
+        $this->info("Clear AI   : " . ($clearAiTags ? 'YES — existing AI tags deleted first' : 'no'));
+        if ($artworkId !== null) {
+            $this->info("Artwork ID : {$artworkId} (single-artwork mode)");
+        }
+        $this->line('');
+
+        // Single-artwork mode: bypass public/approved scope so any artwork can be tested.
+        if ($artworkId !== null) {
+            $artwork = Artwork::withTrashed()->find($artworkId);
+            if ($artwork === null) {
+                $this->error("Artwork #{$artworkId} not found.");
+                return self::FAILURE;
+            }
+            $limit = 1;
+            $query = Artwork::withTrashed()->where('id', $artworkId);
+        } else {
+            $query = Artwork::query()
+                ->public()
+                ->where('id', '>', $afterId)
+                ->whereNotNull('hash')
+                ->whereNotNull('thumb_ext')
+                ->orderBy('id');
+
+            if ($skipTagged) {
+                // Exclude artworks that already have an AI-sourced tag in the pivot.
+                $query->whereDoesntHave('tags', fn ($q) => $q->where('artwork_tag.source', 'ai'));
+            }
+        }
+
+        $processed = 0;
+        $tagged    = 0;
+        $skipped   = 0;
+        $errors    = 0;
+
+        $query->chunkById($chunk, function ($artworks) use (
+            &$processed, &$tagged, &$skipped, &$errors,
+            $limit, $dryRun, $dumpCurl, $verbose, $useBase64, $baseUrl, $model, $maxTags, $clearAiTags,
+        ) {
+            foreach ($artworks as $artwork) {
+                if ($limit !== null && $processed >= $limit) {
+                    return false; // stop iteration
+                }
+
+                $processed++;
+
+                $imageUrl = $artwork->thumbUrl('md');
+                if ($imageUrl === null) {
+                    $this->warn("  [#{$artwork->id}] No thumb URL — skip");
+                    $skipped++;
+                    continue;
+                }
+
+                $this->line("  [#{$artwork->id}] {$artwork->title}");
+
+                // Remove AI tags first if requested.
+                if ($clearAiTags) {
+                    $aiTagIds = DB::table('artwork_tag')
+                        ->where('artwork_id', $artwork->id)
+                        ->where('source', 'ai')
+                        ->pluck('tag_id')
+                        ->all();
+
+                    if ($aiTagIds !== []) {
+                        if (!$dryRun) {
+                            $this->tagService->detachTags($artwork, $aiTagIds);
+                        }
+                        $this->line('    ✂ Cleared ' . count($aiTagIds) . ' existing AI tag(s)' . ($dryRun ? ' (dry-run)' : ''));
+                    }
+                }
+
+                if ($verbose) {
+                    $this->line("    CDN URL : {$imageUrl}");
+                }
+
+                try {
+                    $tags = $this->fetchTags($baseUrl, $model, $imageUrl, $useBase64, $maxTags, $dumpCurl, $verbose);
+                } catch (Throwable $e) {
+                    $this->error("    ✗ API error: " . $e->getMessage());
+                    // Show first 120 chars of the response body for easier debugging.
+                    if (str_contains($e->getMessage(), 'status code')) {
+                        $this->line("    (use --dry-run to test without saving)");
+                    }
+                    Log::error('artworks:ai-tag API error', [
+                        'artwork_id' => $artwork->id,
+                        'error'      => $e->getMessage(),
+                    ]);
+                    $errors++;
+                    continue;
+                }
+
+                if ($tags === []) {
+                    $this->warn("    ✗ No tags returned");
+                    $skipped++;
+                    continue;
+                }
+
+                $tagList = implode(', ', $tags);
+                $this->line("    → {$tagList}");
+
+                if (!$dryRun) {
+                    $aiTagPayload = array_map(fn (string $t) => ['tag' => $t, 'confidence' => null], $tags);
+
+                    try {
+                        $this->tagService->attachAiTags($artwork, $aiTagPayload);
+                        $tagged++;
+                    } catch (Throwable $e) {
+                        $this->error("    ✗ Save error: " . $e->getMessage());
+                        Log::error('artworks:ai-tag save error', [
+                            'artwork_id' => $artwork->id,
+                            'error'      => $e->getMessage(),
+                        ]);
+                        $errors++;
+                    }
+                } else {
+                    $tagged++;
+                }
+            }
+        });
+
+        $this->line('');
+        $this->info("Done. processed={$processed}  tagged={$tagged}  skipped={$skipped}  errors={$errors}");
+
+        return $errors > 0 ? self::FAILURE : self::SUCCESS;
+    }
+
+    // -------------------------------------------------------------------------
+    // LM Studio API call
+    // -------------------------------------------------------------------------
+
+    /**
+     * @return list<string>
+     */
+    private function fetchTags(
+        string $baseUrl,
+        string $model,
+        string $imageUrl,
+        bool $useBase64,
+        int $maxTags,
+        bool $dumpCurl = false,
+        bool $verbose = false,
+    ): array {
+        $imageContent = $useBase64
+            ? $this->buildBase64ImageContent($imageUrl, $verbose)
+            : ['type' => 'image_url', 'image_url' => ['url' => $imageUrl]];
+
+        $payload = [
+            'model'       => $model,
+            'temperature' => (float) config('vision.lm_studio.temperature', 0.3),
+            'max_tokens'  => (int) config('vision.lm_studio.max_tokens', 300),
+            'messages'    => [
+                [
+                    'role'    => 'system',
+                    'content' => self::SYSTEM_PROMPT,
+                ],
+                [
+                    'role'    => 'user',
+                    'content' => [
+                        $imageContent,
+                        ['type' => 'text', 'text' => self::USER_PROMPT],
+                    ],
+                ],
+            ],
+        ];
+
+        $timeout        = (int) config('vision.lm_studio.timeout', 60);
+        $connectTimeout = (int) config('vision.lm_studio.connect_timeout', 5);
+        $endpoint       = "{$baseUrl}/v1/chat/completions";
+
+        // --dump-curl: write payload to a temp file and print the equivalent curl command.
+        if ($dumpCurl) {
+            $jsonPayload = json_encode($payload, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+
+            // Truncate any base64 data URIs in the printed output so the terminal stays readable.
+            $printable = preg_replace(
+                '/("data:[^;]+;base64,)([A-Za-z0-9+\/=]{60})[A-Za-z0-9+\/=]+(")/',
+                '$1$2...[base64 truncated]$3',
+                $jsonPayload,
+            ) ?? $jsonPayload;
+
+            // Write the full (untruncated) payload to a temp file for use with curl --data.
+            $tmpJson = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sbtag_payload_' . uniqid() . '.json';
+            file_put_contents($tmpJson, $jsonPayload);
+
+            $this->line('');
+            $this->line('<fg=yellow>--- Payload (base64 truncated for display) ---</>');
+            $this->line($printable);
+            $this->line('');
+            $this->line('<fg=yellow>--- curl command (full payload in temp file) ---</>');
+            $this->line(
+                'curl -s -X POST ' . escapeshellarg($endpoint)
+                . ' -H ' . escapeshellarg('Content-Type: application/json')
+                . ' --data @' . escapeshellarg($tmpJson)
+                . ' | python -m json.tool'
+            );
+            $this->line('');
+            $this->info("Full JSON payload written to: {$tmpJson}");
+
+            // Return empty — no real API call is made.
+            return [];
+        }
+
+        $response = Http::timeout($timeout)
+            ->connectTimeout($connectTimeout)
+            ->post($endpoint, $payload)
+            ->throw();
+
+        $body    = $response->json();
+        $content = $body['choices'][0]['message']['content'] ?? '';
+
+        return $this->parseTags((string) $content, $maxTags);
+    }
+
+    /**
+     * Download the image using the system curl binary (raw bytes, no encoding surprises),
+     * base64-encode from the local file, then delete it.
+     *
+     * Using curl directly is more reliable than the Laravel Http client here because it
+     * avoids gzip/deflate decoding issues, chunked-transfer quirks, and header parsing
+     * edge cases that could corrupt the image bytes before encoding.
+     *
+     * @return array<string, mixed>
+     * @throws \RuntimeException if curl fails or the file is empty
+     */
+    private function buildBase64ImageContent(string $imageUrl, bool $verbose = false): array
+    {
+        $ext  = strtolower(pathinfo(parse_url($imageUrl, PHP_URL_PATH) ?? '', PATHINFO_EXTENSION));
+        $mime = match ($ext) {
+            'png'  => 'image/png',
+            'gif'  => 'image/gif',
+            'webp' => 'image/webp',
+            default => 'image/jpeg',
+        };
+
+        $tmpPath = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sbtag_' . uniqid() . '.' . ($ext ?: 'jpg');
+
+        try {
+            exec(
+                'curl -s -f -L --max-time 30 -o ' . escapeshellarg($tmpPath) . ' ' . escapeshellarg($imageUrl),
+                $output,
+                $exitCode,
+            );
+
+            if ($exitCode !== 0 || !file_exists($tmpPath) || filesize($tmpPath) === 0) {
+                throw new \RuntimeException("curl failed to download image (exit={$exitCode}, size=" . (file_exists($tmpPath) ? filesize($tmpPath) : 'N/A') . "): {$imageUrl}");
+            }
+
+            $rawBytes = file_get_contents($tmpPath);
+            if ($rawBytes === false || $rawBytes === '') {
+                throw new \RuntimeException("file_get_contents returned empty after curl download: {$tmpPath}");
+            }
+
+            // LM Studio does not support WebP. Convert to JPEG via GD if needed.
+            if ($mime === 'image/webp') {
+                $convertedPath = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'sbtag_conv_' . uniqid() . '.jpg';
+                try {
+                    if (!function_exists('imagecreatefromwebp')) {
+                        throw new \RuntimeException('GD extension with WebP support is required to convert WebP images. Enable ext-gd with WebP support in php.ini.');
+                    }
+                    $img = imagecreatefromwebp($tmpPath);
+                    if ($img === false) {
+                        throw new \RuntimeException("GD failed to load WebP: {$tmpPath}");
+                    }
+                    imagejpeg($img, $convertedPath, 92);
+                    imagedestroy($img);
+                    $rawBytes = file_get_contents($convertedPath);
+                    $mime     = 'image/jpeg';
+                    if ($verbose) {
+                        $this->line('    Convert : WebP → JPEG (LM Studio does not accept WebP)');
+                    }
+                } finally {
+                    @unlink($convertedPath);
+                }
+            }
+
+            if ($verbose) {
+                $fileSize  = filesize($tmpPath);
+                // Show first 8 bytes as hex to confirm it's a real image, not an HTML error page.
+                $magicHex  = strtoupper(bin2hex(substr($rawBytes, 0, 8)));
+                $this->line("    File    : {$tmpPath}");
+                $this->line("    Size    : {$fileSize} bytes");
+                $this->line("    Magic   : {$magicHex}  (JPEG=FFD8FF, PNG=89504E47, WEBP=52494646)");
+            }
+
+            $base64  = base64_encode($rawBytes);
+            $dataUri = "data:{$mime};base64,{$base64}";
+
+            if ($verbose) {
+                $this->line("    MIME    : {$mime}");
+                $this->line("    URI pfx : " . substr($dataUri, 0, 60) . '...');
+            }
+        } finally {
+            @unlink($tmpPath);
+        }
+
+        return ['type' => 'image_url', 'image_url' => ['url' => $dataUri]];
+    }
+
+    // -------------------------------------------------------------------------
+    // Response parsing
+    // -------------------------------------------------------------------------
+
+    /**
+     * Extract a JSON array from the model's response text.
+     *
+     * The model should return just the array, but may include surrounding text
+     * or markdown code fences, so we search for the first `[…]` block.
+     *
+     * @return list<string>
+     */
+    private function parseTags(string $content, int $maxTags): array
+    {
+        $content = trim($content);
+
+        // Strip markdown code fences if present (```json … ```)
+        $content = preg_replace('/^```(?:json)?\s*/i', '', $content) ?? $content;
+        $content = preg_replace('/\s*```$/', '', $content) ?? $content;
+
+        // Extract the first JSON array from the text.
+        if (!preg_match('/(\[.*?\])/s', $content, $matches)) {
+            return [];
+        }
+
+        $decoded = json_decode($matches[1], true);
+        if (!is_array($decoded)) {
+            return [];
+        }
+
+        $tags = [];
+        foreach ($decoded as $item) {
+            if (!is_string($item)) {
+                continue;
+            }
+            $clean = trim(strtolower((string) $item));
+            if ($clean !== '') {
+                $tags[] = $clean;
+            }
+        }
+
+        // Respect the configured max-tags ceiling.
+        return array_slice(array_unique($tags), 0, $maxTags);
+    }
+}

app/Console/Commands/AvatarsMigrate.php

@@ -0,0 +1,316 @@
+<?php
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Storage;
+use App\Models\User;
+use App\Models\UserProfile;
+use Intervention\Image\ImageManagerStatic as Image;
+use Carbon\Carbon;
+
+class AvatarsMigrate extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'avatars:migrate
+        {--dry-run : Do not write files or update database}
+        {--force : Overwrite existing migrated avatars}
+        {--remove-legacy : Remove legacy files after successful migration}
+        {--path=public/files/usericons : Legacy path to scan}
+        {--user-id= : Only migrate a single user by ID}
+    ';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Migrate legacy avatars from public/files/usericons to storage/app/public/avatars and generate sizes (WebP)';
+
+    /**
+     * Allowed MIME types for source images.
+     *
+     * @var array
+     */
+    protected $allowed = [
+        'image/jpeg',
+        'image/png',
+        'image/webp',
+    ];
+
+    /**
+     * Target sizes to generate.
+     *
+     * @var int[]
+     */
+    protected $sizes = [32, 64, 128, 256, 512];
+
+    public function handle(): int
+    {
+        $dry = $this->option('dry-run');
+        $force = $this->option('force');
+        $removeLegacy = $this->option('remove-legacy');
+        $legacyPath = base_path($this->option('path'));
+        $userId = $this->option('user-id') ? (int) $this->option('user-id') : null;
+
+        $this->info('Starting avatar migration' . ($dry ? ' (dry-run)' : '') . ($userId ? " for user={$userId}" : ''));
+
+        // Detect processing backend: Intervention preferred, GD fallback
+        $useIntervention = class_exists('Intervention\\Image\\ImageManagerStatic');
+        if ($useIntervention) {
+            Image::configure(['driver' => extension_loaded('imagick') ? 'imagick' : 'gd']);
+        }
+
+        $bar = null;
+
+        $query = User::with('profile');
+        if ($userId) {
+            $query->where('id', $userId);
+        }
+
+        $query->chunk(100, function ($users) use ($dry, $force, $removeLegacy, $legacyPath, &$bar, $useIntervention) {
+            foreach ($users as $user) {
+                /** @var UserProfile|null $profile */
+                $profile = $user->profile;
+
+                if (!$profile) {
+                    continue;
+                }
+
+                // Skip if already migrated unless --force
+                if (!$force && !empty($profile->avatar_hash)) {
+                    $this->line("[skip] user={$user->id} already migrated");
+                    continue;
+                }
+
+                $source = $this->findLegacyFile($profile, $user->id, $legacyPath);
+
+                if (!$source) {
+                    $this->line("[noop] user={$user->id} no legacy file found");
+                    continue;
+                }
+
+                try {
+                    $this->line("[proc] user={$user->id} file={$source}");
+
+                    if ($useIntervention) {
+                        $img = Image::make($source);
+                        $mime = $img->mime();
+                    } else {
+                        $info = @getimagesize($source);
+                        $mime = $info['mime'] ?? null;
+                    }
+
+                    if (!in_array($mime, $this->allowed, true)) {
+                        $this->line("[reject] user={$user->id} unsupported mime={$mime}");
+                        continue;
+                    }
+
+                    // Re-encode full original to webp (strip metadata)
+                    if ($useIntervention) {
+                        $originalBlob = (string) $img->encode('webp', 82);
+                    } else {
+                        $originalBlob = $this->gdEncodeWebp($source, 82);
+                    }
+
+                    // Hybrid hash: deterministic user-id fingerprint + short content fingerprint
+                    // idPart = sha1(zero-padded user id), contentPart = first 12 chars of sha1(original webp blob)
+                    $idPart = sha1(sprintf('%08d', $user->id));
+                    $contentPart = substr(sha1($originalBlob), 0, 12);
+                    $hash = sprintf('%s_%s', $idPart, $contentPart);
+
+                    if ($dry) {
+                        $this->line("[dry] user={$user->id} would write avatars for hash={$hash}");
+                    } else {
+                        // Use hash-based directory structure: avatars/ab/cd/{hash}/
+                        $hashPrefix1 = substr($hash, 0, 2);
+                        $hashPrefix2 = substr($hash, 2, 2);
+                        $dir = "avatars/{$hashPrefix1}/{$hashPrefix2}/{$hash}";
+                        Storage::disk('public')->makeDirectory($dir);
+
+                        // Save original.webp
+                        Storage::disk('public')->put("{$dir}/original.webp", $originalBlob);
+
+                        // Generate sizes
+                        foreach ($this->sizes as $size) {
+                            if ($useIntervention) {
+                                $thumb = Image::make($source)->fit($size, $size, function ($constraint) {
+                                    $constraint->upsize();
+                                });
+
+                                $thumbBlob = (string) $thumb->encode('webp', 82);
+                            } else {
+                                $thumbBlob = $this->gdCreateThumbnailWebp($source, $size, 82);
+                            }
+                            Storage::disk('public')->put("{$dir}/{$size}.webp", $thumbBlob);
+                        }
+
+                        // Update DB
+                        $profile->avatar_hash = $hash;
+                        $profile->avatar_mime = 'image/webp';
+                        $profile->avatar_updated_at = Carbon::now();
+                        $profile->save();
+
+                        $this->line("[ok] user={$user->id} migrated hash={$hash}");
+
+                        if ($removeLegacy && !empty($profile->avatar_legacy)) {
+                            $legacyFile = base_path("public/files/usericons/{$profile->avatar_legacy}");
+                            if (file_exists($legacyFile)) {
+                                @unlink($legacyFile);
+                                $this->line("[rm] removed legacy file {$legacyFile}");
+                            }
+                        }
+                    }
+                } catch (\Exception $e) {
+                    $this->error("[error] user={$user->id} {$e->getMessage()}");
+                    continue;
+                }
+            }
+        });
+
+        $this->info('Avatar migration complete');
+
+        return 0;
+    }
+
+    /**
+     * Try to find a legacy avatar file for a user/profile.
+     *
+     * @param UserProfile $profile
+     * @param int $userId
+     * @param string $legacyBase
+     * @return string|null
+     */
+    protected function findLegacyFile(UserProfile $profile, int $userId, string $legacyBase): ?string
+    {
+        // 1) If profile->avatar_legacy looks like a filename, try it
+        if (!empty($profile->avatar_legacy)) {
+            $p = $legacyBase . DIRECTORY_SEPARATOR . $profile->avatar_legacy;
+            if (file_exists($p)) {
+                return $p;
+            }
+        }
+
+        // 2) Try files named by user id with common extensions
+        $exts = ['png','jpg','jpeg','webp','gif'];
+        foreach ($exts as $ext) {
+            $p = $legacyBase . DIRECTORY_SEPARATOR . "{$userId}.{$ext}";
+            if (file_exists($p)) {
+                return $p;
+            }
+        }
+
+        // 3) Try any file under legacy dir that contains the user id in name
+        if (is_dir($legacyBase)) {
+            $files = glob($legacyBase . DIRECTORY_SEPARATOR . "*{$userId}*.*");
+            if (!empty($files)) {
+                return $files[0];
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * GD-based encode to WebP binary blob.
+     *
+     * @param string $path
+     * @param int $quality
+     * @return string
+     */
+    protected function gdEncodeWebp(string $path, int $quality = 82): string
+    {
+        if (!function_exists('imagewebp')) {
+            throw new \RuntimeException('GD imagewebp function is not available. Install Intervention Image or enable GD WebP support.');
+        }
+
+        $src = $this->gdCreateResource($path);
+        if (!$src) {
+            throw new \RuntimeException('Unable to read image for GD processing: ' . $path);
+        }
+
+        ob_start();
+        imagewebp($src, null, $quality);
+        $data = ob_get_clean();
+        imagedestroy($src);
+
+        return $data;
+    }
+
+    /**
+     * Create a center-cropped square thumbnail and return WebP binary.
+     *
+     * @param string $path
+     * @param int $size
+     * @param int $quality
+     * @return string
+     */
+    protected function gdCreateThumbnailWebp(string $path, int $size, int $quality = 82): string
+    {
+        if (!function_exists('imagewebp')) {
+            throw new \RuntimeException('GD imagewebp function is not available. Install Intervention Image or enable GD WebP support.');
+        }
+
+        $src = $this->gdCreateResource($path);
+        if (!$src) {
+            throw new \RuntimeException('Unable to read image for GD processing: ' . $path);
+        }
+
+        $w = imagesx($src);
+        $h = imagesy($src);
+        $min = min($w, $h);
+        $srcX = (int) floor(($w - $min) / 2);
+        $srcY = (int) floor(($h - $min) / 2);
+
+        $dst = imagecreatetruecolor($size, $size);
+        // preserve transparency
+        imagealphablending($dst, false);
+        imagesavealpha($dst, true);
+
+        imagecopyresampled($dst, $src, 0, 0, $srcX, $srcY, $size, $size, $min, $min);
+
+        ob_start();
+        imagewebp($dst, null, $quality);
+        $data = ob_get_clean();
+
+        imagedestroy($src);
+        imagedestroy($dst);
+
+        return $data;
+    }
+
+    /**
+     * Create GD image resource from file path.
+     *
+     * @param string $path
+     * @return resource|false
+     */
+    protected function gdCreateResource(string $path)
+    {
+        $info = @getimagesize($path);
+        if (!$info) {
+            return false;
+        }
+
+        $mime = $info['mime'] ?? '';
+
+        switch ($mime) {
+            case 'image/jpeg':
+                return imagecreatefromjpeg($path);
+            case 'image/png':
+                return imagecreatefrompng($path);
+            case 'image/webp':
+                if (function_exists('imagecreatefromwebp')) {
+                    return imagecreatefromwebp($path);
+                }
+                return false;
+            default:
+                return false;
+        }
+    }
+}
+

app/Console/Commands/BackfillArtworkEmbeddingsCommand.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Jobs\BackfillArtworkEmbeddingsJob;
+use Illuminate\Console\Command;
+
+final class BackfillArtworkEmbeddingsCommand extends Command
+{
+    protected $signature = 'artworks:embeddings-backfill {--after-id=0 : Resume after this artwork id} {--batch=200 : Batch size for resumable fan-out} {--force : Regenerate even when source hash matches}';
+
+    protected $description = 'Queue resumable CLIP embedding backfill for artworks';
+
+    public function handle(): int
+    {
+        $afterId = max(0, (int) $this->option('after-id'));
+        $batch = max(1, min((int) $this->option('batch'), 1000));
+        $force = (bool) $this->option('force');
+
+        BackfillArtworkEmbeddingsJob::dispatch($afterId, $batch, $force);
+
+        $this->info("Queued artwork embedding backfill (after_id={$afterId}, batch={$batch}, force=" . ($force ? 'yes' : 'no') . ').');
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/CompareFeedAbCommand.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\Recommendations\FeedOfflineEvaluationService;
+use Illuminate\Console\Command;
+
+final class CompareFeedAbCommand extends Command
+{
+    protected $signature = 'analytics:compare-feed-ab
+                            {baseline : Baseline algo_version}
+                            {candidate : Candidate algo_version}
+                            {--from= : Start date (Y-m-d), defaults to last 30 days}
+                            {--to= : End date (Y-m-d), defaults to today}
+                            {--json : Output as JSON}';
+
+    protected $description = 'A/B helper for baseline vs candidate feed algo comparison';
+
+    public function __construct(private readonly FeedOfflineEvaluationService $evaluator)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $from = (string) ($this->option('from') ?: now()->subDays(29)->toDateString());
+        $to = (string) ($this->option('to') ?: now()->toDateString());
+
+        if ($from > $to) {
+            $this->error('Invalid range: --from must be <= --to');
+            return self::FAILURE;
+        }
+
+        $baseline = (string) $this->argument('baseline');
+        $candidate = (string) $this->argument('candidate');
+
+        $comparison = $this->evaluator->compareBaselineCandidate($baseline, $candidate, $from, $to);
+
+        if ((bool) $this->option('json')) {
+            $this->line((string) json_encode($comparison, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            return self::SUCCESS;
+        }
+
+        $this->table(
+            ['algo_version', 'ctr', 'save_rate', 'long_dwell_share', 'bounce_rate', 'objective_score'],
+            [[
+                (string) $comparison['baseline']['algo_version'],
+                (float) $comparison['baseline']['ctr'],
+                (float) $comparison['baseline']['save_rate'],
+                (float) $comparison['baseline']['long_dwell_share'],
+                (float) $comparison['baseline']['bounce_rate'],
+                (float) $comparison['baseline']['objective_score'],
+            ], [
+                (string) $comparison['candidate']['algo_version'],
+                (float) $comparison['candidate']['ctr'],
+                (float) $comparison['candidate']['save_rate'],
+                (float) $comparison['candidate']['long_dwell_share'],
+                (float) $comparison['candidate']['bounce_rate'],
+                (float) $comparison['candidate']['objective_score'],
+            ]]
+        );
+
+        $delta = (array) $comparison['delta'];
+        $this->line('Δ objective_score: ' . (string) $delta['objective_score']);
+        $this->line('Δ objective_lift_pct: ' . (string) ($delta['objective_lift_pct'] ?? 'n/a'));
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/ConfigureMeilisearchIndex.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Meilisearch\Client as MeilisearchClient;
+
+/**
+ * Configure the Meilisearch artworks index:
+ *   – sortable attributes (all fields used in category/discover sorts)
+ *   – filterable attributes (used in search filters)
+ *
+ * Run after any schema / toSearchableArray change:
+ *   php artisan meilisearch:configure-index
+ */
+class ConfigureMeilisearchIndex extends Command
+{
+    protected $signature   = 'meilisearch:configure-index {--index=artworks : Meilisearch index name}';
+    protected $description = 'Push sortable and filterable attribute settings to the Meilisearch artworks index.';
+
+    /**
+     * Fields that can be used as sort targets in Artwork::search()->options(['sort' => …]).
+     * Must match keys in Artwork::toSearchableArray().
+     */
+    private const SORTABLE_ATTRIBUTES = [
+        'created_at',
+        'trending_score_24h',
+        'trending_score_7d',
+        'favorites_count',
+        'downloads_count',
+        'awards_received_count',
+        'views',
+        'likes',
+        'downloads',
+    ];
+
+    /**
+     * Fields used in filter expressions (AND category = "…" etc.).
+     */
+    private const FILTERABLE_ATTRIBUTES = [
+        'id',
+        'is_public',
+        'is_approved',
+        'category',
+        'content_type',
+        'tags',
+        'author_id',
+        'orientation',
+        'resolution',
+    ];
+
+    public function handle(): int
+    {
+        $prefix    = config('scout.prefix', '');
+        $indexName = $prefix . (string) $this->option('index');
+
+        /** @var MeilisearchClient $client */
+        $client = app(MeilisearchClient::class);
+
+        $index = $client->index($indexName);
+
+        $this->info("Configuring Meilisearch index: {$indexName}");
+
+        // ── Sortable attributes ───────────────────────────────────────────────
+        $this->line('  → Updating sortableAttributes…');
+        $task = $index->updateSortableAttributes(self::SORTABLE_ATTRIBUTES);
+        $this->line("    Task uid: {$task['taskUid']}");
+
+        // ── Filterable attributes ─────────────────────────────────────────────
+        $this->line('  → Updating filterableAttributes…');
+        $task2 = $index->updateFilterableAttributes(self::FILTERABLE_ATTRIBUTES);
+        $this->line("    Task uid: {$task2['taskUid']}");
+
+        $this->info('Done. Meilisearch will process these tasks asynchronously.');
+        $this->warn('Re-index artworks if sortable attributes changed: php artisan artworks:search-rebuild');
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/EnforceUsernamePolicy.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\User;
+use App\Support\UsernamePolicy;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+class EnforceUsernamePolicy extends Command
+{
+    protected $signature = 'skinbase:enforce-usernames {--dry-run : Report only, no writes}';
+
+    protected $description = 'Normalize and enforce username policy on existing users, with collision resolution and redirect logging.';
+
+    public function handle(): int
+    {
+        $dryRun = (bool) $this->option('dry-run');
+        $logPath = storage_path('logs/username_migration.log');
+        @file_put_contents($logPath, '['.now()."] enforce-usernames dry_run=".($dryRun ? '1' : '0')."\n", FILE_APPEND);
+
+        $used = User::query()->whereNotNull('username')->pluck('id', 'username')->mapWithKeys(fn ($id, $username) => [strtolower((string) $username) => (int) $id])->all();
+
+        $updated = 0;
+
+        User::query()->orderBy('id')->chunkById(500, function ($users) use (&$used, &$updated, $dryRun, $logPath): void {
+            foreach ($users as $user) {
+                $current = strtolower(trim((string) ($user->username ?? '')));
+                $base = UsernamePolicy::sanitizeLegacy($current !== '' ? $current : ('user'.$user->id));
+
+                if (UsernamePolicy::isReserved($base) || UsernamePolicy::similarReserved($base) !== null) {
+                    $base = 'user'.$user->id;
+                }
+
+                $candidate = substr($base, 0, UsernamePolicy::max());
+                $suffix = 1;
+                while ((isset($used[$candidate]) && (int) $used[$candidate] !== (int) $user->id) || UsernamePolicy::isReserved($candidate) || UsernamePolicy::similarReserved($candidate) !== null) {
+                    $suffixStr = (string) $suffix;
+                    $prefixLen = max(1, UsernamePolicy::max() - strlen($suffixStr));
+                    $candidate = substr($base, 0, $prefixLen) . $suffixStr;
+                    $suffix++;
+                }
+
+                $needsUpdate = $candidate !== $current;
+                if (! $needsUpdate) {
+                    $used[$candidate] = (int) $user->id;
+                    continue;
+                }
+
+                @file_put_contents($logPath, sprintf("[%s] user_id=%d old=%s new=%s\n", now()->toDateTimeString(), (int) $user->id, $current, $candidate), FILE_APPEND);
+
+                if (! $dryRun) {
+                    DB::transaction(function () use ($user, $current, $candidate): void {
+                        if ($current !== '' && Schema::hasTable('username_history')) {
+                            DB::table('username_history')->insert([
+                                'user_id' => (int) $user->id,
+                                'old_username' => $current,
+                                'changed_at' => now(),
+                                'created_at' => now(),
+                                'updated_at' => now(),
+                            ]);
+                        }
+
+                        if ($current !== '' && Schema::hasTable('username_redirects')) {
+                            DB::table('username_redirects')->updateOrInsert(
+                                ['old_username' => $current],
+                                [
+                                    'new_username' => $candidate,
+                                    'user_id' => (int) $user->id,
+                                    'created_at' => now(),
+                                    'updated_at' => now(),
+                                ]
+                            );
+                        }
+
+                        DB::table('users')->where('id', (int) $user->id)->update([
+                            'username' => $candidate,
+                            'username_changed_at' => now(),
+                            'updated_at' => now(),
+                        ]);
+                    });
+                }
+
+                $used[$candidate] = (int) $user->id;
+                $updated++;
+            }
+        });
+
+        $this->info("Username policy enforcement complete. Updated: {$updated}" . ($dryRun ? ' (dry run)' : ''));
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/EvaluateFeedWeightsCommand.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\Recommendations\FeedOfflineEvaluationService;
+use Illuminate\Console\Command;
+
+final class EvaluateFeedWeightsCommand extends Command
+{
+    protected $signature = 'analytics:evaluate-feed-weights
+                            {--algo= : Optional algo_version to evaluate}
+                            {--from= : Start date (Y-m-d), defaults to last 30 days}
+                            {--to= : End date (Y-m-d), defaults to today}
+                            {--json : Output as JSON}';
+
+    protected $description = 'Offline feed weight evaluation using feed_daily_metrics';
+
+    public function __construct(private readonly FeedOfflineEvaluationService $evaluator)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $from = (string) ($this->option('from') ?: now()->subDays(29)->toDateString());
+        $to = (string) ($this->option('to') ?: now()->toDateString());
+        $algo = $this->option('algo') ? (string) $this->option('algo') : null;
+
+        if ($from > $to) {
+            $this->error('Invalid range: --from must be <= --to');
+            return self::FAILURE;
+        }
+
+        if ($algo !== null && $algo !== '') {
+            $result = $this->evaluator->evaluateAlgo($algo, $from, $to);
+
+            if ((bool) $this->option('json')) {
+                $this->line((string) json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            } else {
+                $this->table(
+                    ['algo_version', 'ctr', 'save_rate', 'long_dwell_share', 'bounce_rate', 'objective_score'],
+                    [[
+                        (string) $result['algo_version'],
+                        (float) $result['ctr'],
+                        (float) $result['save_rate'],
+                        (float) $result['long_dwell_share'],
+                        (float) $result['bounce_rate'],
+                        (float) $result['objective_score'],
+                    ]]
+                );
+            }
+
+            return self::SUCCESS;
+        }
+
+        $results = $this->evaluator->evaluateAll($from, $to);
+
+        if ((bool) $this->option('json')) {
+            $this->line((string) json_encode($results, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            return self::SUCCESS;
+        }
+
+        $rows = array_map(static fn (array $row): array => [
+            (string) $row['algo_version'],
+            (float) $row['ctr'],
+            (float) $row['save_rate'],
+            (float) $row['long_dwell_share'],
+            (float) $row['bounce_rate'],
+            (float) $row['objective_score'],
+        ], $results);
+
+        $this->table(
+            ['algo_version', 'ctr', 'save_rate', 'long_dwell_share', 'bounce_rate', 'objective_score'],
+            $rows
+        );
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/FixTagNamesCommand.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\TagNormalizer;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * One-time (and idempotent) command to convert slug-style tag names to
+ * human-readable display names.
+ *
+ * A tag is considered "slug-style" when its name is identical to its slug
+ * (e.g. name="digital-art", slug="digital-art").  Tags that already have a
+ * custom name (user-edited) are left untouched.
+ *
+ * Usage:
+ *   php artisan tags:fix-names
+ *   php artisan tags:fix-names --dry-run
+ */
+final class FixTagNamesCommand extends Command
+{
+    protected $signature = 'tags:fix-names
+        {--dry-run : Show what would change without writing to the database}
+    ';
+
+    protected $description = 'Convert slug-style tag names (e.g. "digital-art") to readable names ("Digital Art")';
+
+    public function __construct(private readonly TagNormalizer $normalizer)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $dryRun = (bool) $this->option('dry-run');
+
+        if ($dryRun) {
+            $this->warn('DRY-RUN — no changes will be written.');
+        }
+
+        // Only fix rows where name === slug (those were created by the old code).
+        $rows = DB::table('tags')
+            ->whereColumn('name', 'slug')
+            ->orderBy('id')
+            ->get(['id', 'name', 'slug']);
+
+        if ($rows->isEmpty()) {
+            $this->info('Nothing to fix — all tag names are already human-readable.');
+            return self::SUCCESS;
+        }
+
+        $this->info("Found {$rows->count()} tag(s) with slug-style names.");
+
+        $updated = 0;
+        $bar     = $this->output->createProgressBar($rows->count());
+        $bar->start();
+
+        foreach ($rows as $row) {
+            $displayName = $this->normalizer->toDisplayName($row->slug);
+
+            if ($displayName === $row->name) {
+                $bar->advance();
+                continue; // Already correct (e.g. single-word tag "cars" → "Cars" — wait, that would differ)
+            }
+
+            if ($this->output->isVerbose()) {
+                $this->newLine();
+                $this->line("  {$row->slug}  →  \"{$displayName}\"");
+            }
+
+            if (!$dryRun) {
+                DB::table('tags')
+                    ->where('id', $row->id)
+                    ->update(['name' => $displayName]);
+            }
+
+            $updated++;
+            $bar->advance();
+        }
+
+        $bar->finish();
+        $this->newLine(2);
+
+        $suffix = $dryRun ? ' (dry-run, nothing written)' : '';
+        $this->info("Updated {$updated} of {$rows->count()} tag(s){$suffix}.");
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/FlushRedisStatsCommand.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\ArtworkStatsService;
+use Illuminate\Console\Command;
+
+/**
+ * Drain the Redis artwork-stat delta queue into MySQL.
+ *
+ * The ArtworkStatsService::incrementViews/Downloads methods push compressed
+ * delta payloads to a Redis list (`artwork_stats:deltas`) when Redis is
+ * available. This command drains that queue by applying each delta to the
+ * artwork_stats table via applyDelta().
+ *
+ * Designed to run every 5 minutes so counters stay reasonably fresh while
+ * keeping MySQL write pressure low. If Redis is unavailable the command exits
+ * immediately without error — the service already fell back to direct DB
+ * writes in that case.
+ *
+ * Usage:
+ *   php artisan skinbase:flush-redis-stats
+ *   php artisan skinbase:flush-redis-stats --max=500
+ */
+class FlushRedisStatsCommand extends Command
+{
+    protected $signature   = 'skinbase:flush-redis-stats {--max=1000 : Maximum deltas to process per run}';
+    protected $description = 'Drain Redis artwork stat delta queue into MySQL';
+
+    public function handle(ArtworkStatsService $service): int
+    {
+        $max = (int) $this->option('max');
+
+        $processed = $service->processPendingFromRedis($max);
+
+        if ($this->getOutput()->isVerbose()) {
+            $this->info("Processed {$processed} artwork-stat delta(s) from Redis.");
+        }
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/ForumConvertPosts.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use App\Models\ForumPost;
+use App\Services\BbcodeConverter;
+
+class ForumConvertPosts extends Command
+{
+    protected $signature = 'forum:convert-posts {--dry-run} {--chunk=500} {--limit=} {--report}';
+
+    protected $description = 'Convert migrated forum posts content from legacy BBCode to HTML in-place';
+
+    public function handle(): int
+    {
+        $dry = $this->option('dry-run');
+        $chunk = (int)$this->option('chunk');
+        $limit = $this->option('limit') ? (int)$this->option('limit') : null;
+
+        $query = ForumPost::query()->orderBy('id');
+        $total = $limit ? min($query->count(), $limit) : $query->count();
+
+        $this->info('Converting forum posts (dry-run='.($dry ? 'yes' : 'no').')');
+        $this->info("Total posts to consider: {$total}");
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->start();
+
+        $converter = new BbcodeConverter();
+        $processed = 0;
+        $changed = 0;
+
+        try {
+            $query->chunkById($chunk, function ($posts) use (&$bar, &$processed, &$changed, $dry, $limit, $converter) {
+                foreach ($posts as $post) {
+                    if ($limit !== null && $processed >= $limit) {
+                        throw new \RuntimeException('limit_reached');
+                    }
+                    $bar->advance();
+                    $processed++;
+
+                    $old = $post->content ?? '';
+                    $new = $converter->convert($old);
+
+                    if ($old === $new) {
+                        continue;
+                    }
+
+                    $changed++;
+                    if ($dry) {
+                        $this->line('[dry] would update post ' . $post->id);
+                        continue;
+                    }
+
+                    $post->content = $new;
+                    $post->save();
+                }
+            });
+        } catch (\RuntimeException $e) {
+            if ($e->getMessage() !== 'limit_reached') {
+                throw $e;
+            }
+            // intentionally stop chunking when limit reached
+        }
+
+        $bar->finish();
+        $this->line('');
+
+        $this->info("Processed: {$processed} posts. Changed: {$changed} posts.");
+
+        if ($this->option('report')) {
+            $this->info('Conversion complete');
+        }
+
+        return 0;
+    }
+}

app/Console/Commands/ForumMigrateOld.php

@@ -0,0 +1,624 @@
+<?php
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Str;
+use App\Models\ForumCategory;
+use App\Models\User;
+use App\Models\ForumThread;
+use App\Models\ForumPost;
+use Exception;
+use App\Services\BbcodeConverter;
+
+class ForumMigrateOld extends Command
+{
+    protected $signature = 'forum:migrate-old {--dry-run} {--only=} {--limit=} {--chunk=500} {--report} {--repair-orphans}';
+
+    protected $description = 'Migrate legacy forum data from legacy DB into new forum tables';
+
+    protected string $logPath;
+
+    protected ?int $limit = null;
+
+    protected ?int $deletedUserId = null;
+
+    /** @var array<int,int> */
+    protected array $missingUserIds = [];
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->logPath = storage_path('logs/forum_migration.log');
+    }
+
+    public function handle(): int
+    {
+        $this->info('Starting forum migration');
+        $this->log('Starting forum migration');
+
+        $dry = $this->option('dry-run');
+        $only = $this->option('only');
+        $chunk = (int)$this->option('chunk');
+        $this->limit = $this->option('limit') !== null ? max(0, (int) $this->option('limit')) : null;
+
+        $only = $only === 'attachments' ? 'gallery' : $only;
+        if ($only && !in_array($only, ['categories', 'threads', 'posts', 'gallery', 'repair-orphans'], true)) {
+            $this->error('Invalid --only value. Allowed: categories, threads, posts, gallery (or attachments), repair-orphans.');
+            return 1;
+        }
+
+        if ($chunk < 1) {
+            $chunk = 500;
+        }
+
+        try {
+            if (!$only || $only === 'categories') {
+                $this->migrateCategories($dry);
+            }
+
+            if (!$only || $only === 'threads') {
+                $this->migrateThreads($dry, $chunk);
+            }
+
+            if (!$only || $only === 'posts') {
+                $this->migratePosts($dry, $chunk);
+            }
+
+            if (!$only || $only === 'gallery') {
+                $this->migrateGallery($dry, $chunk);
+            }
+
+            if ($this->option('repair-orphans') || $only === 'repair-orphans') {
+                $this->repairOrphanPosts($dry);
+            }
+
+            if ($this->option('report')) {
+                $this->generateReport();
+            }
+
+            $this->info('Forum migration finished');
+            $this->log('Forum migration finished');
+            return 0;
+        } catch (Exception $e) {
+            $this->error('Migration failed: ' . $e->getMessage());
+            $this->log('Migration failed: ' . $e->getMessage());
+            return 1;
+        }
+    }
+
+    protected function migrateCategories(bool $dry)
+    {
+        $this->info('Migrating categories');
+        $legacy = DB::connection('legacy');
+
+        $roots = $legacy->table('forum_topics')
+            ->select('root_id')
+            ->distinct()
+            ->where('root_id', '>', 0)
+            ->orderBy('root_id')
+            ->pluck('root_id');
+
+        if ($this->limit !== null && $this->limit > 0) {
+            $roots = $roots->take($this->limit);
+        }
+
+        $this->info('Found ' . $roots->count() . ' legacy root ids');
+
+        foreach ($roots as $rootId) {
+            $row = $legacy->table('forum_topics')->where('topic_id', $rootId)->first();
+            $name = $row->topic ?? 'Category ' . $rootId;
+            $slug = Str::slug(substr($name, 0, 150));
+
+            $this->line("-> root {$rootId}: {$name}");
+
+            if ($dry) {
+                $this->log("[dry] create category {$name} ({$slug})");
+                continue;
+            }
+
+            DB::transaction(function () use ($rootId, $name, $slug) {
+                ForumCategory::updateOrCreate(
+                    ['id' => $rootId],
+                    ['name' => $name, 'slug' => $slug]
+                );
+            }, 3);
+        }
+
+        $this->info('Categories migrated');
+    }
+
+    protected function migrateThreads(bool $dry, int $chunk)
+    {
+        $this->info('Migrating threads');
+        $legacy = DB::connection('legacy');
+
+        $query = $legacy->table('forum_topics')->orderBy('topic_id');
+
+        $total = $query->count();
+        if ($this->limit !== null && $this->limit > 0) {
+            $total = min($total, $this->limit);
+        }
+        $this->info("Total threads to process: {$total}");
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->start();
+
+        $processed = 0;
+        $limit = $this->limit;
+
+        // chunk by legacy primary key `topic_id`
+        $query->chunkById($chunk, function ($rows) use ($dry, $bar, &$processed, $limit) {
+            foreach ($rows as $r) {
+                if ($limit !== null && $limit > 0 && $processed >= $limit) {
+                    return false;
+                }
+
+                $bar->advance();
+                $processed++;
+
+                $data = [
+                    'id' => $r->topic_id,
+                    'category_id' => $this->resolveCategoryId($r->root_id ?? null, $r->topic_id),
+                    // resolve user id or assign to system user (1) when missing or not found
+                    'user_id' => $this->resolveUserId($r->user_id ?? null),
+                    'title' => $r->topic,
+                    'slug' => $this->uniqueSlug(Str::slug(substr($r->topic,0,200)) ?: 'thread-'.$r->topic_id, $r->topic_id),
+                    'content' => $r->preview ?? '',
+                    'views' => $r->views ?? 0,
+                    'is_locked' => isset($r->open) ? !((bool)$r->open) : false,
+                    'is_pinned' => false,
+                    'visibility' => $this->mapPrivilegeToVisibility($r->privilege ?? 0),
+                    'last_post_at' => $this->normalizeDate($r->last_update ?? null),
+                ];
+
+                if ($dry) {
+                    $this->log('[dry] thread: ' . $r->topic_id . ' - ' . $r->topic);
+                    continue;
+                }
+
+                DB::transaction(function () use ($data) {
+                    ForumThread::updateOrCreate(['id' => $data['id']], $data);
+                }, 3);
+            }
+        }, 'topic_id');
+
+        $bar->finish();
+        $this->line('');
+        $this->info('Threads migrated');
+    }
+
+    protected function migratePosts(bool $dry, int $chunk)
+    {
+        $this->info('Migrating posts');
+        $legacy = DB::connection('legacy');
+
+        $query = $legacy->table('forum_posts')->orderBy('post_id');
+        $total = $query->count();
+        if ($this->limit !== null && $this->limit > 0) {
+            $total = min($total, $this->limit);
+        }
+        $this->info("Total posts to process: {$total}");
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->start();
+
+        $processed = 0;
+        $limit = $this->limit;
+
+        // legacy forum_posts uses `post_id` as primary key
+        $query->chunkById($chunk, function ($rows) use ($dry, $bar, &$processed, $limit) {
+            foreach ($rows as $r) {
+                if ($limit !== null && $limit > 0 && $processed >= $limit) {
+                    return false;
+                }
+
+                $bar->advance();
+                $processed++;
+
+                $data = [
+                    'id' => $r->post_id,
+                    'thread_id' => $r->topic_id,
+                    'user_id' => $r->user_id ?? null,
+                    'content' => $this->convertLegacyMessage($r->message ?? ''),
+                    'is_edited' => isset($r->isupdated) ? (bool)$r->isupdated : false,
+                    'edited_at' => $r->updated ?? null,
+                ];
+
+                if ($dry) {
+                    $this->log('[dry] post: ' . $r->post_id);
+                    continue;
+                }
+
+                DB::transaction(function () use ($data) {
+                    ForumPost::updateOrCreate(['id' => $data['id']], $data);
+                }, 3);
+            }
+        }, 'post_id');
+
+        $bar->finish();
+        $this->line('');
+        $this->info('Posts migrated');
+    }
+
+    protected function mapPrivilegeToVisibility($priv)
+    {
+        // legacy privilege: 0 public, 1 members, 4 staff? adjust mapping conservatively
+        if ($priv >= 4) return 'staff';
+        if ($priv >= 1) return 'members';
+        return 'public';
+    }
+
+    protected function normalizeDate($val)
+    {
+        if (empty($val)) return null;
+        $s = trim((string)$val);
+        // legacy sometimes contains sentinel invalid dates like -0001-11-30 or zero dates
+        if (strpos($s, '-0001') !== false) return null;
+        if (strpos($s, '0000-00-00') !== false) return null;
+        if (strtotime($s) === false) return null;
+        return date('Y-m-d H:i:s', strtotime($s));
+    }
+
+    protected function uniqueSlug(string $base, int $id)
+    {
+        $slug = $base;
+        $i = 0;
+        while (ForumThread::where('slug', $slug)->where('id', '<>', $id)->exists()) {
+            $i++;
+            $slug = $base . '-' . $id;
+            // if somehow still exists, append counter
+            if (ForumThread::where('slug', $slug)->where('id', '<>', $id)->exists()) {
+                $slug = $base . '-' . $id . '-' . $i;
+            }
+        }
+        return $slug;
+    }
+
+    protected function resolveCategoryId($rootId, $topicId)
+    {
+        // prefer explicit rootId
+        if (!empty($rootId)) {
+            // ensure category exists
+            if (ForumCategory::where('id', $rootId)->exists()) return $rootId;
+        }
+
+        // if this topic itself is a category
+        if (ForumCategory::where('id', $topicId)->exists()) return $topicId;
+
+        // fallback: use first available category
+        $first = ForumCategory::first();
+        if ($first) return $first->id;
+
+        // as last resort, create Uncategorized
+        $cat = ForumCategory::create(['name' => 'Uncategorized', 'slug' => 'uncategorized']);
+        return $cat->id;
+    }
+
+    protected function resolveUserId($userId)
+    {
+        if (empty($userId)) {
+            return $this->resolveDeletedUserId();
+        }
+
+        // check users table in default connection
+        if (DB::table('users')->where('id', $userId)->exists()) {
+            return $userId;
+        }
+
+        $uid = (int) $userId;
+        if ($uid > 0 && !in_array($uid, $this->missingUserIds, true)) {
+            $this->missingUserIds[] = $uid;
+        }
+
+        return $this->resolveDeletedUserId();
+    }
+
+    protected function resolveDeletedUserId(): int
+    {
+        if ($this->deletedUserId !== null) {
+            return $this->deletedUserId;
+        }
+
+        $userOne = User::query()->find(1);
+        if ($userOne) {
+            $this->deletedUserId = 1;
+            return $this->deletedUserId;
+        }
+
+        $fallback = User::query()->orderBy('id')->first();
+        if ($fallback) {
+            $this->deletedUserId = (int) $fallback->id;
+            return $this->deletedUserId;
+        }
+
+        $created = User::query()->create([
+            'name' => 'Deleted User',
+            'email' => 'deleted-user+forum@skinbase.local',
+            'password' => Hash::make(Str::random(64)),
+            'role' => 'user',
+        ]);
+
+        $this->deletedUserId = (int) $created->id;
+
+        return $this->deletedUserId;
+    }
+
+    protected function convertLegacyMessage($msg)
+    {
+        $converter = new BbcodeConverter();
+        return $converter->convert($msg);
+    }
+
+    protected function repairOrphanPosts(bool $dry): void
+    {
+        $this->info('Repairing orphan posts');
+
+        $orphansQuery = ForumPost::query()->whereDoesntHave('thread')->orderBy('id');
+        $orphanCount = (clone $orphansQuery)->count();
+
+        if ($orphanCount === 0) {
+            $this->info('No orphan posts found.');
+            return;
+        }
+
+        $this->warn("Found {$orphanCount} orphan posts.");
+
+        $repairThread = $this->resolveOrCreateOrphanRepairThread($dry);
+
+        if ($repairThread === null) {
+            $this->warn('Unable to resolve/create repair thread in dry-run mode. Reporting only.');
+            (clone $orphansQuery)->limit(20)->get(['id', 'thread_id', 'user_id', 'created_at'])->each(function (ForumPost $post): void {
+                $this->line("- orphan post id={$post->id} thread_id={$post->thread_id} user_id={$post->user_id}");
+            });
+            return;
+        }
+
+        $this->line("Repair target thread: {$repairThread->id} ({$repairThread->slug})");
+
+        if ($dry) {
+            $this->info("[dry] Would reassign {$orphanCount} orphan posts to thread {$repairThread->id}");
+            (clone $orphansQuery)->limit(20)->get(['id', 'thread_id', 'user_id', 'created_at'])->each(function (ForumPost $post) use ($repairThread): void {
+                $this->log("[dry] orphan post {$post->id}: {$post->thread_id} -> {$repairThread->id}");
+            });
+            return;
+        }
+
+        $updated = 0;
+
+        (clone $orphansQuery)->chunkById(500, function ($posts) use ($repairThread, &$updated): void {
+            DB::transaction(function () use ($posts, $repairThread, &$updated): void {
+                /** @var ForumPost $post */
+                foreach ($posts as $post) {
+                    $post->thread_id = $repairThread->id;
+                    $post->is_edited = true;
+                    $post->edited_at = $post->edited_at ?: now();
+                    $post->save();
+                    $updated++;
+                }
+            }, 3);
+        }, 'id');
+
+        $latestPostAt = ForumPost::query()
+            ->where('thread_id', $repairThread->id)
+            ->max('created_at');
+
+        if ($latestPostAt) {
+            $repairThread->last_post_at = $latestPostAt;
+            $repairThread->save();
+        }
+
+        $this->info("Repaired orphan posts: {$updated}");
+        $this->log("Repaired orphan posts: {$updated} -> thread {$repairThread->id}");
+    }
+
+    protected function resolveOrCreateOrphanRepairThread(bool $dry): ?ForumThread
+    {
+        $slug = 'migration-orphaned-posts';
+
+        $existing = ForumThread::query()->where('slug', $slug)->first();
+        if ($existing) {
+            return $existing;
+        }
+
+        $category = ForumCategory::query()->ordered()->first();
+
+        if (!$category && !$dry) {
+            $category = ForumCategory::query()->create([
+                'name' => 'Migration Repairs',
+                'slug' => 'migration-repairs',
+                'parent_id' => null,
+                'position' => 9999,
+            ]);
+        }
+
+        if (!$category) {
+            return null;
+        }
+
+        if ($dry) {
+            return new ForumThread([
+                'id' => 0,
+                'slug' => $slug,
+                'category_id' => $category->id,
+            ]);
+        }
+
+        return ForumThread::query()->create([
+            'category_id' => $category->id,
+            'user_id' => $this->resolveDeletedUserId(),
+            'title' => 'Migration: Orphaned Posts Recovery',
+            'slug' => $slug,
+            'content' => 'Automatic recovery thread for legacy posts whose source thread no longer exists after migration.',
+            'views' => 0,
+            'is_locked' => false,
+            'is_pinned' => false,
+            'visibility' => 'staff',
+            'last_post_at' => now(),
+        ]);
+    }
+
+    protected function generateReport()
+    {
+        $this->info('Generating migration report');
+        $legacy = DB::connection('legacy');
+
+        $legacyCounts = [
+            'categories' => $legacy->table('forum_topics')->where('root_id','>',0)->distinct('root_id')->count('root_id'),
+            'threads' => $legacy->table('forum_topics')->count(),
+            'posts' => $legacy->table('forum_posts')->count(),
+        ];
+
+        $newCounts = [
+            'categories' => ForumCategory::count(),
+            'threads' => ForumThread::count(),
+            'posts' => ForumPost::count(),
+            'attachments' => DB::table('forum_attachments')->count(),
+        ];
+
+        $orphans = ForumPost::query()
+            ->whereDoesntHave('thread')
+            ->count();
+
+        $legacyThreadsWithLastUpdate = $legacy->table('forum_topics')->whereNotNull('last_update')->count();
+        $newThreadsWithLastPost = ForumThread::query()->whereNotNull('last_post_at')->count();
+        $legacyPostsWithPostDate = $legacy->table('forum_posts')->whereNotNull('post_date')->count();
+        $newPostsWithCreatedAt = ForumPost::query()->whereNotNull('created_at')->count();
+
+        $report = [
+            'missing_users_count' => count($this->missingUserIds),
+            'missing_users' => $this->missingUserIds,
+            'orphan_posts' => $orphans,
+            'timestamp_mismatches' => [
+                'threads_last_post_gap' => max(0, $legacyThreadsWithLastUpdate - $newThreadsWithLastPost),
+                'posts_created_at_gap' => max(0, $legacyPostsWithPostDate - $newPostsWithCreatedAt),
+            ],
+        ];
+
+        $this->info('Legacy counts: ' . json_encode($legacyCounts));
+        $this->info('New counts: ' . json_encode($newCounts));
+        $this->info('Report: ' . json_encode($report));
+        $this->log('Report: legacy=' . json_encode($legacyCounts) . ' new=' . json_encode($newCounts) . ' extra=' . json_encode($report));
+    }
+
+    protected function log(string $msg)
+    {
+        $line = '[' . date('c') . '] ' . $msg . "\n";
+        file_put_contents($this->logPath, $line, FILE_APPEND | LOCK_EX);
+    }
+
+    protected function migrateGallery(bool $dry, int $chunk)
+    {
+        $this->info('Migrating gallery (forum_topics_gallery → forum_attachments)');
+        $legacy = DB::connection('legacy');
+
+        if (!$legacy->getSchemaBuilder()->hasTable('forum_topics_gallery')) {
+            $this->info('No legacy forum_topics_gallery table found, skipping');
+            return;
+        }
+
+        $query = $legacy->table('forum_topics_gallery')->orderBy('id');
+        $total = $query->count();
+        if ($this->limit !== null && $this->limit > 0) {
+            $total = min($total, $this->limit);
+        }
+        $this->info("Total gallery items to process: {$total}");
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->start();
+
+        $processed = 0;
+        $limit = $this->limit;
+
+        $query->chunkById($chunk, function ($rows) use ($dry, $bar, &$processed, $limit) {
+            foreach ($rows as $r) {
+                if ($limit !== null && $limit > 0 && $processed >= $limit) {
+                    return false;
+                }
+
+                $bar->advance();
+                $processed++;
+
+                // expected legacy fields: id, name, category (topic id), folder, datum, description
+                $topicId = $r->category ?? ($r->topic_id ?? null);
+                $fileName = $r->name ?? null;
+                if (empty($topicId) || empty($fileName)) {
+                    $this->log('Skipping gallery row with missing topic or name: ' . json_encode($r));
+                    continue;
+                }
+
+                $nid = floor($topicId / 100);
+                $relativePath = "files/news/{$nid}/{$topicId}/{$fileName}";
+                $publicPath = public_path($relativePath);
+
+                $fileSize = null;
+                $mimeType = null;
+                $width = null;
+                $height = null;
+
+                if (file_exists($publicPath)) {
+                    $fileSize = filesize($publicPath);
+                    $img = @getimagesize($publicPath);
+                    if ($img !== false) {
+                        $width = $img[0];
+                        $height = $img[1];
+                        $mimeType = $img['mime'] ?? null;
+                    } else {
+                        $finfo = finfo_open(FILEINFO_MIME_TYPE);
+                        $mimeType = finfo_file($finfo, $publicPath);
+                        finfo_close($finfo);
+                    }
+                }
+
+                // find legacy first post id for this topic
+                $legacy = DB::connection('legacy');
+                $firstPostId = $legacy->table('forum_posts')
+                    ->where('topic_id', $topicId)
+                    ->orderBy('post_date')
+                    ->value('post_id');
+
+                // map to new forum_posts id (we preserved ids when migrating)
+                $postId = null;
+                if ($firstPostId && \App\Models\ForumPost::where('id', $firstPostId)->exists()) {
+                    $postId = $firstPostId;
+                } else {
+                    // fallback: find any post in new DB for thread
+                    $post = \App\Models\ForumPost::where('thread_id', $topicId)->orderBy('created_at')->first();
+                    if ($post) $postId = $post->id;
+                }
+
+                if (empty($postId)) {
+                    $this->log('No target post found for gallery item: topic ' . $topicId . ' file ' . $fileName);
+                    continue;
+                }
+
+                if ($dry) {
+                    $this->log("[dry] attach {$relativePath} -> post {$postId}");
+                    continue;
+                }
+
+                DB::transaction(function () use ($postId, $relativePath, $fileSize, $mimeType, $width, $height) {
+                    \App\Models\ForumAttachment::query()->updateOrCreate(
+                        [
+                            'post_id' => $postId,
+                            'file_path' => $relativePath,
+                        ],
+                        [
+                            'file_size' => $fileSize ?? 0,
+                            'mime_type' => $mimeType,
+                            'width' => $width,
+                            'height' => $height,
+                            'updated_at' => now(),
+                        ]
+                    );
+                }, 3);
+            }
+        }, 'id');
+
+        $bar->finish();
+        $this->line('');
+        $this->info('Gallery migrated');
+    }
+}

app/Console/Commands/ImportLegacyAwards.php

@@ -0,0 +1,288 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\ArtworkAward;
+use App\Models\ArtworkAwardStat;
+use App\Services\ArtworkAwardService;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Migrates legacy `users_opinions` (projekti_old_skinbase) into `artwork_awards`.
+ *
+ * Score mapping  (legacy score → new medal):
+ *   4 → gold   (weight 3)
+ *   3 → silver (weight 2)
+ *   2 → bronze (weight 1)
+ *   1 → skipped (too low to map meaningfully)
+ *
+ * Usage:
+ *   php artisan awards:import-legacy
+ *   php artisan awards:import-legacy --dry-run
+ *   php artisan awards:import-legacy --chunk=500
+ *   php artisan awards:import-legacy --skip-stats   (skip final stats recalc)
+ */
+class ImportLegacyAwards extends Command
+{
+    protected $signature = 'awards:import-legacy
+                            {--dry-run         : Preview only — no writes to DB}
+                            {--chunk=250       : Rows to process per batch}
+                            {--skip-stats      : Skip per-artwork stats recalculation at the end}
+                            {--force           : Overwrite existing awards instead of skipping duplicates}';
+
+    protected $description = 'Import legacy users_opinions into artwork_awards';
+
+    /** Maps legacy score value → medal string */
+    private const SCORE_MAP = [
+        4 => 'gold',
+        3 => 'silver',
+        2 => 'bronze',
+    ];
+
+    public function handle(ArtworkAwardService $service): int
+    {
+        $dryRun    = (bool) $this->option('dry-run');
+        $chunk     = max(1, (int) $this->option('chunk'));
+        $skipStats = (bool) $this->option('skip-stats');
+        $force     = (bool) $this->option('force');
+
+        if ($dryRun) {
+            $this->warn('[DRY-RUN] No data will be written.');
+        }
+
+        // Verify legacy connection is reachable
+        try {
+            DB::connection('legacy')->getPdo();
+        } catch (\Throwable $e) {
+            $this->error('Cannot connect to legacy database: ' . $e->getMessage());
+            return self::FAILURE;
+        }
+
+        if (! DB::connection('legacy')->getSchemaBuilder()->hasTable('users_opinions')) {
+            $this->error('Legacy table `users_opinions` not found.');
+            return self::FAILURE;
+        }
+
+        // Pre-load sets of valid artwork IDs and user IDs from the new DB
+        $this->info('Loading new-DB artwork and user ID sets…');
+        $validArtworkIds = DB::table('artworks')
+            ->whereNull('deleted_at')
+            ->pluck('id')
+            ->flip()   // flip so we can use isset() for O(1) lookup
+            ->all();
+
+        $validUserIds = DB::table('users')
+            ->whereNull('deleted_at')
+            ->pluck('id')
+            ->flip()
+            ->all();
+
+        $this->info(sprintf(
+            'Found %d artworks and %d users in new DB.',
+            count($validArtworkIds),
+            count($validUserIds)
+        ));
+
+        // Count legacy rows for progress bar
+        $total = DB::connection('legacy')
+            ->table('users_opinions')
+            ->count();
+
+        $this->info("Legacy rows to process: {$total}");
+
+        if ($total === 0) {
+            $this->warn('No legacy rows found. Nothing to do.');
+            return self::SUCCESS;
+        }
+
+        $stats = [
+            'imported'         => 0,
+            'skipped_score'    => 0,
+            'skipped_artwork'  => 0,
+            'skipped_user'     => 0,
+            'skipped_duplicate'=> 0,
+            'updated_force'    => 0,
+            'errors'           => 0,
+        ];
+
+        $affectedArtworkIds = [];
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->setFormat(' %current%/%max% [%bar%] %percent:3s%% | imported: %imported% | skipped: %skipped%');
+        $bar->setMessage('0', 'imported');
+        $bar->setMessage('0', 'skipped');
+        $bar->start();
+
+        DB::connection('legacy')
+            ->table('users_opinions')
+            ->orderBy('opinion_id')
+            ->chunk($chunk, function ($rows) use (
+                &$stats,
+                &$affectedArtworkIds,
+                $validArtworkIds,
+                $validUserIds,
+                $dryRun,
+                $force,
+                $bar
+            ) {
+                $inserts = [];
+                $now     = now();
+
+                foreach ($rows as $row) {
+                    $artworkId = (int) $row->artwork_id;
+                    $userId    = (int) $row->author_id; // author_id = the voter
+                    $score     = (int) $row->score;
+                    $postedAt  = $row->post_date ?? $now;
+
+                    // --- score → medal ---
+                    $medal = self::SCORE_MAP[$score] ?? null;
+                    if ($medal === null) {
+                        $stats['skipped_score']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    // --- Artwork must exist in new DB ---
+                    if (! isset($validArtworkIds[$artworkId])) {
+                        $stats['skipped_artwork']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    // --- User must exist in new DB ---
+                    if (! isset($validUserIds[$userId])) {
+                        $stats['skipped_user']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    if (! $dryRun) {
+                        if ($force) {
+                            // Upsert: update medal if row already exists
+                            $affected = DB::table('artwork_awards')
+                                ->where('artwork_id', $artworkId)
+                                ->where('user_id', $userId)
+                                ->update([
+                                    'medal'      => $medal,
+                                    'weight'     => ArtworkAward::WEIGHTS[$medal],
+                                    'updated_at' => $now,
+                                ]);
+
+                            if ($affected > 0) {
+                                $stats['updated_force']++;
+                                $affectedArtworkIds[$artworkId] = true;
+                                $bar->advance();
+                                continue;
+                            }
+                        } else {
+                            // Skip if already exists
+                            if (
+                                DB::table('artwork_awards')
+                                    ->where('artwork_id', $artworkId)
+                                    ->where('user_id', $userId)
+                                    ->exists()
+                            ) {
+                                $stats['skipped_duplicate']++;
+                                $bar->advance();
+                                continue;
+                            }
+                        }
+
+                        $inserts[] = [
+                            'artwork_id' => $artworkId,
+                            'user_id'    => $userId,
+                            'medal'      => $medal,
+                            'weight'     => ArtworkAward::WEIGHTS[$medal],
+                            'created_at' => $postedAt,
+                            'updated_at' => $postedAt,
+                        ];
+
+                        $affectedArtworkIds[$artworkId] = true;
+                    }
+
+                    $stats['imported']++;
+                    $bar->advance();
+                }
+
+                // Bulk insert the batch (DB::table bypasses the observer intentionally;
+                // stats are recalculated in bulk at the end for performance)
+                if (! $dryRun && ! empty($inserts)) {
+                    try {
+                        DB::table('artwork_awards')->insert($inserts);
+                    } catch (\Throwable $e) {
+                        // Fallback: insert one-by-one to isolate constraint violations
+                        foreach ($inserts as $row) {
+                            try {
+                                DB::table('artwork_awards')->insertOrIgnore([$row]);
+                            } catch (\Throwable) {
+                                $stats['errors']++;
+                            }
+                        }
+                    }
+                }
+
+                $skippedTotal = $stats['skipped_score']
+                    + $stats['skipped_artwork']
+                    + $stats['skipped_user']
+                    + $stats['skipped_duplicate'];
+
+                $bar->setMessage((string) $stats['imported'], 'imported');
+                $bar->setMessage((string) $skippedTotal, 'skipped');
+            });
+
+        $bar->finish();
+        $this->newLine(2);
+
+        // -------------------------------------------------------------------------
+        // Recalculate stats for every affected artwork
+        // -------------------------------------------------------------------------
+        if (! $dryRun && ! $skipStats && ! empty($affectedArtworkIds)) {
+            $artworkCount = count($affectedArtworkIds);
+            $this->info("Recalculating award stats for {$artworkCount} artworks…");
+
+            $statsBar = $this->output->createProgressBar($artworkCount);
+            $statsBar->start();
+
+            foreach (array_keys($affectedArtworkIds) as $artworkId) {
+                try {
+                    $service->recalcStats($artworkId);
+                } catch (\Throwable $e) {
+                    $this->newLine();
+                    $this->warn("Stats recalc failed for artwork #{$artworkId}: {$e->getMessage()}");
+                }
+                $statsBar->advance();
+            }
+
+            $statsBar->finish();
+            $this->newLine(2);
+        }
+
+        // -------------------------------------------------------------------------
+        // Summary
+        // -------------------------------------------------------------------------
+        $this->table(
+            ['Result', 'Count'],
+            [
+                ['Imported (new rows)',     $stats['imported']],
+                ['Forced updates',          $stats['updated_force']],
+                ['Skipped – bad score',     $stats['skipped_score']],
+                ['Skipped – artwork gone',  $stats['skipped_artwork']],
+                ['Skipped – user gone',     $stats['skipped_user']],
+                ['Skipped – duplicate',     $stats['skipped_duplicate']],
+                ['Errors',                  $stats['errors']],
+            ]
+        );
+
+        if ($dryRun) {
+            $this->warn('[DRY-RUN] Nothing was written. Re-run without --dry-run to apply.');
+        } else {
+            $this->info('Migration complete.');
+        }
+
+        return $stats['errors'] > 0 ? self::FAILURE : self::SUCCESS;
+    }
+}

app/Console/Commands/ImportLegacyComments.php

@@ -0,0 +1,266 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Migrates legacy `artworks_comments` (projekti_old_skinbase) into `artwork_comments`.
+ *
+ * Column mapping:
+ *   legacy.comment_id    → artwork_comments.legacy_id  (idempotency key)
+ *   legacy.artwork_id    → artwork_comments.artwork_id
+ *   legacy.user_id       → artwork_comments.user_id
+ *   legacy.description   → artwork_comments.content
+ *   legacy.date + .time  → artwork_comments.created_at / updated_at
+ *
+ * Ignored legacy columns: owner, author (username strings), owner_user_id
+ *
+ * Usage:
+ *   php artisan comments:import-legacy
+ *   php artisan comments:import-legacy --dry-run
+ *   php artisan comments:import-legacy --chunk=1000
+ *   php artisan comments:import-legacy --allow-guest-user=0  (import rows where user_id maps to 0 / not found, assigning a fallback user_id)
+ */
+class ImportLegacyComments extends Command
+{
+    protected $signature = 'comments:import-legacy
+                            {--dry-run       : Preview only — no writes to DB}
+                            {--chunk=500     : Rows to process per batch}
+                            {--skip-empty    : Skip comments with empty/whitespace-only content}';
+
+    protected $description = 'Import legacy artworks_comments into artwork_comments';
+
+    public function handle(): int
+    {
+        $dryRun    = (bool) $this->option('dry-run');
+        $chunk     = max(1, (int) $this->option('chunk'));
+        $skipEmpty = (bool) $this->option('skip-empty');
+
+        if ($dryRun) {
+            $this->warn('[DRY-RUN] No data will be written.');
+        }
+
+        // Verify legacy connection
+        try {
+            DB::connection('legacy')->getPdo();
+        } catch (\Throwable $e) {
+            $this->error('Cannot connect to legacy database: ' . $e->getMessage());
+            return self::FAILURE;
+        }
+
+        if (! DB::connection('legacy')->getSchemaBuilder()->hasTable('artworks_comments')) {
+            $this->error('Legacy table `artworks_comments` not found.');
+            return self::FAILURE;
+        }
+
+        if (! DB::getSchemaBuilder()->hasColumn('artwork_comments', 'legacy_id')) {
+            $this->error('Column `legacy_id` missing from `artwork_comments`. Run: php artisan migrate');
+            return self::FAILURE;
+        }
+
+        // Pre-load valid artwork IDs and user IDs from new DB for O(1) lookup
+        $this->info('Loading new-DB artwork and user ID sets…');
+
+        $validArtworkIds = DB::table('artworks')
+            ->whereNull('deleted_at')
+            ->pluck('id')
+            ->flip()
+            ->all();
+
+        $validUserIds = DB::table('users')
+            ->whereNull('deleted_at')
+            ->pluck('id')
+            ->flip()
+            ->all();
+
+        $this->info(sprintf(
+            'Found %d artworks and %d users in new DB.',
+            count($validArtworkIds),
+            count($validUserIds)
+        ));
+
+        // Already-imported legacy IDs (to resume safely)
+        $this->info('Loading already-imported legacy_ids…');
+        $alreadyImported = DB::table('artwork_comments')
+            ->whereNotNull('legacy_id')
+            ->pluck('legacy_id')
+            ->flip()
+            ->all();
+
+        $this->info(sprintf('%d comments already imported (will be skipped).', count($alreadyImported)));
+
+        $total = DB::connection('legacy')->table('artworks_comments')->count();
+        $this->info("Legacy rows to process: {$total}");
+
+        if ($total === 0) {
+            $this->warn('No legacy rows found. Nothing to do.');
+            return self::SUCCESS;
+        }
+
+        $stats = [
+            'imported'          => 0,
+            'skipped_duplicate' => 0,
+            'skipped_artwork'   => 0,
+            'skipped_user'      => 0,
+            'skipped_empty'     => 0,
+            'errors'            => 0,
+        ];
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->setFormat(' %current%/%max% [%bar%] %percent:3s%% | imported: %imported% | skipped: %skipped%');
+        $bar->setMessage('0', 'imported');
+        $bar->setMessage('0', 'skipped');
+        $bar->start();
+
+        DB::connection('legacy')
+            ->table('artworks_comments')
+            ->orderBy('comment_id')
+            ->chunk($chunk, function ($rows) use (
+                &$stats,
+                &$alreadyImported,
+                $validArtworkIds,
+                $validUserIds,
+                $dryRun,
+                $skipEmpty,
+                $bar
+            ) {
+                $inserts = [];
+                $now     = now();
+
+                foreach ($rows as $row) {
+                    $legacyId  = (int) $row->comment_id;
+                    $artworkId = (int) $row->artwork_id;
+                    $userId    = (int) $row->user_id;
+                    $content   = trim((string) ($row->description ?? ''));
+
+                    // --- Already imported ---
+                    if (isset($alreadyImported[$legacyId])) {
+                        $stats['skipped_duplicate']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    // --- Content ---
+                    if ($skipEmpty && $content === '') {
+                        $stats['skipped_empty']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    // Replace empty content with a placeholder so NOT NULL is satisfied
+                    if ($content === '') {
+                        $content = '[no content]';
+                    }
+
+                    // --- Artwork must exist ---
+                    if (! isset($validArtworkIds[$artworkId])) {
+                        $stats['skipped_artwork']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    // --- User must exist ---
+                    if (! isset($validUserIds[$userId])) {
+                        $stats['skipped_user']++;
+                        $bar->advance();
+                        continue;
+                    }
+
+                    // --- Build timestamp from separate date + time columns ---
+                    $createdAt = $this->buildTimestamp($row->date, $row->time, $now);
+
+                    if (! $dryRun) {
+                        $inserts[] = [
+                            'legacy_id'   => $legacyId,
+                            'artwork_id'  => $artworkId,
+                            'user_id'     => $userId,
+                            'content'     => $content,
+                            'is_approved' => 1,
+                            'created_at'  => $createdAt,
+                            'updated_at'  => $createdAt,
+                            'deleted_at'  => null,
+                        ];
+
+                        $alreadyImported[$legacyId] = true;
+                    }
+
+                    $stats['imported']++;
+                    $bar->advance();
+                }
+
+                if (! $dryRun && ! empty($inserts)) {
+                    try {
+                        DB::table('artwork_comments')->insert($inserts);
+                    } catch (\Throwable $e) {
+                        // Fallback: row-by-row with ignore on unique violations
+                        foreach ($inserts as $row) {
+                            try {
+                                DB::table('artwork_comments')->insertOrIgnore([$row]);
+                            } catch (\Throwable) {
+                                $stats['errors']++;
+                            }
+                        }
+                    }
+                }
+
+                $skippedTotal = $stats['skipped_duplicate']
+                    + $stats['skipped_artwork']
+                    + $stats['skipped_user']
+                    + $stats['skipped_empty'];
+
+                $bar->setMessage((string) $stats['imported'], 'imported');
+                $bar->setMessage((string) $skippedTotal, 'skipped');
+            });
+
+        $bar->finish();
+        $this->newLine(2);
+
+        // -------------------------------------------------------------------------
+        // Summary
+        // -------------------------------------------------------------------------
+        $this->table(
+            ['Result', 'Count'],
+            [
+                ['Imported',                    $stats['imported']],
+                ['Skipped – already imported',  $stats['skipped_duplicate']],
+                ['Skipped – artwork gone',       $stats['skipped_artwork']],
+                ['Skipped – user gone',          $stats['skipped_user']],
+                ['Skipped – empty content',      $stats['skipped_empty']],
+                ['Errors',                       $stats['errors']],
+            ]
+        );
+
+        if ($dryRun) {
+            $this->warn('[DRY-RUN] Nothing was written. Re-run without --dry-run to apply.');
+        } else {
+            $this->info('Migration complete.');
+        }
+
+        return $stats['errors'] > 0 ? self::FAILURE : self::SUCCESS;
+    }
+
+    /**
+     * Combine a legacy `date` (DATE) and `time` (TIME) column into a single datetime string.
+     * Falls back to $fallback when both are null.
+     */
+    private function buildTimestamp(mixed $date, mixed $time, \Illuminate\Support\Carbon $fallback): string
+    {
+        if (! $date) {
+            return $fallback->toDateTimeString();
+        }
+
+        $datePart = substr((string) $date, 0, 10);         // '2000-09-13'
+        $timePart = $time ? substr((string) $time, 0, 8) : '00:00:00';  // '09:34:27'
+
+        // Sanity-check: MySQL TIME can be negative or > 24h for intervals — clamp to midnight
+        if (! preg_match('/^\d{2}:\d{2}:\d{2}$/', $timePart) || $timePart < '00:00:00') {
+            $timePart = '00:00:00';
+        }
+
+        return $datePart . ' ' . $timePart;
+    }
+}

app/Console/Commands/ImportLegacyUsers.php

@@ -2,43 +2,79 @@
 
 namespace App\Console\Commands;
 
-use App\Models\User;
+use App\Support\UsernamePolicy;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Schema;
 use Illuminate\Support\Str;
 
 class ImportLegacyUsers extends Command
 {
-    protected $signature = 'skinbase:import-legacy-users {--chunk=200 : Chunk size for processing} {--force-reset-all : Force reset passwords for all imported users}';
+    protected $signature = 'skinbase:import-legacy-users {--chunk=200 : Chunk size for processing} {--force-reset-all : Force reset passwords for all imported users} {--dry-run : Preview which users would be skipped/deleted without making changes}';
     protected $description = 'Import legacy users into the new auth schema per legacy_users_migration spec';
 
-    protected array $usedUsernames = [];
-    protected array $usedEmails = [];
+    protected string $migrationLogPath;
+    /** @var array<int,true> Legacy user IDs that qualify for import */
+    protected array $activeUserIds = [];
 
     public function handle(): int
     {
-        $this->usedUsernames = User::pluck('username', 'username')->filter()->all();
-        $this->usedEmails = User::pluck('email', 'email')->filter()->all();
+        $this->migrationLogPath = storage_path('logs/username_migration.log');
+        @file_put_contents($this->migrationLogPath, '['.now()."] Starting legacy username policy migration\n", FILE_APPEND);
+
+        // Build the set of legacy user IDs that have any meaningful activity.
+        // Users outside this set will be skipped (or deleted from the new DB if already imported).
+        $this->activeUserIds = $this->buildActiveUserIds();
+        $this->info('Active legacy users (uploads / comments / forum): ' . count($this->activeUserIds));
 
         $chunk     = (int) $this->option('chunk');
+        $dryRun    = (bool) $this->option('dry-run');
         $imported  = 0;
         $skipped   = 0;
+        $purged    = 0;
 
-        if (! DB::getPdo()) {
+        if (! DB::connection('legacy')->getPdo()) {
             $this->error('Legacy DB connection "legacy" is not configured or reachable.');
             return self::FAILURE;
         }
 
-        DB::table('users')
-            ->chunkById($chunk, function ($rows) use (&$imported, &$skipped) {
+        DB::connection('legacy')->table('users')
+            ->chunkById($chunk, function ($rows) use (&$imported, &$skipped, &$purged, $dryRun) {
                 $ids = $rows->pluck('user_id')->all();
-                $stats = DB::table('users_statistics')
+                $stats = DB::connection('legacy')->table('users_statistics')
                     ->whereIn('user_id', $ids)
                     ->get()
                     ->keyBy('user_id');
 
                 foreach ($rows as $row) {
+                    $legacyId = (int) $row->user_id;
+
+                    // ── Inactive user: no uploads, no comments, no forum activity ──
+                    if (! isset($this->activeUserIds[$legacyId])) {
+                        // If already imported into the new DB, purge it.
+                        $existsInNew = DB::table('users')->where('id', $legacyId)->exists();
+                        if ($existsInNew) {
+                            if ($dryRun) {
+                                $this->warn("[dry] Would DELETE inactive user_id={$legacyId} from new DB");
+                            } else {
+                                $this->purgeNewUser($legacyId);
+                                $this->warn("[purge] Deleted inactive user_id={$legacyId} from new DB");
+                                $purged++;
+                            }
+                        } else {
+                            $this->line("[skip] user_id={$legacyId} no activity — skipping");
+                        }
+                        $skipped++;
+                        continue;
+                    }
+
+                    if ($dryRun) {
+                        $this->line("[dry] Would import user_id={$legacyId}");
+                        $imported++;
+                        continue;
+                    }
+
                     try {
                         $this->importRow($row, $stats[$row->user_id] ?? null);
                         $imported++;
@@ -49,17 +85,70 @@ class ImportLegacyUsers extends Command
                 }
             }, 'user_id');
 
-        $this->info("Imported: {$imported}, Skipped: {$skipped}");
+        $this->info("Imported: {$imported}, Skipped: {$skipped}, Purged: {$purged}");
         return self::SUCCESS;
     }
 
+    /**
+     * Build a lookup array of legacy user IDs that qualify for import:
+     * — uploaded at least one artwork (users_statistics.uploads > 0)
+     * — posted at least one artwork comment (artworks_comments.user_id)
+     * — created or posted to a forum thread (forum_topics / forum_posts)
+     *
+     * @return array<int,true>
+     */
+    protected function buildActiveUserIds(): array
+    {
+        $rows = DB::connection('legacy')->select("
+            SELECT DISTINCT user_id FROM users_statistics WHERE uploads > 0
+            UNION
+            SELECT DISTINCT user_id FROM artworks_comments WHERE user_id > 0
+            UNION
+            SELECT DISTINCT user_id FROM forum_posts WHERE user_id > 0
+            UNION
+            SELECT DISTINCT user_id FROM forum_topics WHERE user_id > 0
+        ");
+
+        $map = [];
+        foreach ($rows as $r) {
+            $map[(int) $r->user_id] = true;
+        }
+        return $map;
+    }
+
+    /**
+     * Remove all new-DB records for a given legacy user ID.
+     * Covers: users, user_profiles, user_statistics, username_redirects.
+     */
+    protected function purgeNewUser(int $userId): void
+    {
+        DB::transaction(function () use ($userId) {
+            DB::table('username_redirects')->where('user_id', $userId)->delete();
+            DB::table('user_statistics')->where('user_id', $userId)->delete();
+            DB::table('user_profiles')->where('user_id', $userId)->delete();
+            DB::table('users')->where('id', $userId)->delete();
+        });
+    }
+
     protected function importRow($row, $statRow = null): void
     {
         $legacyId = (int) $row->user_id;
-        $baseUsername = $this->sanitizeUsername($row->uname ?: ('user'.$legacyId));
-        $username = $this->uniqueUsername($baseUsername);
 
-        $email = $this->prepareEmail($row->email ?? null, $username);
+        // Use legacy username as-is (sanitized only, no numeric suffixing — was unique in old DB).
+        $username = $this->sanitizeUsername((string) ($row->uname ?: ('user' . $legacyId)));
+
+        $normalizedLegacy = UsernamePolicy::normalize((string) ($row->uname ?? ''));
+        if ($normalizedLegacy !== $username) {
+            @file_put_contents(
+                $this->migrationLogPath,
+                sprintf("[%s] user_id=%d old=%s new=%s\n", now()->toDateTimeString(), $legacyId, $normalizedLegacy, $username),
+                FILE_APPEND
+            );
+        }
+
+        // Use the real legacy email; only synthesise a placeholder when missing.
+        $rawEmail = $row->email ? strtolower(trim($row->email)) : null;
+        $email = $rawEmail ?: ($this->sanitizeEmailLocal($username) . '@users.skinbase.org');
 
         $legacyPassword = $row->password2 ?: $row->password ?: null;
 
@@ -84,26 +173,40 @@ class ImportLegacyUsers extends Command
 
         DB::transaction(function () use ($legacyId, $username, $email, $passwordHash, $row, $uploads, $downloads, $pageviews, $awards) {
             $now = now();
+            $alreadyExists = DB::table('users')->where('id', $legacyId)->exists();
 
-            DB::table('users')->insert([
-                'id' => $legacyId,
+            // All fields synced from legacy on every run
+            $sharedFields = [
                 'username'             => $username,
+                'username_changed_at'  => $now,
                 'name'                 => $row->real_name ?: $username,
                 'email'                => $email,
-                'password' => $passwordHash,
                 'is_active'            => (int) ($row->active ?? 1) === 1,
                 'needs_password_reset' => true,
                 'role'                 => 'user',
                 'legacy_password_algo' => null,
                 'last_visit_at'        => $row->LastVisit ?: null,
-                'created_at' => $row->joinDate ?: $now,
                 'updated_at'           => $now,
-            ]);
+            ];
 
-            DB::table('user_profiles')->insert([
-                'user_id' => $legacyId,
-                'bio' => $row->about_me ?: $row->description ?: null,
-                'avatar' => $row->picture ?: null,
+            if ($alreadyExists) {
+                // Sync all fields from legacy — password is never overwritten on re-runs
+                // (unless --force-reset-all was passed, in which case the caller handles it
+                // separately outside this transaction).
+                DB::table('users')->where('id', $legacyId)->update($sharedFields);
+            } else {
+                DB::table('users')->insert(array_merge($sharedFields, [
+                    'id'         => $legacyId,
+                    'password'   => $passwordHash,
+                    'created_at' => $row->joinDate ?: $now,
+                ]));
+            }
+
+            DB::table('user_profiles')->updateOrInsert(
+                ['user_id' => $legacyId],
+                [
+                    'about'          => $row->about_me ?: $row->description ?: null,
+                    'avatar_legacy'  => $row->picture ?: null,
                     'cover_image'    => $row->cover_art ?: null,
                     'country'        => $row->country ?: null,
                     'country_code'   => $row->country_code ? substr($row->country_code, 0, 2) : null,
@@ -111,29 +214,37 @@ class ImportLegacyUsers extends Command
                     'birthdate'      => $row->birth ?: null,
                     'gender'         => $row->gender ?: 'X',
                     'website'        => $row->web ?: null,
-                'created_at' => $now,
                     'updated_at'     => $now,
-            ]);
+                ]
+            );
 
-            if (!empty($row->web)) {
-                DB::table('user_social_links')->insert([
+            // Do not duplicate `website` into `user_social_links` — keep canonical site in `user_profiles.website`.
+
+            DB::table('user_statistics')->updateOrInsert(
+                ['user_id' => $legacyId],
+                [
+                    'uploads_count'                => $uploads,
+                    'downloads_received_count'     => $downloads,
+                    'artwork_views_received_count' => $pageviews,
+                    'awards_received_count'        => $awards,
+                    'updated_at'                   => $now,
+                ]
+            );
+
+            if (Schema::hasTable('username_redirects')) {
+                $old = UsernamePolicy::normalize((string) ($row->uname ?? ''));
+                if ($old !== '' && $old !== $username) {
+                    DB::table('username_redirects')->updateOrInsert(
+                        ['old_username' => $old],
+                        [
+                            'new_username' => $username,
                             'user_id' => $legacyId,
-                    'platform' => 'website',
-                    'url' => $row->web,
                             'created_at' => $now,
                             'updated_at' => $now,
-                ]);
+                        ]
+                    );
+                }
             }
-
-            DB::table('user_statistics')->insert([
-                'user_id' => $legacyId,
-                'uploads' => $uploads,
-                'downloads' => $downloads,
-                'pageviews' => $pageviews,
-                'awards' => $awards,
-                'created_at' => $now,
-                'updated_at' => $now,
-            ]);
         });
     }
 
@@ -151,45 +262,7 @@ class ImportLegacyUsers extends Command
 
     protected function sanitizeUsername(string $username): string
     {
-        $username = strtolower(trim($username));
-        $username = preg_replace('/[^a-z0-9._-]/', '-', $username) ?: 'user';
-        return trim($username, '.-') ?: 'user';
-    }
-
-    protected function uniqueUsername(string $base): string
-    {
-        $name = $base;
-        $i = 1;
-        while (isset($this->usedUsernames[$name]) || DB::table('users')->where('username', $name)->exists()) {
-            $name = $base . '-' . $i;
-            $i++;
-        }
-        $this->usedUsernames[$name] = $name;
-        return $name;
-    }
-
-    protected function prepareEmail(?string $legacyEmail, string $username): string
-    {
-        $legacyEmail = $legacyEmail ? strtolower(trim($legacyEmail)) : null;
-        $baseLocal = $this->sanitizeEmailLocal($username);
-        $domain = 'users.skinbase.org';
-
-        $email = $legacyEmail ?: ($baseLocal . '@' . $domain);
-        $email = $this->uniqueEmail($email, $baseLocal, $domain);
-        return $email;
-    }
-
-    protected function uniqueEmail(string $email, string $baseLocal, string $domain): string
-    {
-        $i = 1;
-        $local = explode('@', $email)[0];
-        $current = $email;
-        while (isset($this->usedEmails[$current]) || DB::table('users')->where('email', $current)->exists()) {
-            $current = $local . $i . '@' . $domain;
-            $i++;
-        }
-        $this->usedEmails[$current] = $current;
-        return $current;
+        return UsernamePolicy::sanitizeLegacy($username);
     }
 
     protected function sanitizeEmailLocal(string $value): string

app/Console/Commands/MigrateFavourites.php

@@ -0,0 +1,325 @@
+<?php
+
+namespace App\Console\Commands;
+
+use Carbon\Carbon;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+/**
+ * php artisan skinbase:migrate-favourites
+ *
+ * Migrates rows from the legacy `favourites` table (projekti_old_skinbase)
+ * into the new `artwork_favourites` table on the default connection.
+ *
+ * Skipped rows (logged as warnings):
+ *   - artwork_id not found in new artworks table
+ *   - user_id not found in new OR legacy users table (unless --import-missing-users)
+ *   - row already imported (duplicate legacy_id)
+ *   - would create a duplicate (user_id, artwork_id) pair
+ *
+ * Dropped legacy columns (not migrated):
+ *   - user_type  — membership tier, not relevant to the relationship
+ *   - author_id  — always derivable via artworks.user_id
+ *
+ * Options:
+ *   --dry-run                Preview without writing
+ *   --chunk=500              Rows per batch
+ *   --start-id=0             Resume from this favourite_id
+ *   --limit=0                Stop after N inserts (0 = no limit)
+ *   --import-missing-users   Auto-create a stub user from legacy data when the
+ *                            user is missing from the new DB (needs_password_reset=true)
+ *   --legacy-connection      Override legacy DB connection name (default: legacy)
+ *   --legacy-table           Override legacy favourites table name (default: favourites)
+ *   --legacy-users-table     Override legacy users table name (default: users)
+ */
+class MigrateFavourites extends Command
+{
+    protected $signature = 'skinbase:migrate-favourites
+                            {--dry-run : Preview changes without writing to the database}
+                            {--chunk=500 : Number of rows to process per batch}
+                            {--start-id=0 : Resume processing from this favourite_id}
+                            {--limit=0 : Stop after inserting this many rows (0 = unlimited)}
+                            {--import-missing-users : Auto-create stub users from legacy data when missing from new DB}
+                            {--legacy-connection=legacy : Name of the legacy DB connection}
+                            {--legacy-table=favourites : Name of the legacy favourites table}
+                            {--legacy-users-table=users : Name of the legacy users table}';
+
+    protected $description = 'Migrate legacy favourites into artwork_favourites.';
+
+    // ── Counters ─────────────────────────────────────────────────────────────
+
+    private int $inserted      = 0;
+    private int $skipped       = 0;
+    private int $total         = 0;
+    private int $usersImported = 0;
+
+    // ── Runtime config (set in handle()) ─────────────────────────────────────
+
+    private bool   $importMissingUsers = false;
+    private string $legacyConn        = 'legacy';
+    private string $legacyUsersTable  = 'users';
+
+    public function handle(): int
+    {
+        $dryRun    = (bool) $this->option('dry-run');
+        $chunk     = max(1, (int) $this->option('chunk'));
+        $startId   = max(0, (int) $this->option('start-id'));
+        $limit     = max(0, (int) $this->option('limit'));
+
+        $this->importMissingUsers = (bool) $this->option('import-missing-users');
+        $this->legacyConn         = (string) $this->option('legacy-connection');
+        $this->legacyUsersTable   = (string) $this->option('legacy-users-table');
+        $legacyTable              = (string) $this->option('legacy-table');
+
+        $this->info("Migrating <comment>{$this->legacyConn}.{$legacyTable}</comment> → <info>artwork_favourites</info>");
+
+        if ($this->importMissingUsers) {
+            $this->warn('--import-missing-users: stub users will be created with needs_password_reset=true.');
+        }
+
+        if ($dryRun) {
+            $this->warn('DRY-RUN mode — no rows will be written.');
+        }
+        if ($startId > 0) {
+            $this->line("Resuming from favourite_id >= {$startId}");
+        }
+        if ($limit > 0) {
+            $this->line("Will stop after {$limit} inserts.");
+        }
+
+        $query = DB::connection($this->legacyConn)
+            ->table($legacyTable)
+            ->orderBy('favourite_id');
+
+        if ($startId > 0) {
+            $query->where('favourite_id', '>=', $startId);
+        }
+
+        $query->chunkById(
+            $chunk,
+            function ($rows) use ($dryRun, $limit): bool {
+                foreach ($rows as $row) {
+                    $this->total++;
+
+                    if ($limit > 0 && $this->inserted >= $limit) {
+                        return false; // stop chunking
+                    }
+
+                    if ($this->processRow($row, $dryRun) === false) {
+                        $this->skipped++;
+                    }
+                }
+                return true;
+            },
+            'favourite_id',
+        );
+
+        $this->newLine();
+        $this->info(sprintf(
+            'Done. %d scanned, %d %s, %d skipped%s.',
+            $this->total,
+            $this->inserted,
+            $dryRun ? 'would be inserted' : 'inserted',
+            $this->skipped,
+            $this->usersImported > 0
+                ? ", {$this->usersImported} stub users " . ($dryRun ? 'would be ' : '') . 'created'
+                : '',
+        ));
+
+        return self::SUCCESS;
+    }
+
+    // ── Row processing ────────────────────────────────────────────────────────
+
+    /**
+     * Process a single legacy row.  Returns true on success, false when skipped.
+     */
+    private function processRow(object $row, bool $dryRun): bool
+    {
+        $legacyId  = (int) ($row->favourite_id ?? 0);
+        $artworkId = (int) ($row->artwork_id   ?? 0);
+        $userId    = (int) ($row->user_id      ?? 0);
+        $datum     = $row->datum ?? null;
+
+        // ── Validate IDs ────────────────────────────────────────────────────
+
+        if ($artworkId <= 0 || $userId <= 0) {
+            $this->skip($legacyId, "invalid artwork_id={$artworkId} or user_id={$userId}");
+            return false;
+        }
+
+        if (! DB::table('artworks')->where('id', $artworkId)->exists()) {
+            $this->skip($legacyId, "artwork #{$artworkId} not found in new DB");
+            return false;
+        }
+
+        if (! DB::table('users')->where('id', $userId)->exists()) {
+            if ($this->importMissingUsers) {
+                if (! $this->importUserStub($userId, $dryRun)) {
+                    $this->skip($legacyId, "user #{$userId} not found in legacy DB either — skipped");
+                    return false;
+                }
+            } else {
+                $this->skip($legacyId, "user #{$userId} not found in new DB (use --import-missing-users to auto-create)");
+                return false;
+            }
+        }
+
+        // ── Idempotency guards ───────────────────────────────────────────────
+
+        if (DB::table('artwork_favourites')->where('legacy_id', $legacyId)->exists()) {
+            // Already imported — silently skip (not counted as "skipped" error)
+            return true;
+        }
+
+        if (DB::table('artwork_favourites')
+                ->where('user_id', $userId)
+                ->where('artwork_id', $artworkId)
+                ->exists()
+        ) {
+            $this->skip($legacyId, "duplicate (user={$userId}, artwork={$artworkId}) already exists");
+            return false;
+        }
+
+        // ── Map timestamp ────────────────────────────────────────────────────
+
+        $createdAt = $this->parseDate($datum);
+
+        // ── Insert ───────────────────────────────────────────────────────────
+
+        if (! $dryRun) {
+            DB::table('artwork_favourites')->insert([
+                'user_id'    => $userId,
+                'artwork_id' => $artworkId,
+                'legacy_id'  => $legacyId,
+                'created_at' => $createdAt,
+                'updated_at' => $createdAt,
+            ]);
+        }
+
+        $this->inserted++;
+
+        if ($this->inserted % 500 === 0) {
+            $this->line("  {$this->inserted} inserted, {$this->skipped} skipped…");
+        }
+
+        return true;
+    }
+
+    // ── Helpers ───────────────────────────────────────────────────────────────
+
+    /**
+     * Look up $userId in the legacy users table and create a stub record in
+     * the new users table preserving the same primary key.
+     *
+     * The stub has:
+     *   - needs_password_reset = true  (user must reset before logging in)
+     *   - legacy_password_algo = 'legacy'  (marks imported credential)
+     *   - is_active determined from legacy `active` flag
+     *   - email placeholder if original email is null or already taken
+     *
+     * @return bool  true = stub created (or already existed), false = not in legacy DB
+     */
+    private function importUserStub(int $userId, bool $dryRun): bool
+    {
+        // Already exists — nothing to do.
+        if (DB::table('users')->where('id', $userId)->exists()) {
+            return true;
+        }
+
+        $legacyUser = DB::connection($this->legacyConn)
+            ->table($this->legacyUsersTable)
+            ->where('user_id', $userId)
+            ->first();
+
+        if (! $legacyUser) {
+            return false;
+        }
+
+        // ── Map fields ──────────────────────────────────────────────────────
+
+        $username = trim((string) ($legacyUser->uname ?? '')) ?: "user_{$userId}";
+
+        // Ensure username is unique in the new DB.
+        if (DB::table('users')->where('username', $username)->exists()) {
+            $username = $username . '_' . $userId;
+        }
+
+        $name  = trim((string) ($legacyUser->real_name ?? '')) ?: $username;
+        $email = trim((string) ($legacyUser->email     ?? ''));
+
+        // Resolve email: use placeholder when blank or already taken.
+        if ($email === '' || DB::table('users')->where('email', $email)->exists()) {
+            $email = "legacy_{$userId}@legacy.skinbase.org";
+        }
+
+        $isActive  = ((int) ($legacyUser->active ?? 0)) === 1;
+        $createdAt = $this->parseDate($legacyUser->joinDate   ?? null);
+        $lastVisit = $this->parseDate($legacyUser->LastVisit  ?? null);
+
+        $stub = [
+            'id'                    => $userId,
+            'username'              => $username,
+            'name'                  => $name,
+            'email'                 => $email,
+            'password'              => bcrypt(Str::random(48)), // unusable random password
+            'needs_password_reset'  => true,
+            'legacy_password_algo'  => 'legacy',
+            'is_active'             => $isActive,
+            'role'                  => 'user',
+            'last_visit_at'         => $lastVisit !== $createdAt ? $lastVisit : null,
+            'created_at'            => $createdAt,
+            'updated_at'            => $createdAt,
+        ];
+
+        $msg = "Stub user created: #{$userId} ({$username}, {$email})";
+
+        if ($dryRun) {
+            $this->line("  [dry] {$msg}");
+            $this->usersImported++;
+            return true;
+        }
+
+        try {
+            // Force explicit ID insert — MySQL respects it even with auto_increment.
+            DB::table('users')->insert($stub);
+            $this->usersImported++;
+            $this->line("  <info>{$msg}</info>");
+            Log::info("skinbase:migrate-favourites {$msg}");
+        } catch (\Throwable $e) {
+            $err = "Failed to create stub user #{$userId}: {$e->getMessage()}";
+            $this->warn("  {$err}");
+            Log::error("skinbase:migrate-favourites {$err}");
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Parse a legacy date value (DATE string / null / zero-date) to a
+     * full datetime string safe for MySQL.
+     */
+    private function parseDate(mixed $value): string
+    {
+        if (empty($value) || $value === '0000-00-00' || $value === '0000-00-00 00:00:00') {
+            return Carbon::now()->toDateTimeString();
+        }
+
+        try {
+            return Carbon::parse((string) $value)->toDateTimeString();
+        } catch (\Throwable) {
+            return Carbon::now()->toDateTimeString();
+        }
+    }
+
+    private function skip(int $legacyId, string $reason): void
+    {
+        $msg = "SKIP favourite#{$legacyId}: {$reason}";
+        $this->warn("  {$msg}");
+        Log::warning("skinbase:migrate-favourites {$msg}");
+    }
+}

app/Console/Commands/MigrateFollows.php

@@ -0,0 +1,351 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Support\UsernamePolicy;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Str;
+
+/**
+ * Migrates legacy friends_list (from the legacy DB connection) into user_followers.
+ *
+ * Usage:
+ *   php artisan skinbase:migrate-follows [--dry-run] [--chunk=1000] [--import-missing-users]
+ *
+ * Legacy table: friends_list
+ *   user_id    -> follower_id  (the user who added the friend = someone who follows)
+ *   friend_id  -> user_id      (the user being followed)
+ *
+ * With --import-missing-users: any user referenced in friends_list that does not
+ * exist in the new DB will be fetched from the legacy `users` table and created
+ * as a stub before the follow row is inserted.
+ */
+class MigrateFollows extends Command
+{
+    protected $signature = 'skinbase:migrate-follows
+        {--dry-run            : Simulate without writing to the database}
+        {--chunk=1000         : Number of rows to process per batch}
+        {--import-missing-users : Import unknown users from legacy DB instead of skipping them}';
+
+    protected $description = 'Migrate legacy friends_list into user_followers';
+
+    /** Cache per-run: id => true (resolved) | null (not in legacy DB) | false (import error) */
+    private array $legacyUserCache = [];
+
+    public function handle(): int
+    {
+        $isDryRun      = (bool) $this->option('dry-run');
+        $chunkSize     = max(1, (int) $this->option('chunk'));
+        $importMissing = (bool) $this->option('import-missing-users');
+
+        $this->info($isDryRun
+            ? '🔍  Dry-run mode – nothing will be written.'
+            : '🚀  Live mode – writing to user_followers.'
+        );
+        if ($importMissing) {
+            $this->info('👤  --import-missing-users: orphan users will be fetched from legacy DB.');
+        }
+
+        try {
+            $totalLegacy = DB::connection('legacy')->table('friends_list')->count();
+        } catch (\Throwable $e) {
+            $this->error('Cannot read legacy friends_list: ' . $e->getMessage());
+            return self::FAILURE;
+        }
+
+        $this->info("Total rows in legacy friends_list: {$totalLegacy}");
+
+        $validUserIds = DB::table('users')->pluck('id')->flip()->all();
+
+        $stats = [
+            'processed'             => 0,
+            'inserted'              => 0,
+            'duplicates'            => 0,
+            'self_follows'          => 0,
+            'invalid'               => 0,   // total orphan rows skipped
+            'invalid_zero_id'       => 0,   // follower_id or friend_id was 0
+            'invalid_not_in_new'    => 0,   // not in new DB (--import-missing-users not used)
+            'invalid_not_in_legacy' => 0,   // not in new DB AND not in legacy DB
+            'invalid_import_error'  => 0,   // in legacy DB but stub import failed
+            'users_imported'        => 0,
+            'errors'                => 0,
+        ];
+
+        $logPath = storage_path('logs/migrate_follows.log');
+        $logFile = fopen($logPath, 'a');
+        $this->logLine($logFile, '=== migrate-follows started at ' . now()->toISOString()
+            . " (dry_run={$isDryRun}, import_missing={$importMissing}) ===");
+
+        $chunkNum    = 0;
+        $reportEvery = max(1, (int) ceil($totalLegacy / $chunkSize / 10));
+
+        DB::connection('legacy')
+            ->table('friends_list')
+            ->orderBy('id')
+            ->chunk($chunkSize, function ($rows) use (
+                $isDryRun,
+                $importMissing,
+                &$validUserIds,
+                &$stats,
+                &$chunkNum,
+                $reportEvery,
+                $totalLegacy,
+                $logFile
+            ) {
+                $toInsert = [];
+
+                foreach ($rows as $row) {
+                    $stats['processed']++;
+
+                    $followerId = (int) ($row->user_id   ?? 0);
+                    $followedId = (int) ($row->friend_id ?? 0);
+                    $createdAt  = $row->date_added ?? now();
+
+                    if ($followerId === $followedId) {
+                        $stats['self_follows']++;
+                        $this->logLine($logFile, "SKIP self-follow: user_id={$followerId}");
+                        continue;
+                    }
+
+                    // Try to resolve any user_id that isn't in the new DB yet
+                    $skipReasons = [];
+                    $sides = ['follower' => $followerId, 'followed' => $followedId];
+
+                    foreach ($sides as $role => $uid) {
+                        if (isset($validUserIds[$uid])) {
+                            continue; // already valid
+                        }
+
+                        if ($uid === 0) {
+                            $skipReasons[] = "{$role}_id is 0/null";
+                            $stats['invalid_zero_id']++;
+                            continue;
+                        }
+
+                        if (! $importMissing) {
+                            $skipReasons[] = "{$role}={$uid} not in users table (use --import-missing-users to auto-import)";
+                            $stats['invalid_not_in_new']++;
+                            continue;
+                        }
+
+                        // ensureLegacyUser returns: true = resolved, null = not in legacy, false = import error
+                        $result = $this->ensureLegacyUser($uid, $isDryRun, $logFile);
+                        if ($result === true) {
+                            $validUserIds[$uid] = true;
+                            $stats['users_imported']++;
+                        } elseif ($result === null) {
+                            $skipReasons[] = "{$role}={$uid} not found in legacy DB";
+                            $stats['invalid_not_in_legacy']++;
+                        } else {
+                            $skipReasons[] = "{$role}={$uid} found in legacy DB but import failed";
+                            $stats['invalid_import_error']++;
+                        }
+                    }
+
+                    if (! isset($validUserIds[$followerId]) || ! isset($validUserIds[$followedId])) {
+                        $stats['invalid']++;
+                        $reason = implode('; ', $skipReasons) ?: 'unknown';
+                        $this->logLine($logFile, "SKIP orphan [row_id={$row->id}] follower={$followerId} followed={$followedId} — {$reason}");
+                        continue;
+                    }
+
+                    $toInsert[] = [
+                        'follower_id' => $followerId,
+                        'user_id'     => $followedId,
+                        'created_at'  => $createdAt,
+                    ];
+                }
+
+                if (! $isDryRun && ! empty($toInsert)) {
+                    try {
+                        $inserted = DB::table('user_followers')->insertOrIgnore($toInsert);
+                        $stats['inserted']   += $inserted;
+                        $stats['duplicates'] += count($toInsert) - $inserted;
+                    } catch (\Throwable $e) {
+                        $stats['errors']++;
+                        $this->logLine($logFile, 'ERROR batch insert: ' . $e->getMessage());
+                    }
+                } elseif ($isDryRun) {
+                    $stats['inserted'] += count($toInsert);
+                }
+
+                $chunkNum++;
+                if ($chunkNum % $reportEvery === 0 || $stats['processed'] >= $totalLegacy) {
+                    $pct = $totalLegacy > 0 ? round($stats['processed'] / $totalLegacy * 100) : 100;
+                    $this->line("  {$stats['processed']} / {$totalLegacy} rows ({$pct}%)"
+                        . "  inserted: {$stats['inserted']}"
+                        . "  imported: {$stats['users_imported']}"
+                        . "  skipped: " . ($stats['self_follows'] + $stats['invalid']));
+                }
+            });
+
+        $this->newLine();
+
+        if (! $isDryRun) {
+            $this->info('Backfilling user_statistics counters...');
+            $this->backfillCounters();
+        }
+
+        $this->table(
+            ['Metric', 'Count'],
+            [
+                ['Processed',                          $stats['processed']],
+                ['Inserted',                           $stats['inserted']],
+                ['Duplicates (already exist)',         $stats['duplicates']],
+                ['Self-follows skipped',               $stats['self_follows']],
+                ['Users stub-imported from legacy',    $stats['users_imported']],
+                ['Invalid (orphan) — total',           $stats['invalid']],
+                ['  ↳ zero/null user_id',              $stats['invalid_zero_id']],
+                ['  ↳ not in new DB (not imported)',   $stats['invalid_not_in_new']],
+                ['  ↳ not in legacy DB either',        $stats['invalid_not_in_legacy']],
+                ['  ↳ legacy import error',            $stats['invalid_import_error']],
+                ['Errors',                             $stats['errors']],
+            ]
+        );
+
+        $summary = "Processed={$stats['processed']} Inserted={$stats['inserted']} "
+            . "Duplicates={$stats['duplicates']} SelfFollows={$stats['self_follows']} "
+            . "UsersImported={$stats['users_imported']} Invalid={$stats['invalid']} "
+            . "(ZeroId={$stats['invalid_zero_id']} NotInNew={$stats['invalid_not_in_new']} "
+            . "NotInLegacy={$stats['invalid_not_in_legacy']} ImportError={$stats['invalid_import_error']}) "
+            . "Errors={$stats['errors']}";
+
+        $this->logLine($logFile, "=== DONE: {$summary} ===");
+        fclose($logFile);
+
+        $this->info("Log written to: {$logPath}");
+
+        return self::SUCCESS;
+    }
+
+    // -------------------------------------------------------------------------
+
+    /**
+     * Ensure a legacy user_id exists in the new `users` table.
+     *
+     * Returns:
+     *   true  – user is valid (was already there, or was just imported / dry-run pretend-imported)
+     *   null  – user not found in the legacy DB either → cannot be imported
+     *   false – user found in legacy DB but the stub-import threw an exception
+     *
+     * Results are cached per command run to avoid redundant DB queries.
+     */
+    private function ensureLegacyUser(int $legacyId, bool $isDryRun, $logFile): ?bool
+    {
+        if (array_key_exists($legacyId, $this->legacyUserCache)) {
+            return $this->legacyUserCache[$legacyId];
+        }
+
+        if (DB::table('users')->where('id', $legacyId)->exists()) {
+            return $this->legacyUserCache[$legacyId] = true;
+        }
+
+        $legacyUser = DB::connection('legacy')
+            ->table('users')
+            ->where('user_id', $legacyId)
+            ->first();
+
+        if (! $legacyUser) {
+            $this->logLine($logFile, "IMPORT FAIL: user_id={$legacyId} not found in legacy DB");
+            return $this->legacyUserCache[$legacyId] = null;
+        }
+
+        if ($isDryRun) {
+            $this->logLine($logFile, "DRY-RUN IMPORT: would create user_id={$legacyId} uname={$legacyUser->uname}");
+            return $this->legacyUserCache[$legacyId] = true;
+        }
+
+        try {
+            $this->importLegacyUserStub($legacyUser);
+            $this->logLine($logFile, "IMPORTED user_id={$legacyId} uname={$legacyUser->uname}");
+            return $this->legacyUserCache[$legacyId] = true;
+        } catch (\Throwable $e) {
+            $this->logLine($logFile, "IMPORT ERROR user_id={$legacyId}: " . $e->getMessage());
+            return $this->legacyUserCache[$legacyId] = false;
+        }
+    }
+
+    private function importLegacyUserStub(object $row): void
+    {
+        $legacyId = (int) $row->user_id;
+        $now      = now();
+
+        $username = UsernamePolicy::sanitizeLegacy((string) ($row->uname ?: ('user' . $legacyId)));
+        if (! $username) {
+            $username = 'user' . $legacyId;
+        }
+
+        if (DB::table('users')->whereRaw('LOWER(username) = ?', [strtolower($username)])->exists()) {
+            $username = $username . $legacyId;
+        }
+
+        $email = ($row->email ? strtolower(trim($row->email)) : null)
+            ?: ('user' . $legacyId . '@users.skinbase.org');
+
+        DB::transaction(function () use ($legacyId, $username, $email, $row, $now) {
+            DB::table('users')->insertOrIgnore([
+                'id'                   => $legacyId,
+                'username'             => $username,
+                'name'                 => $row->real_name ?: $username,
+                'email'                => $email,
+                'password'             => Hash::make(Str::random(32)),
+                'is_active'            => (int) ($row->active ?? 1) === 1,
+                'needs_password_reset' => true,
+                'role'                 => 'user',
+                'created_at'           => $row->joinDate ?? $now,
+                'updated_at'           => $now,
+            ]);
+
+            DB::table('user_profiles')->updateOrInsert(
+                ['user_id' => $legacyId],
+                [
+                    'country'      => $row->country ?? null,
+                    'country_code' => $row->country_code ? substr((string) $row->country_code, 0, 2) : null,
+                    'website'      => $row->web ?? null,
+                    'updated_at'   => $now,
+                ]
+            );
+
+            DB::table('user_statistics')->updateOrInsert(
+                ['user_id' => $legacyId],
+                ['updated_at' => $now, 'created_at' => $now]
+            );
+        });
+    }
+
+    // -------------------------------------------------------------------------
+
+    private function backfillCounters(): void
+    {
+        DB::statement('
+            UPDATE user_statistics us
+            JOIN (
+                SELECT user_id, COUNT(*) AS cnt
+                FROM user_followers
+                GROUP BY user_id
+            ) AS f ON f.user_id = us.user_id
+            SET us.followers_count = f.cnt, us.updated_at = NOW()
+        ');
+
+        DB::statement('
+            UPDATE user_statistics us
+            JOIN (
+                SELECT follower_id, COUNT(*) AS cnt
+                FROM user_followers
+                GROUP BY follower_id
+            ) AS f ON f.follower_id = us.user_id
+            SET us.following_count = f.cnt, us.updated_at = NOW()
+        ');
+
+        $this->info('Counters backfilled.');
+    }
+
+    private function logLine($handle, string $message): void
+    {
+        if (is_resource($handle)) {
+            fwrite($handle, '[' . now()->toISOString() . '] ' . $message . PHP_EOL);
+        }
+    }
+}

app/Console/Commands/MigrateMessagesCommand.php

@@ -0,0 +1,246 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\Conversation;
+use App\Models\ConversationParticipant;
+use App\Models\Message;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Throwable;
+
+/**
+ * Migrates legacy `chat` / `messages` tables into the modern conversation-based system.
+ *
+ * Strategy:
+ *   1. Load all legacy rows from the `chat` table via the 'legacy' DB connection.
+ *   2. Group by (sender_user_id, receiver_user_id) pair (canonical: min first).
+ *   3. For each pair, find or create a `direct` conversation.
+ *   4. Insert each message in chronological order.
+ *   5. Set last_read_at based on the legacy read_date column (if present).
+ *   6. Skip deleted / inactive rows.
+ *   7. Convert smileys to emoji placeholders.
+ *
+ * Usage:
+ *   php artisan skinbase:migrate-messages
+ *   php artisan skinbase:migrate-messages --dry-run
+ *   php artisan skinbase:migrate-messages --chunk=1000
+ */
+class MigrateMessagesCommand extends Command
+{
+    protected $signature = 'skinbase:migrate-messages
+                            {--dry-run    : Preview only — no writes to DB}
+                            {--chunk=500  : Rows to process per batch}';
+
+    protected $description = 'Migrate legacy chat/messages into the modern conversation system';
+
+    /** Columns we attempt to read; gracefully degrade if missing. */
+    private array $skipped = [];
+
+    public function handle(): int
+    {
+        $dryRun = (bool) $this->option('dry-run');
+        $chunk  = max(1, (int) $this->option('chunk'));
+
+        if ($dryRun) {
+            $this->warn('[DRY-RUN] No data will be written.');
+        }
+
+        // ── Check legacy connection ───────────────────────────────────────────
+        try {
+            DB::connection('legacy')->getPdo();
+        } catch (Throwable $e) {
+            $this->error('Cannot connect to legacy database: ' . $e->getMessage());
+            return self::FAILURE;
+        }
+
+        $legacySchema = DB::connection('legacy')->getSchemaBuilder();
+
+        if (! $legacySchema->hasTable('chat')) {
+            $this->error('Legacy table `chat` not found on the legacy connection.');
+            return self::FAILURE;
+        }
+
+        $columns = $legacySchema->getColumnListing('chat');
+        $this->info('Legacy chat columns: ' . implode(', ', $columns));
+
+        // Map expected legacy columns (adapt if your legacy schema differs)
+        $hasReadDate   = in_array('read_date', $columns, true);
+        $hasSoftDelete = in_array('deleted', $columns, true);
+
+        // ── Count total rows ──────────────────────────────────────────────────
+        $query = DB::connection('legacy')->table('chat');
+
+        if ($hasSoftDelete) {
+            $query->where('deleted', 0);
+        }
+
+        $total = $query->count();
+        $this->info("Total legacy rows to process: {$total}");
+
+        if ($total === 0) {
+            $this->info('Nothing to migrate.');
+            return self::SUCCESS;
+        }
+
+        $bar      = $this->output->createProgressBar($total);
+        $inserted = 0;
+        $skipped  = 0;
+        $offset   = 0;
+
+        // ── Chunk processing ──────────────────────────────────────────────────
+        while (true) {
+            $rows = DB::connection('legacy')
+                ->table('chat')
+                ->when($hasSoftDelete, fn ($q) => $q->where('deleted', 0))
+                ->orderBy('id')
+                ->offset($offset)
+                ->limit($chunk)
+                ->get();
+
+            if ($rows->isEmpty()) {
+                break;
+            }
+
+            foreach ($rows as $row) {
+                $senderId   = (int) ($row->sender_user_id  ?? $row->from_user_id ?? $row->user_id       ?? 0);
+                $receiverId = (int) ($row->receiver_user_id ?? $row->to_user_id  ?? $row->recipient_id  ?? 0);
+                $body       = trim((string) ($row->message ?? $row->body ?? $row->content ?? ''));
+                $createdAt  = $row->created_at ?? $row->date ?? $row->timestamp ?? now();
+                $readDate   = $hasReadDate ? $row->read_date : null;
+
+                if ($senderId === 0 || $receiverId === 0 || $body === '') {
+                    $skipped++;
+                    $this->skipped[] = ['id' => $row->id ?? '?', 'reason' => 'missing sender/receiver/body'];
+                    $bar->advance();
+                    continue;
+                }
+
+                // Skip self-messages
+                if ($senderId === $receiverId) {
+                    $skipped++;
+                    $this->skipped[] = ['id' => $row->id ?? '?', 'reason' => 'self-message'];
+                    $bar->advance();
+                    continue;
+                }
+
+                // Sanitize: strip HTML, convert smileys to emoji
+                $body = $this->sanitize($body);
+
+                if ($dryRun) {
+                    $inserted++;
+                    $bar->advance();
+                    continue;
+                }
+
+                try {
+                    DB::transaction(function () use ($senderId, $receiverId, $body, $createdAt, $readDate, &$inserted) {
+                        // Find or create direct conversation
+                        $conv = Conversation::findDirect($senderId, $receiverId);
+
+                        if (! $conv) {
+                            $conv = Conversation::create([
+                                'type'            => 'direct',
+                                'created_by'      => $senderId,
+                                'last_message_at' => $createdAt,
+                            ]);
+
+                            ConversationParticipant::insert([
+                                [
+                                    'conversation_id' => $conv->id,
+                                    'user_id'         => $senderId,
+                                    'role'            => 'admin',
+                                    'joined_at'       => $createdAt,
+                                    'last_read_at'    => $readDate,
+                                ],
+                                [
+                                    'conversation_id' => $conv->id,
+                                    'user_id'         => $receiverId,
+                                    'role'            => 'member',
+                                    'joined_at'       => $createdAt,
+                                    'last_read_at'    => $readDate,
+                                ],
+                            ]);
+                        } else {
+                            // Update last_read_at on existing participants when available
+                            if ($readDate) {
+                                ConversationParticipant::where('conversation_id', $conv->id)
+                                    ->where('user_id', $receiverId)
+                                    ->whereNull('last_read_at')
+                                    ->update(['last_read_at' => $readDate]);
+                            }
+                        }
+
+                        Message::create([
+                            'conversation_id' => $conv->id,
+                            'sender_id'       => $senderId,
+                            'body'            => $body,
+                            'created_at'      => $createdAt,
+                            'updated_at'      => $createdAt,
+                        ]);
+
+                        // Keep last_message_at up to date
+                        if ($conv->last_message_at < $createdAt) {
+                            $conv->update(['last_message_at' => $createdAt]);
+                        }
+
+                        $inserted++;
+                    });
+                } catch (Throwable $e) {
+                    $skipped++;
+                    $this->skipped[] = ['id' => $row->id ?? '?', 'reason' => $e->getMessage()];
+                    Log::warning('MigrateMessages: skipped row', [
+                        'id'     => $row->id ?? '?',
+                        'reason' => $e->getMessage(),
+                    ]);
+                }
+
+                $bar->advance();
+            }
+
+            $offset += $chunk;
+        }
+
+        $bar->finish();
+        $this->newLine();
+
+        $this->info("Done. Inserted: {$inserted} | Skipped: {$skipped}");
+
+        if ($skipped > 0 && $this->option('verbose')) {
+            $this->table(['ID', 'Reason'], $this->skipped);
+        }
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * Strip HTML tags and convert common legacy smileys to emoji.
+     */
+    private function sanitize(string $body): string
+    {
+        // Strip raw HTML
+        $body = strip_tags($body);
+
+        // Decode HTML entities
+        $body = html_entity_decode($body, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+
+        // Common smiley → emoji mapping
+        $smileys = [
+            ':)'  => '🙂', ':-)' => '🙂',
+            ':('  => '🙁', ':-(' => '🙁',
+            ':D'  => '😀', ':-D' => '😀',
+            ':P'  => '😛', ':-P' => '😛',
+            ';)'  => '😉', ';-)' => '😉',
+            ':o'  => '😮', ':O'  => '😮',
+            ':|'  => '😐', ':-|' => '😐',
+            ':/'  => '😕', ':-/' => '😕',
+            '<3'  => '❤️',
+            'xD'  => '😂', 'XD'  => '😂',
+        ];
+
+        return str_replace(array_keys($smileys), array_values($smileys), $body);
+    }
+}

app/Console/Commands/MigrateSmileys.php

@@ -0,0 +1,143 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\LegacySmileyMapper;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * php artisan skinbase:migrate-smileys
+ *
+ * Scans artworks.description, artwork_comments.content, and forum_posts.content,
+ * replaces legacy smiley codes (:beer, :lol, etc.) with Unicode emoji.
+ *
+ * Options:
+ *   --dry-run        Show what would change without writing to DB
+ *   --chunk=200      Rows processed per batch (default 200)
+ *   --table=artworks Limit scan to one table
+ */
+class MigrateSmileys extends Command
+{
+    protected $signature = 'skinbase:migrate-smileys
+                            {--dry-run : Preview changes without writing to the database}
+                            {--chunk=200 : Number of rows to process per batch}
+                            {--table= : Limit scan to a single table (artworks|artwork_comments|forum_posts)}';
+
+    protected $description = 'Convert legacy :smiley: codes to Unicode emoji in content fields.';
+
+    /** Tables and their content columns to scan. */
+    private const TARGETS = [
+        'artworks'         => 'description',
+        'artwork_comments' => 'content',
+        'forum_posts'      => 'content',
+    ];
+
+    public function handle(): int
+    {
+        $dryRun  = (bool) $this->option('dry-run');
+        $chunk   = max(1, (int) $this->option('chunk'));
+        $tableOpt = $this->option('table');
+
+        $targets = self::TARGETS;
+        if ($tableOpt) {
+            if (! isset($targets[$tableOpt])) {
+                $this->error("Unknown table: {$tableOpt}. Allowed: " . implode(', ', array_keys($targets)));
+                return self::FAILURE;
+            }
+            $targets = [$tableOpt => $targets[$tableOpt]];
+        }
+
+        if ($dryRun) {
+            $this->warn('DRY-RUN mode — no changes will be written.');
+        }
+
+        $totalChanged = 0;
+        $totalRows    = 0;
+
+        foreach ($targets as $table => $column) {
+            $this->line("Scanning <info>{$table}.{$column}</info>…");
+
+            [$changed, $rows] = $this->processTable($table, $column, $chunk, $dryRun);
+
+            $totalChanged += $changed;
+            $totalRows    += $rows;
+
+            $this->line("  → {$rows} rows scanned, {$changed} updated.");
+        }
+
+        $this->newLine();
+        $this->info("Summary: {$totalRows} rows scanned, {$totalChanged} rows " . ($dryRun ? 'would be ' : '') . 'updated.');
+
+        return self::SUCCESS;
+    }
+
+    private function processTable(
+        string $table,
+        string $column,
+        int    $chunk,
+        bool   $dryRun
+    ): array {
+        $totalChanged = 0;
+        $totalRows    = 0;
+
+        DB::table($table)
+            ->whereNotNull($column)
+            ->orderBy('id')
+            ->chunk($chunk, function ($rows) use ($table, $column, $dryRun, &$totalChanged, &$totalRows) {
+                foreach ($rows as $row) {
+                    $original  = $row->$column ?? '';
+                    $converted = LegacySmileyMapper::convert($original);
+
+                    // Collapse emoji flood runs BEFORE size/DB checks so that
+                    // rows like ":beer :beer :beer …" (×500) don't exceed MEDIUMTEXT.
+                    $collapsed = LegacySmileyMapper::collapseFlood($converted);
+                    if ($collapsed !== $converted) {
+                        $beforeBytes = mb_strlen($converted, '8bit');
+                        $afterBytes  = mb_strlen($collapsed,  '8bit');
+                        $floodMsg    = "[{$table}#{$row->id}] Emoji flood collapsed "
+                                     . "({$beforeBytes} bytes \u{2192} {$afterBytes} bytes).";
+                        $this->warn("  {$floodMsg}");
+                        Log::warning($floodMsg);
+                        $converted = $collapsed;
+                    }
+
+                    $totalRows++;
+
+                    if ($converted === $original) {
+                        continue;
+                    }
+
+                    $totalChanged++;
+
+                    $codes = LegacySmileyMapper::detect($original);
+                    $msg   = "[{$table}#{$row->id}] Converting: " . implode(', ', $codes);
+                    $this->line("  {$msg}");
+                    Log::info($msg);
+
+                    if (! $dryRun) {
+                        // Guard: MEDIUMTEXT max is 16,777,215 bytes.
+                        if (mb_strlen($converted, '8bit') > 16_777_215) {
+                            $warn = "[{$table}#{$row->id}] SKIP — converted content exceeds MEDIUMTEXT limit (" . mb_strlen($converted, '8bit') . " bytes). Row left unchanged.";
+                            $this->warn("  {$warn}");
+                            Log::warning($warn);
+                            continue;
+                        }
+
+                        try {
+                            DB::table($table)
+                                ->where('id', $row->id)
+                                ->update([$column => $converted]);
+                        } catch (\Throwable $e) {
+                            $err = "[{$table}#{$row->id}] DB error: {$e->getMessage()}";
+                            $this->warn("  {$err}");
+                            Log::error($err);
+                        }
+                    }
+                }
+            });
+
+        return [$totalChanged, $totalRows];
+    }
+}

app/Console/Commands/MigrateWallzStatsCommand.php

@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Copy views and downloads from the legacy `wallz` table into `artwork_stats`.
+ *
+ * Uses wallz.id as artwork_id.
+ * Rows that already exist are updated; missing rows are inserted with zeros
+ * for all other counters.
+ *
+ * Usage:
+ *   php artisan skinbase:migrate-wallz-stats
+ *   php artisan skinbase:migrate-wallz-stats --chunk=500 --dry-run
+ */
+class MigrateWallzStatsCommand extends Command
+{
+    protected $signature = 'skinbase:migrate-wallz-stats
+                            {--chunk=1000 : Number of wallz rows to process per batch}
+                            {--dry-run : Preview counts without writing to the database}';
+
+    protected $description = 'Import views and downloads from legacy wallz table into artwork_stats';
+
+    public function handle(): int
+    {
+        $chunkSize = (int) $this->option('chunk');
+        $dryRun    = (bool) $this->option('dry-run');
+
+        if ($dryRun) {
+            $this->warn('[DRY RUN] No data will be written.');
+        }
+
+        $total     = (int) DB::connection('legacy')->table('wallz')->count();
+        $processed = 0;
+        $inserted  = 0;
+        $updated   = 0;
+
+        $this->info("Found {$total} rows in legacy wallz table. Chunk size: {$chunkSize}.");
+
+        $bar = $this->output->createProgressBar($total);
+        $bar->setFormat(' %current%/%max% [%bar%] %percent:3s%% — ins: %message%');
+        $bar->setMessage('0 ins / 0 upd');
+        $bar->start();
+
+        DB::connection('legacy')
+            ->table('wallz')
+            ->select('id', 'views', 'dls', 'rating', 'rating_num')
+            ->orderBy('id')
+            ->chunk($chunkSize, function ($rows) use ($dryRun, &$processed, &$inserted, &$updated, $bar) {
+                $artworkIds = $rows->pluck('id')->all();
+
+                // Find which artwork_ids already have a stats row.
+                $existing = DB::table('artwork_stats')
+                    ->whereIn('artwork_id', $artworkIds)
+                    ->pluck('artwork_id')
+                    ->flip(); // flip → [artwork_id => index] for O(1) lookup
+
+                $toInsert = [];
+                $now      = now()->toDateTimeString();
+
+                foreach ($rows as $row) {
+                    $views      = max(0, (int) $row->views);
+                    $dls        = max(0, (int) $row->dls);
+                    $ratingAvg  = max(0, (float) $row->rating);
+                    $ratingCount = max(0, (int) $row->rating_num);
+
+                    if ($existing->has($row->id)) {
+                        // Update existing row.
+                        if (! $dryRun) {
+                            DB::table('artwork_stats')
+                                ->where('artwork_id', $row->id)
+                                ->update([
+                                    'views'        => $views,
+                                    'downloads'    => $dls,
+                                    'rating_avg'   => $ratingAvg,
+                                    'rating_count' => $ratingCount,
+                                ]);
+                        }
+                        $updated++;
+                    } else {
+                        // Batch-collect for insert.
+                        $toInsert[] = [
+                            'artwork_id'    => $row->id,
+                            'views'         => $views,
+                            'views_24h'     => 0,
+                            'views_7d'      => 0,
+                            'downloads'     => $dls,
+                            'downloads_24h' => 0,
+                            'downloads_7d'  => 0,
+                            'favorites'     => 0,
+                            'rating_avg'    => $ratingAvg,
+                            'rating_count'  => $ratingCount,
+                        ];
+                        $inserted++;
+                    }
+                }
+
+                if (! $dryRun && ! empty($toInsert)) {
+                    DB::table('artwork_stats')->insertOrIgnore($toInsert);
+                }
+
+                $processed += count($rows);
+                $bar->setMessage("{$inserted} ins / {$updated} upd");
+                $bar->advance(count($rows));
+            });
+
+        $bar->finish();
+        $this->newLine();
+
+        if ($dryRun) {
+            $this->warn("DRY RUN complete — would insert {$inserted}, update {$updated} ({$processed} rows scanned).");
+        } else {
+            $this->info("Done — inserted {$inserted}, updated {$updated} ({$processed} rows processed).");
+        }
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/PruneViewEventsCommand.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Delete artwork_view_events rows older than N days.
+ *
+ * The view event log grows ~proportionally to site traffic. Rows beyond the
+ * retention window are no longer useful for trending (which looks back ≤7
+ * days) or for computing "recently viewed" lists in the UI.
+ *
+ * Default retention is 90 days — long enough for analytics queries and user
+ * history pages, short enough to keep the table from growing unbounded.
+ *
+ * Usage:
+ *   php artisan skinbase:prune-view-events
+ *   php artisan skinbase:prune-view-events --days=30
+ */
+class PruneViewEventsCommand extends Command
+{
+    protected $signature   = 'skinbase:prune-view-events {--days=90 : Delete events older than this many days}';
+    protected $description = 'Delete artwork_view_events rows older than N days';
+
+    public function handle(): int
+    {
+        $days   = (int) $this->option('days');
+        $cutoff = now()->subDays($days);
+
+        $deleted = DB::table('artwork_view_events')
+            ->where('viewed_at', '<', $cutoff)
+            ->delete();
+
+        $this->info("Pruned {$deleted} view event(s) older than {$days} days (cutoff: {$cutoff}).");
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/RebuildArtworkSearchIndex.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\ArtworkSearchIndexer;
+use Illuminate\Console\Command;
+
+class RebuildArtworkSearchIndex extends Command
+{
+    protected $signature   = 'artworks:search-rebuild {--chunk=500 : Number of artworks per chunk}';
+    protected $description = 'Re-queue all artworks for Meilisearch indexing (non-blocking, chunk-based).';
+
+    public function __construct(private readonly ArtworkSearchIndexer $indexer)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $chunk = (int) $this->option('chunk');
+
+        $this->info("Dispatching index jobs in chunks of {$chunk}…");
+        $this->indexer->rebuildAll($chunk);
+        $this->info('All jobs dispatched. Workers will process them asynchronously.');
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/RecalculateTrendingCommand.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\TrendingService;
+use Illuminate\Console\Command;
+
+/**
+ * php artisan skinbase:recalculate-trending [--period=24h|7d] [--chunk=1000] [--skip-index]
+ */
+class RecalculateTrendingCommand extends Command
+{
+    protected $signature = 'skinbase:recalculate-trending
+                            {--period=7d   : Period to recalculate (24h or 7d). Use "all" to run both.}
+                            {--chunk=1000  : DB chunk size}
+                            {--skip-index  : Skip dispatching Meilisearch re-index jobs}';
+
+    protected $description = 'Recalculate trending scores for artworks and sync to Meilisearch';
+
+    public function __construct(private readonly TrendingService $trending)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $period    = (string)  $this->option('period');
+        $chunkSize = (int)     $this->option('chunk');
+        $skipIndex = (bool)    $this->option('skip-index');
+
+        $periods = $period === 'all' ? ['24h', '7d'] : [$period];
+
+        foreach ($periods as $p) {
+            if (! in_array($p, ['24h', '7d'], true)) {
+                $this->error("Invalid period '{$p}'. Use 24h, 7d, or all.");
+                return self::FAILURE;
+            }
+
+            $this->info("Recalculating trending ({$p}) …");
+            $start   = microtime(true);
+            $updated = $this->trending->recalculate($p, $chunkSize);
+            $elapsed = round(microtime(true) - $start, 2);
+
+            $this->info("  ✓ {$updated} artworks updated in {$elapsed}s");
+
+            if (! $skipIndex) {
+                $this->info("  Dispatching Meilisearch index jobs …");
+                $this->trending->syncToSearchIndex($p);
+                $this->info("  ✓ Index jobs dispatched");
+            }
+        }
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/RecomputeUserStatsCommand.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Jobs\RecomputeUserStatsJob;
+use App\Services\UserStatsService;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Recompute user_statistics counters from authoritative source tables.
+ *
+ * Usage:
+ *   # Recompute a single user (live)
+ *   php artisan skinbase:recompute-user-stats 42
+ *
+ *   # Dry-run for a single user
+ *   php artisan skinbase:recompute-user-stats 42 --dry-run
+ *
+ *   # Recompute all users in chunks of 500
+ *   php artisan skinbase:recompute-user-stats --all --chunk=500
+ *
+ *   # Recompute all users via queue (one job per chunk)
+ *   php artisan skinbase:recompute-user-stats --all --queue
+ */
+class RecomputeUserStatsCommand extends Command
+{
+    protected $signature = 'skinbase:recompute-user-stats
+                            {user_id? : The ID of a single user to recompute}
+                            {--all    : Recompute stats for ALL non-deleted users}
+                            {--chunk=1000 : Chunk size when --all is used}
+                            {--dry-run    : Show what would be written without saving}
+                            {--queue      : Dispatch recompute jobs to the queue (--all mode only)}';
+
+    protected $description = 'Rebuild user_statistics counters from authoritative source tables';
+
+    public function handle(UserStatsService $statsService): int
+    {
+        $dryRun  = (bool) $this->option('dry-run');
+        $all     = (bool) $this->option('all');
+        $userId  = $this->argument('user_id');
+        $chunk   = max(1, (int) $this->option('chunk'));
+        $queue   = (bool) $this->option('queue');
+
+        if ($userId !== null && $all) {
+            $this->error('Provide either a user_id OR --all, not both.');
+            return self::FAILURE;
+        }
+
+        if ($userId !== null) {
+            return $this->recomputeSingle((int) $userId, $statsService, $dryRun);
+        }
+
+        if ($all) {
+            return $this->recomputeAll($statsService, $chunk, $dryRun, $queue);
+        }
+
+        $this->error('Provide a user_id or use --all.');
+        return self::FAILURE;
+    }
+
+    // ─── Single user ─────────────────────────────────────────────────────────
+
+    private function recomputeSingle(int $userId, UserStatsService $statsService, bool $dryRun): int
+    {
+        $exists = DB::table('users')->where('id', $userId)->exists();
+        if (! $exists) {
+            $this->error("User {$userId} not found.");
+            return self::FAILURE;
+        }
+
+        $label = $dryRun ? '[DRY-RUN]' : '[LIVE]';
+        $this->line("{$label} Recomputing stats for user #{$userId}…");
+
+        $computed = $statsService->recomputeUser($userId, $dryRun);
+
+        $rows = [];
+        foreach ($computed as $col => $val) {
+            $rows[] = [$col, $val ?? '(null)'];
+        }
+
+        $this->table(['Column', 'Value'], $rows);
+
+        if ($dryRun) {
+            $this->warn('Dry-run: no changes written.');
+        } else {
+            $this->info("Stats saved for user #{$userId}.");
+        }
+
+        return self::SUCCESS;
+    }
+
+    // ─── All users ────────────────────────────────────────────────────────────
+
+    private function recomputeAll(
+        UserStatsService $statsService,
+        int $chunk,
+        bool $dryRun,
+        bool $useQueue
+    ): int {
+        $total = DB::table('users')->whereNull('deleted_at')->count();
+        $label = $dryRun ? '[DRY-RUN]' : ($useQueue ? '[QUEUE]' : '[LIVE]');
+
+        $this->info("{$label} Recomputing stats for {$total} users (chunk={$chunk})…");
+
+        if ($useQueue && ! $dryRun) {
+            $dispatched = 0;
+            DB::table('users')
+                ->whereNull('deleted_at')
+                ->orderBy('id')
+                ->chunkById($chunk, function ($users) use (&$dispatched) {
+                    $ids = $users->pluck('id')->all();
+                    RecomputeUserStatsJob::dispatch($ids);
+                    $dispatched += count($ids);
+                    $this->line("  Queued chunk of " . count($ids) . " users (total dispatched: {$dispatched})");
+                });
+
+            $this->info("Done – {$dispatched} users queued for recompute.");
+            return self::SUCCESS;
+        }
+
+        $processed = 0;
+        $bar = $this->output->createProgressBar($total);
+        $bar->start();
+
+        DB::table('users')
+            ->whereNull('deleted_at')
+            ->orderBy('id')
+            ->chunkById($chunk, function ($users) use ($statsService, $dryRun, &$processed, $bar) {
+                foreach ($users as $user) {
+                    $statsService->recomputeUser((int) $user->id, $dryRun);
+                    $processed++;
+                    $bar->advance();
+                }
+            });
+
+        $bar->finish();
+        $this->newLine();
+
+        $suffix = $dryRun ? ' (no changes written – dry-run)' : '';
+        $this->info("Done – {$processed} users recomputed{$suffix}.");
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/ResetWindowedStatsCommand.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * php artisan skinbase:reset-windowed-stats --period=24h|7d
+ *
+ * Resets / recomputes the sliding-window stats columns in artwork_stats:
+ *
+ *   views_24h / views_7d
+ *     — Zeroed on each reset because we have no per-view event log.
+ *       Artworks re-accumulate from the next view event onward.
+ *       (Low-traffic reset window: 03:30 means minimal trending disruption.)
+ *
+ *   downloads_24h / downloads_7d
+ *     — Recomputed accurately from the artwork_downloads event log.
+ *       A single bulk UPDATE with a correlated COUNT() is safe here because
+ *       it runs once nightly/weekly, not in the hot path.
+ *
+ * Scheduled in routes/console.php:
+ *   --period=24h  daily at 03:30
+ *   --period=7d   weekly (Monday) at 03:30
+ */
+class ResetWindowedStatsCommand extends Command
+{
+    protected $signature = 'skinbase:reset-windowed-stats
+                            {--period=24h : Window to reset: 24h or 7d}';
+
+    protected $description = 'Reset windowed view/download counters in artwork_stats';
+
+    public function handle(): int
+    {
+        $period = (string) $this->option('period');
+
+        if (! in_array($period, ['24h', '7d'], true)) {
+            $this->error("Invalid period '{$period}'. Use 24h or 7d.");
+            return self::FAILURE;
+        }
+
+        [$viewsCol, $downloadsCol, $cutoff] = match ($period) {
+            '24h'   => ['views_24h', 'downloads_24h', now()->subDay()],
+            default => ['views_7d',  'downloads_7d',  now()->subDays(7)],
+        };
+
+        $start = microtime(true);
+
+        // ── 1. Zero the views window column ──────────────────────────────────
+        //    We have no per-view event log, so we reset the accumulator.
+        $viewsReset = DB::table('artwork_stats')->update([$viewsCol => 0]);
+
+        // ── 2. Recompute downloads window from the event log ─────────────────
+        //    artwork_downloads has created_at, so each row's window is accurate.
+        //    Chunked PHP loop avoids MySQL-only functions (GREATEST, INTERVAL)
+        //    so this command works in both MySQL (production) and SQLite (tests).
+        $downloadsRecomputed = 0;
+
+        DB::table('artwork_stats')
+            ->orderBy('artwork_id')
+            ->chunk(1000, function ($rows) use ($downloadsCol, $cutoff, &$downloadsRecomputed): void {
+                foreach ($rows as $row) {
+                    $count = DB::table('artwork_downloads')
+                        ->where('artwork_id', $row->artwork_id)
+                        ->where('created_at', '>=', $cutoff)
+                        ->count();
+
+                    DB::table('artwork_stats')
+                        ->where('artwork_id', $row->artwork_id)
+                        ->update([$downloadsCol => max(0, $count)]);
+
+                    $downloadsRecomputed++;
+                }
+            });
+
+        $elapsed = round(microtime(true) - $start, 2);
+
+        $this->info("Period: {$period}");
+        $this->info("  {$viewsCol}: zeroed {$viewsReset} rows");
+        $this->info("  {$downloadsCol}: recomputed {$downloadsRecomputed} rows ({$elapsed}s)");
+
+        Log::info('ResetWindowedStats complete', [
+            'period'               => $period,
+            'views_col'            => $viewsCol,
+            'views_rows_reset'     => $viewsReset,
+            'downloads_col'        => $downloadsCol,
+            'downloads_recomputed' => $downloadsRecomputed,
+            'elapsed_s'            => $elapsed,
+        ]);
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/SanitizeContent.php

@@ -0,0 +1,188 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\ContentSanitizer;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * php artisan skinbase:sanitize-content
+ *
+ * Scans legacy content for unsafe HTML, converts it to Markdown-safe text,
+ * and populates the raw_content / rendered_content columns on artwork_comments.
+ *
+ * Options:
+ *   --dry-run       Preview changes without writing
+ *   --chunk=200     Rows per batch
+ *   --table=        Limit to one target
+ *   --artwork-id=   Limit to a single artwork (filters artwork_comments by artwork_id, artworks by id)
+ */
+class SanitizeContent extends Command
+{
+    protected $signature = 'skinbase:sanitize-content
+                            {--dry-run : Preview changes without writing to the database}
+                            {--chunk=200 : Number of rows per batch}
+                            {--table= : Limit scan to a single target (artwork_comments|artworks|forum_posts)}
+                            {--artwork-id= : Limit scan to a single artwork ID (skips forum_posts)}';
+
+    protected $description = 'Strip unsafe HTML from legacy content and populate sanitized columns.';
+
+    /**
+     * table => [read_col, write_raw_col, write_rendered_col|null]
+     *
+     * For artwork_comments we write two columns; for the others we only sanitize in-place.
+     */
+    private const TARGETS = [
+        'artwork_comments' => [
+            'read'            => 'content',
+            'write_raw'       => 'raw_content',
+            'write_rendered'  => 'rendered_content',
+        ],
+        'artworks' => [
+            'read'            => 'description',
+            'write_raw'       => 'description',
+            'write_rendered'  => null,
+        ],
+        'forum_posts' => [
+            'read'            => 'content',
+            'write_raw'       => 'content',
+            'write_rendered'  => null,
+        ],
+    ];
+
+    public function handle(): int
+    {
+        $dryRun    = (bool) $this->option('dry-run');
+        $chunk     = max(1, (int) $this->option('chunk'));
+        $tableOpt  = $this->option('table');
+        $artworkId = $this->option('artwork-id');
+
+        if ($artworkId !== null) {
+            if (! ctype_digit((string) $artworkId) || (int) $artworkId < 1) {
+                $this->error("--artwork-id must be a positive integer. Got: {$artworkId}");
+                return self::FAILURE;
+            }
+            $artworkId = (int) $artworkId;
+        }
+
+        $targets = self::TARGETS;
+        if ($tableOpt) {
+            if (! isset($targets[$tableOpt])) {
+                $this->error("Unknown table: {$tableOpt}. Allowed: " . implode(', ', array_keys($targets)));
+                return self::FAILURE;
+            }
+            $targets = [$tableOpt => $targets[$tableOpt]];
+        }
+
+        // --artwork-id removes forum_posts (no artwork FK) and informs the user.
+        if ($artworkId !== null) {
+            unset($targets['forum_posts']);
+            $this->line("Filtering to artwork <info>#{$artworkId}</info> (forum_posts skipped).");
+        }
+
+        if ($dryRun) {
+            $this->warn('DRY-RUN mode — no changes will be written.');
+        }
+
+        $totalModified = 0;
+        $totalRows     = 0;
+
+        foreach ($targets as $table => $def) {
+            $this->line("Processing <info>{$table}</info>…");
+
+            [$modified, $rows] = $this->processTable($table, $def, $chunk, $dryRun, $artworkId);
+            $totalModified += $modified;
+            $totalRows     += $rows;
+
+            $this->line("  → {$rows} rows scanned, {$modified} modified.");
+        }
+
+        $this->newLine();
+        $this->info("Summary: {$totalRows} rows, {$totalModified} " . ($dryRun ? 'would be ' : '') . 'modified.');
+
+        return self::SUCCESS;
+    }
+
+    private function processTable(
+        string   $table,
+        array    $def,
+        int      $chunk,
+        bool     $dryRun,
+        ?int     $artworkId = null
+    ): array {
+        $totalModified = 0;
+        $totalRows     = 0;
+
+        $readCol          = $def['read'];
+        $writeRawCol      = $def['write_raw'];
+        $writeRenderedCol = $def['write_rendered'];
+
+        DB::table($table)
+            ->whereNotNull($readCol)
+            ->when($artworkId !== null, function ($q) use ($table, $artworkId) {
+                // artwork_comments has artwork_id; artworks is filtered by its own PK.
+                $filterCol = $table === 'artwork_comments' ? 'artwork_id' : 'id';
+                $q->where($filterCol, $artworkId);
+            })
+            ->orderBy('id')
+            ->chunk($chunk, function ($rows) use (
+                $table, $readCol, $writeRawCol, $writeRenderedCol,
+                $dryRun, &$totalModified, &$totalRows
+            ) {
+                foreach ($rows as $row) {
+                    $original = $row->$readCol ?? '';
+                    $stripped = ContentSanitizer::stripToPlain($original);
+
+                    $totalRows++;
+
+                    // Detect if content had HTML that we need to clean
+                    $hadHtml  = $original !== $stripped && preg_match('/<[a-z][^>]*>/i', $original);
+
+                    if ($writeRawCol === $readCol && ! $hadHtml) {
+                        // Same column, no HTML, skip
+                        continue;
+                    }
+
+                    $rendered  = ContentSanitizer::render($stripped);
+                    $totalModified++;
+
+                    if ($hadHtml) {
+                        $this->line("  [{$table}#{$row->id}] Stripped HTML from content.");
+                        Log::info("skinbase:sanitize-content stripped HTML from {$table}#{$row->id}");
+                    }
+
+                    if ($dryRun) {
+                        continue;
+                    }
+
+                    $update = [$writeRawCol => $stripped];
+
+                    if ($writeRenderedCol) {
+                        $update[$writeRenderedCol] = $rendered;
+                    }
+
+                    DB::table($table)->where('id', $row->id)->update($update);
+                }
+
+                // Also populate rendered_content for rows that have raw_content but no rendered_content
+                if ($writeRenderedCol && ! $dryRun) {
+                    DB::table($table)
+                        ->whereNotNull($writeRawCol)
+                        ->whereNull($writeRenderedCol)
+                        ->orderBy('id')
+                        ->chunk(200, function ($missing) use ($table, $writeRawCol, $writeRenderedCol) {
+                            foreach ($missing as $row) {
+                                $rendered = ContentSanitizer::render($row->$writeRawCol ?? '');
+                                DB::table($table)->where('id', $row->id)->update([
+                                    $writeRenderedCol => $rendered,
+                                ]);
+                            }
+                        });
+                }
+            });
+
+        return [$totalModified, $totalRows];
+    }
+}

app/Console/Kernel.php

@@ -6,6 +6,16 @@ use Illuminate\Foundation\Console\Kernel as ConsoleKernel;
 use App\Console\Commands\ImportLegacyUsers;
 use App\Console\Commands\ImportCategories;
 use App\Console\Commands\MigrateFeaturedWorks;
+use App\Console\Commands\BackfillArtworkEmbeddingsCommand;
+use App\Console\Commands\AggregateSimilarArtworkAnalyticsCommand;
+use App\Console\Commands\AggregateFeedAnalyticsCommand;
+use App\Console\Commands\EvaluateFeedWeightsCommand;
+use App\Console\Commands\AiTagArtworksCommand;
+use App\Console\Commands\CompareFeedAbCommand;
+use App\Console\Commands\RecalculateTrendingCommand;
+use App\Jobs\RankComputeArtworkScoresJob;
+use App\Jobs\RankBuildListsJob;
+use App\Uploads\Commands\CleanupUploadsCommand;
 
 class Kernel extends ConsoleKernel
 {
@@ -16,9 +26,20 @@ class Kernel extends ConsoleKernel
      */
     protected $commands = [
         ImportLegacyUsers::class,
+        \App\Console\Commands\EnforceUsernamePolicy::class,
         ImportCategories::class,
         MigrateFeaturedWorks::class,
+        \App\Console\Commands\AvatarsMigrate::class,
         \App\Console\Commands\ResetAllUserPasswords::class,
+        CleanupUploadsCommand::class,
+        BackfillArtworkEmbeddingsCommand::class,
+        AggregateSimilarArtworkAnalyticsCommand::class,
+        AggregateFeedAnalyticsCommand::class,
+        EvaluateFeedWeightsCommand::class,
+        CompareFeedAbCommand::class,
+        AiTagArtworksCommand::class,
+        \App\Console\Commands\MigrateFollows::class,
+        RecalculateTrendingCommand::class,
     ];
 
     /**
@@ -26,7 +47,18 @@ class Kernel extends ConsoleKernel
      */
     protected function schedule(\Illuminate\Console\Scheduling\Schedule $schedule): void
     {
-        // $schedule->command('inspire')->hourly();
+        $schedule->command('uploads:cleanup')->dailyAt('03:00');
+        $schedule->command('analytics:aggregate-similar-artworks')->dailyAt('03:10');
+        $schedule->command('analytics:aggregate-feed')->dailyAt('03:20');
+        // Recalculate trending scores every 30 minutes (staggered to reduce peak load)
+        $schedule->command('skinbase:recalculate-trending --period=24h')->everyThirtyMinutes();
+        $schedule->command('skinbase:recalculate-trending --period=7d --skip-index')->everyThirtyMinutes()->runInBackground();
+
+        // ── Ranking system (rank_v1) ────────────────────────────────────────
+        // Step 1: compute per-artwork scores every hour at :05
+        $schedule->job(new RankComputeArtworkScoresJob)->hourlyAt(5)->runInBackground();
+        // Step 2: build ranked lists every hour at :15 (after scores are ready)
+        $schedule->job(new RankBuildListsJob)->hourlyAt(15)->runInBackground();
     }
 
     /**

app/DTOs/Artworks/ArtworkDraftResult.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Artworks;
+
+final class ArtworkDraftResult
+{
+    public function __construct(
+        public readonly int $artworkId,
+        public readonly string $status
+    ) {
+    }
+}

app/DTOs/Uploads/UploadChunkResult.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+final class UploadChunkResult
+{
+    public function __construct(
+        public readonly string $sessionId,
+        public readonly string $status,
+        public readonly int $receivedBytes,
+        public readonly int $totalBytes,
+        public readonly int $progress
+    ) {
+    }
+}

app/DTOs/Uploads/UploadInitResult.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+final class UploadInitResult
+{
+    public function __construct(
+        public readonly string $sessionId,
+        public readonly string $token,
+        public readonly string $status
+    ) {
+    }
+}

app/DTOs/Uploads/UploadScanResult.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+final class UploadScanResult
+{
+    public function __construct(
+        public readonly bool $ok,
+        public readonly string $reason
+    ) {
+    }
+
+    public static function clean(): self
+    {
+        return new self(true, '');
+    }
+
+    public static function infected(string $reason): self
+    {
+        return new self(false, $reason);
+    }
+}

app/DTOs/Uploads/UploadSessionData.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+use Carbon\CarbonImmutable;
+
+final class UploadSessionData
+{
+    public function __construct(
+        public readonly string $id,
+        public readonly int $userId,
+        public readonly string $tempPath,
+        public readonly string $status,
+        public readonly string $ip,
+        public readonly CarbonImmutable $createdAt,
+        public readonly int $progress,
+        public readonly ?string $failureReason
+    ) {
+    }
+}

app/DTOs/Uploads/UploadStoredFile.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+final class UploadStoredFile
+{
+    public function __construct(
+        public readonly string $path,
+        public readonly int $size,
+        public readonly string $extension
+    ) {
+    }
+
+    public static function fromPath(string $path): self
+    {
+        $size = is_file($path) ? (int) filesize($path) : 0;
+        $extension = (string) pathinfo($path, PATHINFO_EXTENSION);
+
+        return new self($path, $size, $extension);
+    }
+}

app/DTOs/Uploads/UploadValidatedFile.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+final class UploadValidatedFile
+{
+    public function __construct(
+        public readonly UploadValidationResult $validation,
+        public readonly ?string $hash
+    ) {
+    }
+}

app/DTOs/Uploads/UploadValidationResult.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs\Uploads;
+
+final class UploadValidationResult
+{
+    public function __construct(
+        public readonly bool $ok,
+        public readonly string $reason,
+        public readonly ?int $width,
+        public readonly ?int $height,
+        public readonly ?string $mime,
+        public readonly ?int $size
+    ) {
+    }
+
+    public static function ok(int $width, int $height, string $mime, int $size): self
+    {
+        return new self(true, '', $width, $height, $mime, $size);
+    }
+
+    public static function fail(string $reason, ?int $width = null, ?int $height = null, ?string $mime = null, ?int $size = null): self
+    {
+        return new self(false, $reason, $width, $height, $mime, $size);
+    }
+}

app/DTOs/UserRecoProfileDTO.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTOs;
+
+/**
+ * Lightweight value object representing a user's recommendation preference profile.
+ *
+ * Built by UserPreferenceBuilder from signals:
+ *   - favourited artworks  (+3)
+ *   - awards given         (+5)
+ *   - creator follows      (+2 for their tags)
+ *   - own uploads          (category bias)
+ *
+ * Cached in `user_reco_profiles` with a configurable TTL (default 6 hours).
+ */
+final class UserRecoProfileDTO
+{
+    /**
+     * @param array<int, string>           $topTagSlugs          Top tag slugs by weighted score (up to 20)
+     * @param array<int, string>           $topCategorySlugs     Top category slugs (up to 5)
+     * @param array<int, int>              $strongCreatorIds     Followed creator user IDs (up to 50)
+     * @param array<string, float>         $tagWeights           Tag slug → normalised weight (0–1)
+     * @param array<string, float>         $categoryWeights      Category slug → normalised weight
+     * @param array<int, string>           $dislikedTagSlugs     Future: blocked/hidden tag slugs
+     */
+    public function __construct(
+        public readonly array $topTagSlugs      = [],
+        public readonly array $topCategorySlugs = [],
+        public readonly array $strongCreatorIds = [],
+        public readonly array $tagWeights       = [],
+        public readonly array $categoryWeights  = [],
+        public readonly array $dislikedTagSlugs = [],
+    ) {}
+
+    /**
+     * True if the user has enough signals to drive personalised recommendations.
+     */
+    public function hasSignals(): bool
+    {
+        return $this->topTagSlugs !== [] || $this->strongCreatorIds !== [];
+    }
+
+    /**
+     * Returns the normalised tag weight for a given slug (0.0 if unknown).
+     */
+    public function tagWeight(string $slug): float
+    {
+        return (float) ($this->tagWeights[$slug] ?? 0.0);
+    }
+
+    /**
+     * Returns true when the creator is in the user's strong-follow list.
+     */
+    public function followsCreator(int $userId): bool
+    {
+        return in_array($userId, $this->strongCreatorIds, true);
+    }
+
+    /**
+     * Serialise for storage in the DB / Redis cache.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'top_tags'         => $this->topTagSlugs,
+            'top_categories'   => $this->topCategorySlugs,
+            'strong_creators'  => $this->strongCreatorIds,
+            'tag_weights'      => $this->tagWeights,
+            'category_weights' => $this->categoryWeights,
+            'disliked_tags'    => $this->dislikedTagSlugs,
+        ];
+    }
+
+    /**
+     * Re-hydrate from a stored array (e.g. from the DB JSON column).
+     *
+     * @param array<string, mixed> $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            topTagSlugs:      (array) ($data['top_tags']         ?? []),
+            topCategorySlugs: (array) ($data['top_categories']   ?? []),
+            strongCreatorIds: array_map('intval', (array) ($data['strong_creators'] ?? [])),
+            tagWeights:       array_map('floatval', (array) ($data['tag_weights']   ?? [])),
+            categoryWeights:  array_map('floatval', (array) ($data['category_weights'] ?? [])),
+            dislikedTagSlugs: (array) ($data['disliked_tags']    ?? []),
+        );
+    }
+}

app/Enums/ReactionType.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * Reaction slugs used in the database.
+ * Emoji are only used for display — slugs are stored.
+ */
+enum ReactionType: string
+{
+    case ThumbsUp = 'thumbs_up';
+    case Heart    = 'heart';
+    case Fire     = 'fire';
+    case Laugh    = 'laugh';
+    case Clap     = 'clap';
+    case Wow      = 'wow';
+
+    /** Return the display emoji for this reaction. */
+    public function emoji(): string
+    {
+        return match ($this) {
+            self::ThumbsUp => '👍',
+            self::Heart    => '❤️',
+            self::Fire     => '🔥',
+            self::Laugh    => '😂',
+            self::Clap     => '👏',
+            self::Wow      => '😮',
+        };
+    }
+
+    /** Human-readable label. */
+    public function label(): string
+    {
+        return match ($this) {
+            self::ThumbsUp => 'Like',
+            self::Heart    => 'Love',
+            self::Fire     => 'Fire',
+            self::Laugh    => 'Haha',
+            self::Clap     => 'Clap',
+            self::Wow      => 'Wow',
+        };
+    }
+
+    /** All valid slugs — used for validation. */
+    public static function values(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+
+    /** Full UI payload for the frontend. */
+    public static function asMap(): array
+    {
+        $map = [];
+        foreach (self::cases() as $case) {
+            $map[$case->value] = [
+                'slug'  => $case->value,
+                'emoji' => $case->emoji(),
+                'label' => $case->label(),
+            ];
+        }
+        return $map;
+    }
+}

app/Events/MessageSent.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class MessageSent
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(
+        public int $conversationId,
+        public int $messageId,
+        public int $senderId,
+    ) {}
+}

app/Events/TypingStarted.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class TypingStarted
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(
+        public int $conversationId,
+        public int $userId,
+    ) {}
+}

app/Events/TypingStopped.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class TypingStopped
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(
+        public int $conversationId,
+        public int $userId,
+    ) {}
+}

app/Http/Controllers/Api/Admin/FeedPerformanceReportController.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class FeedPerformanceReportController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'from' => ['nullable', 'date_format:Y-m-d'],
+            'to' => ['nullable', 'date_format:Y-m-d'],
+            'limit' => ['nullable', 'integer', 'min:1', 'max:1000'],
+        ]);
+
+        $from = (string) ($validated['from'] ?? now()->subDays(29)->toDateString());
+        $to = (string) ($validated['to'] ?? now()->toDateString());
+        $limit = (int) ($validated['limit'] ?? 100);
+
+        if ($from > $to) {
+            return response()->json([
+                'message' => 'Invalid date range: from must be before or equal to to.',
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $rows = DB::table('feed_daily_metrics')
+            ->selectRaw('algo_version, source')
+            ->selectRaw('SUM(impressions) as impressions')
+            ->selectRaw('SUM(clicks) as clicks')
+            ->selectRaw('SUM(saves) as saves')
+            ->selectRaw('SUM(dwell_0_5) as dwell_0_5')
+            ->selectRaw('SUM(dwell_5_30) as dwell_5_30')
+            ->selectRaw('SUM(dwell_30_120) as dwell_30_120')
+            ->selectRaw('SUM(dwell_120_plus) as dwell_120_plus')
+            ->whereBetween('metric_date', [$from, $to])
+            ->groupBy('algo_version', 'source')
+            ->orderBy('algo_version')
+            ->orderBy('source')
+            ->get();
+
+        $byAlgoSource = $rows->map(static function ($row): array {
+            $impressions = (int) ($row->impressions ?? 0);
+            $clicks = (int) ($row->clicks ?? 0);
+            $saves = (int) ($row->saves ?? 0);
+
+            return [
+                'algo_version' => (string) $row->algo_version,
+                'source' => (string) $row->source,
+                'impressions' => $impressions,
+                'clicks' => $clicks,
+                'saves' => $saves,
+                'ctr' => round($impressions > 0 ? $clicks / $impressions : 0.0, 6),
+                'save_rate' => round($clicks > 0 ? $saves / $clicks : 0.0, 6),
+                'dwell_buckets' => [
+                    '0_5' => (int) ($row->dwell_0_5 ?? 0),
+                    '5_30' => (int) ($row->dwell_5_30 ?? 0),
+                    '30_120' => (int) ($row->dwell_30_120 ?? 0),
+                    '120_plus' => (int) ($row->dwell_120_plus ?? 0),
+                ],
+            ];
+        })->values();
+
+        $topClickedArtworks = DB::table('feed_events as e')
+            ->leftJoin('artworks as a', 'a.id', '=', 'e.artwork_id')
+            ->selectRaw('e.algo_version')
+            ->selectRaw('e.source')
+            ->selectRaw('e.artwork_id')
+            ->selectRaw('a.title as artwork_title')
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'feed_impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'feed_click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereBetween('e.event_date', [$from, $to])
+            ->groupBy('e.algo_version', 'e.source', 'e.artwork_id', 'a.title')
+            ->get()
+            ->map(static function ($row): array {
+                $impressions = (int) ($row->impressions ?? 0);
+                $clicks = (int) ($row->clicks ?? 0);
+
+                return [
+                    'algo_version' => (string) $row->algo_version,
+                    'source' => (string) $row->source,
+                    'artwork_id' => (int) $row->artwork_id,
+                    'artwork_title' => (string) ($row->artwork_title ?? ''),
+                    'impressions' => $impressions,
+                    'clicks' => $clicks,
+                    'ctr' => round($impressions > 0 ? $clicks / $impressions : 0.0, 6),
+                ];
+            })
+            ->sort(static function (array $a, array $b): int {
+                $clickCompare = $b['clicks'] <=> $a['clicks'];
+                if ($clickCompare !== 0) {
+                    return $clickCompare;
+                }
+
+                return $b['ctr'] <=> $a['ctr'];
+            })
+            ->take($limit)
+            ->values();
+
+        return response()->json([
+            'meta' => [
+                'from' => $from,
+                'to' => $to,
+                'generated_at' => now()->toISOString(),
+                'limit' => $limit,
+            ],
+            'by_algo_source' => $byAlgoSource,
+            'top_clicked_artworks' => $topClickedArtworks,
+        ], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/Admin/ModerationReportQueueController.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Report;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class ModerationReportQueueController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $status = (string) $request->query('status', 'open');
+        $status = in_array($status, ['open', 'reviewing', 'closed'], true) ? $status : 'open';
+
+        $items = Report::query()
+            ->with('reporter:id,username')
+            ->where('status', $status)
+            ->orderByDesc('id')
+            ->paginate(30);
+
+        return response()->json($items);
+    }
+}

app/Http/Controllers/Api/Admin/SimilarArtworkReportController.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class SimilarArtworkReportController extends Controller
+{
+    public function index(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'from' => ['nullable', 'date_format:Y-m-d'],
+            'to' => ['nullable', 'date_format:Y-m-d'],
+            'limit' => ['nullable', 'integer', 'min:1', 'max:1000'],
+        ]);
+
+        $from = (string) ($validated['from'] ?? now()->subDays(29)->toDateString());
+        $to = (string) ($validated['to'] ?? now()->toDateString());
+        $limit = (int) ($validated['limit'] ?? 100);
+
+        if ($from > $to) {
+            return response()->json([
+                'message' => 'Invalid date range: from must be before or equal to to.',
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $byAlgoRows = DB::table('similar_artwork_events')
+            ->selectRaw('algo_version')
+            ->selectRaw("SUM(CASE WHEN event_type = 'impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN event_type = 'click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereBetween('event_date', [$from, $to])
+            ->groupBy('algo_version')
+            ->orderBy('algo_version')
+            ->get();
+
+        $byAlgo = $byAlgoRows->map(static function ($row): array {
+            $impressions = (int) ($row->impressions ?? 0);
+            $clicks = (int) ($row->clicks ?? 0);
+            $ctr = $impressions > 0 ? $clicks / $impressions : 0.0;
+
+            return [
+                'algo_version' => (string) $row->algo_version,
+                'impressions' => $impressions,
+                'clicks' => $clicks,
+                'ctr' => round($ctr, 6),
+            ];
+        })->values();
+
+        $pairRows = DB::table('similar_artwork_events as e')
+            ->leftJoin('artworks as source', 'source.id', '=', 'e.source_artwork_id')
+            ->leftJoin('artworks as similar', 'similar.id', '=', 'e.similar_artwork_id')
+            ->selectRaw('e.algo_version')
+            ->selectRaw('e.source_artwork_id')
+            ->selectRaw('e.similar_artwork_id')
+            ->selectRaw('source.title as source_title')
+            ->selectRaw('similar.title as similar_title')
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'impression' THEN 1 ELSE 0 END) AS impressions")
+            ->selectRaw("SUM(CASE WHEN e.event_type = 'click' THEN 1 ELSE 0 END) AS clicks")
+            ->whereBetween('e.event_date', [$from, $to])
+            ->whereNotNull('e.similar_artwork_id')
+            ->groupBy('e.algo_version', 'e.source_artwork_id', 'e.similar_artwork_id', 'source.title', 'similar.title')
+            ->get();
+
+        $topSimilarities = $pairRows
+            ->map(static function ($row): array {
+                $impressions = (int) ($row->impressions ?? 0);
+                $clicks = (int) ($row->clicks ?? 0);
+                $ctr = $impressions > 0 ? $clicks / $impressions : 0.0;
+
+                return [
+                    'algo_version' => (string) $row->algo_version,
+                    'source_artwork_id' => (int) $row->source_artwork_id,
+                    'source_title' => (string) ($row->source_title ?? ''),
+                    'similar_artwork_id' => (int) $row->similar_artwork_id,
+                    'similar_title' => (string) ($row->similar_title ?? ''),
+                    'impressions' => $impressions,
+                    'clicks' => $clicks,
+                    'ctr' => round($ctr, 6),
+                ];
+            })
+            ->sort(function (array $a, array $b): int {
+                $ctrCompare = $b['ctr'] <=> $a['ctr'];
+                if ($ctrCompare !== 0) {
+                    return $ctrCompare;
+                }
+
+                $clickCompare = $b['clicks'] <=> $a['clicks'];
+                if ($clickCompare !== 0) {
+                    return $clickCompare;
+                }
+
+                return $b['impressions'] <=> $a['impressions'];
+            })
+            ->take($limit)
+            ->values();
+
+        return response()->json([
+            'meta' => [
+                'from' => $from,
+                'to' => $to,
+                'generated_at' => now()->toISOString(),
+                'limit' => $limit,
+            ],
+            'by_algo_version' => $byAlgo,
+            'top_similarities' => $topSimilarities,
+        ], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/Admin/UploadModerationController.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Upload;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+final class UploadModerationController extends Controller
+{
+    public function pending(): JsonResponse
+    {
+        $uploads = Upload::query()
+            ->where('status', 'draft')
+            ->where('moderation_status', 'pending')
+            ->orderBy('created_at')
+            ->get([
+                'id',
+                'user_id',
+                'type',
+                'status',
+                'processing_state',
+                'title',
+                'preview_path',
+                'created_at',
+                'moderation_status',
+            ]);
+
+        return response()->json([
+            'data' => $uploads,
+        ], Response::HTTP_OK);
+    }
+
+    public function approve(string $id, Request $request): JsonResponse
+    {
+        $upload = Upload::query()->find($id);
+
+        if (! $upload) {
+            return response()->json(['message' => 'Upload not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        $upload->moderation_status = 'approved';
+        $upload->moderated_at = now();
+        $upload->moderated_by = (int) $request->user()->id;
+        $upload->moderation_note = $request->input('note');
+        $upload->save();
+
+        return response()->json([
+            'success' => true,
+            'id' => (string) $upload->id,
+            'moderation_status' => (string) $upload->moderation_status,
+        ], Response::HTTP_OK);
+    }
+
+    public function reject(string $id, Request $request): JsonResponse
+    {
+        $upload = Upload::query()->find($id);
+
+        if (! $upload) {
+            return response()->json(['message' => 'Upload not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        $upload->moderation_status = 'rejected';
+        $upload->status = 'rejected';
+        $upload->processing_state = 'rejected';
+        $upload->moderated_at = now();
+        $upload->moderated_by = (int) $request->user()->id;
+        $upload->moderation_note = (string) $request->input('note', '');
+        $upload->save();
+
+        return response()->json([
+            'success' => true,
+            'id' => (string) $upload->id,
+            'status' => (string) $upload->status,
+            'processing_state' => (string) $upload->processing_state,
+            'moderation_status' => (string) $upload->moderation_status,
+        ], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/Admin/UsernameApprovalController.php

@@ -0,0 +1,149 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use App\Support\UsernamePolicy;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class UsernameApprovalController extends Controller
+{
+    public function pending(): JsonResponse
+    {
+        $rows = DB::table('username_approval_requests')
+            ->where('status', 'pending')
+            ->orderBy('created_at')
+            ->get([
+                'id',
+                'user_id',
+                'requested_username',
+                'context',
+                'similar_to',
+                'payload',
+                'created_at',
+            ]);
+
+        return response()->json(['data' => $rows], Response::HTTP_OK);
+    }
+
+    public function approve(int $id, Request $request): JsonResponse
+    {
+        $row = DB::table('username_approval_requests')->where('id', $id)->first();
+        if (! $row) {
+            return response()->json(['message' => 'Request not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        if ((string) $row->status !== 'pending') {
+            return response()->json(['message' => 'Request is not pending.'], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        DB::beginTransaction();
+        try {
+            DB::table('username_approval_requests')
+                ->where('id', $id)
+                ->update([
+                    'status' => 'approved',
+                    'reviewed_by' => (int) $request->user()->id,
+                    'reviewed_at' => now(),
+                    'review_note' => (string) $request->input('note', ''),
+                    'updated_at' => now(),
+                ]);
+
+            if ((string) $row->context === 'profile_update' && ! empty($row->user_id)) {
+                $this->applyProfileRename((int) $row->user_id, (string) $row->requested_username);
+            }
+
+            DB::commit();
+        } catch (\Throwable $e) {
+            DB::rollBack();
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        return response()->json([
+            'success' => true,
+            'id' => $id,
+            'status' => 'approved',
+        ], Response::HTTP_OK);
+    }
+
+    public function reject(int $id, Request $request): JsonResponse
+    {
+        $affected = DB::table('username_approval_requests')
+            ->where('id', $id)
+            ->where('status', 'pending')
+            ->update([
+                'status' => 'rejected',
+                'reviewed_by' => (int) $request->user()->id,
+                'reviewed_at' => now(),
+                'review_note' => (string) $request->input('note', ''),
+                'updated_at' => now(),
+            ]);
+
+        if ($affected === 0) {
+            return response()->json(['message' => 'Request not found or not pending.'], Response::HTTP_NOT_FOUND);
+        }
+
+        return response()->json([
+            'success' => true,
+            'id' => $id,
+            'status' => 'rejected',
+        ], Response::HTTP_OK);
+    }
+
+    private function applyProfileRename(int $userId, string $requestedUsername): void
+    {
+        $user = User::query()->find($userId);
+        if (! $user) {
+            return;
+        }
+
+        $requested = UsernamePolicy::normalize($requestedUsername);
+        if ($requested === '') {
+            throw new \RuntimeException('Requested username is invalid.');
+        }
+
+        $exists = User::query()
+            ->whereRaw('LOWER(username) = ?', [$requested])
+            ->where('id', '!=', $userId)
+            ->exists();
+
+        if ($exists) {
+            throw new \RuntimeException('Requested username is already taken.');
+        }
+
+        $old = UsernamePolicy::normalize((string) ($user->username ?? ''));
+        if ($old === $requested) {
+            return;
+        }
+
+        $user->username = $requested;
+        $user->username_changed_at = now();
+        $user->save();
+
+        if ($old !== '') {
+            DB::table('username_history')->insert([
+                'user_id' => $userId,
+                'old_username' => $old,
+                'changed_at' => now(),
+                'created_at' => now(),
+                'updated_at' => now(),
+            ]);
+
+            DB::table('username_redirects')->updateOrInsert(
+                ['old_username' => $old],
+                [
+                    'new_username' => $requested,
+                    'user_id' => $userId,
+                    'created_at' => now(),
+                    'updated_at' => now(),
+                ]
+            );
+        }
+    }
+}

app/Http/Controllers/Api/ArtworkAwardController.php

@@ -0,0 +1,132 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Models\ArtworkAward;
+use App\Services\ArtworkAwardService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class ArtworkAwardController extends Controller
+{
+    public function __construct(
+        private readonly ArtworkAwardService $service
+    ) {}
+
+    /**
+     * POST /api/artworks/{id}/award
+     * Award the artwork with a medal.
+     */
+    public function store(Request $request, int $id): JsonResponse
+    {
+        $user    = $request->user();
+        $artwork = Artwork::findOrFail($id);
+
+        $this->authorize('award', [ArtworkAward::class, $artwork]);
+
+        $data = $request->validate([
+            'medal' => ['required', 'string', 'in:gold,silver,bronze'],
+        ]);
+
+        $award = $this->service->award($artwork, $user, $data['medal']);
+
+        // Record activity event
+        try {
+            \App\Models\ActivityEvent::record(
+                actorId:    $user->id,
+                type:       \App\Models\ActivityEvent::TYPE_AWARD,
+                targetType: \App\Models\ActivityEvent::TARGET_ARTWORK,
+                targetId:   $artwork->id,
+                meta:       ['medal' => $data['medal']],
+            );
+        } catch (\Throwable) {}
+
+        return response()->json(
+            $this->buildPayload($artwork->id, $user->id),
+            201
+        );
+    }
+
+    /**
+     * PUT /api/artworks/{id}/award
+     * Change an existing award medal.
+     */
+    public function update(Request $request, int $id): JsonResponse
+    {
+        $user    = $request->user();
+        $artwork = Artwork::findOrFail($id);
+
+        $existingAward = ArtworkAward::where('artwork_id', $artwork->id)
+            ->where('user_id', $user->id)
+            ->firstOrFail();
+
+        $this->authorize('change', $existingAward);
+
+        $data = $request->validate([
+            'medal' => ['required', 'string', 'in:gold,silver,bronze'],
+        ]);
+
+        $award = $this->service->changeAward($artwork, $user, $data['medal']);
+
+        return response()->json($this->buildPayload($artwork->id, $user->id));
+    }
+
+    /**
+     * DELETE /api/artworks/{id}/award
+     * Remove the user's award for this artwork.
+     */
+    public function destroy(Request $request, int $id): JsonResponse
+    {
+        $user    = $request->user();
+        $artwork = Artwork::findOrFail($id);
+
+        $existingAward = ArtworkAward::where('artwork_id', $artwork->id)
+            ->where('user_id', $user->id)
+            ->firstOrFail();
+
+        $this->authorize('remove', $existingAward);
+
+        $this->service->removeAward($artwork, $user);
+
+        return response()->json($this->buildPayload($artwork->id, $user->id));
+    }
+
+    /**
+     * GET /api/artworks/{id}/awards
+     * Return award stats + viewer's current award.
+     */
+    public function show(Request $request, int $id): JsonResponse
+    {
+        $artwork = Artwork::findOrFail($id);
+
+        return response()->json($this->buildPayload($artwork->id, $request->user()?->id));
+    }
+
+    // -------------------------------------------------------------------------
+    // All authorization is delegated to ArtworkAwardPolicy via $this->authorize().
+
+    private function buildPayload(int $artworkId, ?int $userId): array
+    {
+        $stat = \App\Models\ArtworkAwardStat::find($artworkId);
+
+        $userAward = $userId
+            ? ArtworkAward::where('artwork_id', $artworkId)
+                ->where('user_id', $userId)
+                ->value('medal')
+            : null;
+
+        return [
+            'awards' => [
+                'gold'        => $stat?->gold_count ?? 0,
+                'silver'      => $stat?->silver_count ?? 0,
+                'bronze'      => $stat?->bronze_count ?? 0,
+                'score'       => $stat?->score_total ?? 0,
+            ],
+            'viewer_award' => $userAward,
+        ];
+    }
+}

app/Http/Controllers/Api/ArtworkCommentController.php

@@ -0,0 +1,220 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Models\ArtworkComment;
+use App\Services\ContentSanitizer;
+use App\Services\LegacySmileyMapper;
+use App\Support\AvatarUrl;
+use Carbon\Carbon;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Gate;
+
+/**
+ * Artwork comment CRUD.
+ *
+ * POST   /api/artworks/{artworkId}/comments          → store
+ * PUT    /api/artworks/{artworkId}/comments/{id}     → update (own comment)
+ * DELETE /api/artworks/{artworkId}/comments/{id}     → delete (own or admin)
+ * GET    /api/artworks/{artworkId}/comments          → list (paginated)
+ */
+class ArtworkCommentController extends Controller
+{
+    private const MAX_LENGTH = 10_000;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // List
+    // ─────────────────────────────────────────────────────────────────────────
+
+    public function index(Request $request, int $artworkId): JsonResponse
+    {
+        $artwork = Artwork::public()->published()->findOrFail($artworkId);
+
+        $page     = max(1, (int) $request->query('page', 1));
+        $perPage  = 20;
+
+        // Only fetch top-level comments (no parent). Replies are recursively eager-loaded.
+        $comments = ArtworkComment::with([
+                'user', 'user.profile',
+                'approvedReplies',
+            ])
+            ->where('artwork_id', $artwork->id)
+            ->where('is_approved', true)
+            ->whereNull('parent_id')
+            ->orderByDesc('created_at')
+            ->paginate($perPage, ['*'], 'page', $page);
+
+        $userId = $request->user()?->id;
+        $items  = $comments->getCollection()->map(fn ($c) => $this->formatComment($c, $userId, true));
+
+        return response()->json([
+            'data' => $items,
+            'meta' => [
+                'current_page' => $comments->currentPage(),
+                'last_page'    => $comments->lastPage(),
+                'total'        => $comments->total(),
+                'per_page'     => $comments->perPage(),
+            ],
+        ]);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Store
+    // ─────────────────────────────────────────────────────────────────────────
+
+    public function store(Request $request, int $artworkId): JsonResponse
+    {
+        $artwork = Artwork::public()->published()->findOrFail($artworkId);
+
+        $request->validate([
+            'content'   => ['required', 'string', 'min:1', 'max:' . self::MAX_LENGTH],
+            'parent_id' => ['nullable', 'integer', 'exists:artwork_comments,id'],
+        ]);
+
+        $raw = $request->input('content');
+        $parentId = $request->input('parent_id');
+
+        // If replying, validate parent belongs to same artwork and is approved
+        if ($parentId) {
+            $parent = ArtworkComment::where('artwork_id', $artwork->id)
+                ->where('is_approved', true)
+                ->find($parentId);
+
+            if (! $parent) {
+                return response()->json([
+                    'errors' => ['parent_id' => ['The comment you are replying to is no longer available.']],
+                ], 422);
+            }
+        }
+
+        // Validate markdown-lite content
+        $errors = ContentSanitizer::validate($raw);
+        if ($errors) {
+            return response()->json(['errors' => ['content' => $errors]], 422);
+        }
+
+        $rendered = ContentSanitizer::render($raw);
+
+        $comment = ArtworkComment::create([
+            'artwork_id'       => $artwork->id,
+            'user_id'          => $request->user()->id,
+            'parent_id'        => $parentId,
+            'content'          => $raw,      // legacy column (plain text fallback)
+            'raw_content'      => $raw,
+            'rendered_content' => $rendered,
+            'is_approved'      => true,       // auto-approve; extend with moderation as needed
+        ]);
+
+        // Bust the comments cache for this user's 'all' feed
+        Cache::forget('comments.latest.all.page1');
+
+        $comment->load(['user', 'user.profile']);
+
+        // Record activity event (fire-and-forget; never break the response)
+        try {
+            \App\Models\ActivityEvent::record(
+                actorId:    $request->user()->id,
+                type:       \App\Models\ActivityEvent::TYPE_COMMENT,
+                targetType: \App\Models\ActivityEvent::TARGET_ARTWORK,
+                targetId:   $artwork->id,
+            );
+        } catch (\Throwable) {}
+
+        return response()->json(['data' => $this->formatComment($comment, $request->user()->id, false)], 201);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Update
+    // ─────────────────────────────────────────────────────────────────────────
+
+    public function update(Request $request, int $artworkId, int $commentId): JsonResponse
+    {
+        $comment = ArtworkComment::where('artwork_id', $artworkId)
+            ->findOrFail($commentId);
+
+        Gate::authorize('update', $comment);
+
+        $request->validate([
+            'content' => ['required', 'string', 'min:1', 'max:' . self::MAX_LENGTH],
+        ]);
+
+        $raw    = $request->input('content');
+        $errors = ContentSanitizer::validate($raw);
+        if ($errors) {
+            return response()->json(['errors' => ['content' => $errors]], 422);
+        }
+
+        $rendered = ContentSanitizer::render($raw);
+
+        $comment->update([
+            'content'          => $raw,
+            'raw_content'      => $raw,
+            'rendered_content' => $rendered,
+        ]);
+
+        Cache::forget('comments.latest.all.page1');
+
+        $comment->load(['user', 'user.profile']);
+
+        return response()->json(['data' => $this->formatComment($comment, $request->user()->id, false)]);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Delete
+    // ─────────────────────────────────────────────────────────────────────────
+
+    public function destroy(Request $request, int $artworkId, int $commentId): JsonResponse
+    {
+        $comment = ArtworkComment::where('artwork_id', $artworkId)->findOrFail($commentId);
+
+        Gate::authorize('delete', $comment);
+
+        $comment->delete();
+        Cache::forget('comments.latest.all.page1');
+
+        return response()->json(['message' => 'Comment deleted.'], 200);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Helpers
+    // ─────────────────────────────────────────────────────────────────────────
+
+    private function formatComment(ArtworkComment $c, ?int $currentUserId, bool $includeReplies = false): array
+    {
+        $user     = $c->user;
+        $userId   = (int) ($c->user_id ?? 0);
+        $avatarHash = $user?->profile?->avatar_hash ?? null;
+
+        $data = [
+            'id'               => $c->id,
+            'parent_id'        => $c->parent_id,
+            'raw_content'      => $c->raw_content ?? $c->content,
+            'rendered_content' => $c->rendered_content ?? e(strip_tags($c->content ?? '')),
+            'created_at'       => $c->created_at?->toIso8601String(),
+            'time_ago'         => $c->created_at ? Carbon::parse($c->created_at)->diffForHumans() : null,
+            'can_edit'         => $currentUserId === $userId,
+            'can_delete'       => $currentUserId === $userId,
+            'user' => [
+                'id'          => $userId,
+                'username'    => $user?->username,
+                'display'     => $user?->username ?? $user?->name ?? 'User',
+                'profile_url' => $user?->username ? '/@' . $user->username : '/profile/' . $userId,
+                'avatar_url'  => AvatarUrl::forUser($userId, $avatarHash, 64),
+            ],
+        ];
+
+        if ($includeReplies && $c->relationLoaded('approvedReplies')) {
+            $data['replies'] = $c->approvedReplies->map(fn ($r) => $this->formatComment($r, $currentUserId, true))->values()->toArray();
+        } elseif ($includeReplies && $c->relationLoaded('replies')) {
+            $data['replies'] = $c->replies->map(fn ($r) => $this->formatComment($r, $currentUserId, true))->values()->toArray();
+        } else {
+            $data['replies'] = [];
+        }
+
+        return $data;
+    }
+}

app/Http/Controllers/Api/ArtworkController.php

@@ -2,11 +2,14 @@
 namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Artworks\ArtworkCreateRequest;
 use App\Http\Resources\ArtworkListResource;
 use App\Http\Resources\ArtworkResource;
 use App\Services\ArtworkService;
+use App\Services\Artworks\ArtworkDraftService;
 use App\Models\Category;
 use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
 
 class ArtworkController extends Controller
 {
@@ -17,6 +20,27 @@ class ArtworkController extends Controller
         $this->service = $service;
     }
 
+    /**
+     * POST /api/artworks
+     * Creates a draft artwork placeholder for the upload pipeline.
+     */
+    public function store(ArtworkCreateRequest $request, ArtworkDraftService $drafts)
+    {
+        $user = $request->user();
+        $data = $request->validated();
+
+        $result = $drafts->createDraft(
+            (int) $user->id,
+            (string) $data['title'],
+            isset($data['description']) ? (string) $data['description'] : null
+        );
+
+        return response()->json([
+            'artwork_id' => $result->artworkId,
+            'status' => $result->status,
+        ], Response::HTTP_CREATED);
+    }
+
     /**
      * GET /api/v1/artworks/{slug}
      * Returns a single public artwork resource by slug.

app/Http/Controllers/Api/ArtworkDownloadController.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Services\ArtworkStatsService;
+use App\Services\ThumbnailPresenter;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+/**
+ * POST /api/art/{id}/download
+ *
+ * Records a download event and returns the full-resolution download URL.
+ *
+ * Responsibilities:
+ *   1. Validates the artwork is public and published.
+ *   2. Inserts a row in artwork_downloads (artwork_id, user_id, ip, user_agent).
+ *   3. Increments artwork_stats.downloads + forwards to creator stats.
+ *   4. Returns {"ok": true, "url": "<download_url>"} so the frontend can
+ *      trigger the actual browser download.
+ *
+ * The frontend fires this POST on click, then uses the returned URL to
+ * trigger the file download (or falls back to the pre-resolved URL it
+ * already has).
+ */
+final class ArtworkDownloadController extends Controller
+{
+    public function __construct(private readonly ArtworkStatsService $stats) {}
+
+    public function __invoke(Request $request, int $id): JsonResponse
+    {
+        $artwork = Artwork::public()
+            ->published()
+            ->with(['user:id'])
+            ->where('id', $id)
+            ->first();
+
+        if (! $artwork) {
+            return response()->json(['error' => 'Not found'], 404);
+        }
+
+        // Record the download event — non-blocking, errors are swallowed.
+        $this->recordDownload($request, $artwork);
+
+        // Increment counters — deferred via Redis when available.
+        try {
+            $this->stats->incrementDownloads((int) $artwork->id, 1, defer: true);
+        } catch (\Throwable) {
+            // Stats failure must never interrupt the download.
+        }
+
+        // Resolve the highest-resolution download URL available.
+        $url = $this->resolveDownloadUrl($artwork);
+
+        // Build a user-friendly download filename: "title-slug.file_ext"
+        $ext      = $artwork->file_ext ?: $artwork->thumb_ext ?: 'webp';
+        $slug     = Str::slug((string) ($artwork->slug ?: $artwork->title)) ?: (string) $artwork->id;
+        $filename = $slug . '.' . $ext;
+
+        return response()->json([
+            'ok'       => true,
+            'url'      => $url,
+            'filename' => $filename,
+            'size'     => (int) ($artwork->file_size ?? 0),
+        ]);
+    }
+
+    /**
+     * Insert a row in artwork_downloads.
+     * Uses a raw insert for the binary(16) IP column.
+     * Silently ignores failures (analytics should never break user flow).
+     */
+    private function recordDownload(Request $request, Artwork $artwork): void
+    {
+        try {
+            $ip  = $request->ip() ?? '0.0.0.0';
+            $bin = @inet_pton($ip);
+
+            DB::table('artwork_downloads')->insert([
+                'artwork_id' => $artwork->id,
+                'user_id'    => $request->user()?->id,
+                'ip'         => $bin !== false ? $bin : null,
+                'user_agent' => mb_substr((string) $request->userAgent(), 0, 512),
+                'created_at' => now(),
+            ]);
+        } catch (\Throwable) {
+            // Analytics failure must never interrupt the download.
+        }
+    }
+
+    /**
+     * Resolve the original full-resolution CDN URL.
+     *
+     * Originals are stored at: {cdn}/original/{h1}/{h2}/{hash}.{file_ext}
+     * h1 = first 2 chars of hash, h2 = next 2 chars, filename = full hash + file_ext.
+     * Falls back to XL → LG → MD thumbnail when hash is unavailable.
+     */
+    private function resolveDownloadUrl(Artwork $artwork): string
+    {
+        $hash = $artwork->hash ?? null;
+        $ext  = ltrim((string) ($artwork->file_ext ?: $artwork->thumb_ext ?: 'webp'), '.');
+
+        if (!empty($hash)) {
+            $h   = strtolower(preg_replace('/[^a-f0-9]/', '', $hash));
+            $h1  = substr($h, 0, 2);
+            $h2  = substr($h, 2, 2);
+            $cdn = rtrim((string) config('cdn.files_url', 'https://files.skinbase.org'), '/');
+
+            return sprintf('%s/original/%s/%s/%s.%s', $cdn, $h1, $h2, $h, $ext);
+        }
+
+        // Fallback: best available thumbnail size
+        foreach (['xl', 'lg', 'md'] as $size) {
+            $thumb = ThumbnailPresenter::present($artwork, $size);
+            if (!empty($thumb['url'])) {
+                return (string) $thumb['url'];
+            }
+        }
+
+        return '';
+    }
+}

app/Http/Controllers/Api/ArtworkInteractionController.php

@@ -0,0 +1,223 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\FollowService;
+use App\Services\UserStatsService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+final class ArtworkInteractionController extends Controller
+{
+    public function favorite(Request $request, int $artworkId): JsonResponse
+    {
+        $state = $request->boolean('state', true);
+
+        $this->toggleSimple(
+            request: $request,
+            table: 'artwork_favourites',
+            keyColumns: ['user_id', 'artwork_id'],
+            keyValues: ['user_id' => (int) $request->user()->id, 'artwork_id' => $artworkId],
+            insertPayload: ['created_at' => now(), 'updated_at' => now()],
+            requiredTable: 'artwork_favourites'
+        );
+
+        $this->syncArtworkStats($artworkId);
+
+        // Update creator's favorites_received_count
+        $creatorId = (int) DB::table('artworks')->where('id', $artworkId)->value('user_id');
+        if ($creatorId) {
+            $svc = app(UserStatsService::class);
+            if ($state) {
+                $svc->incrementFavoritesReceived($creatorId);
+                $svc->setLastActiveAt((int) $request->user()->id);
+
+                // Record activity event (new favourite only)
+                try {
+                    \App\Models\ActivityEvent::record(
+                        actorId:    (int) $request->user()->id,
+                        type:       \App\Models\ActivityEvent::TYPE_FAVORITE,
+                        targetType: \App\Models\ActivityEvent::TARGET_ARTWORK,
+                        targetId:   $artworkId,
+                    );
+                } catch (\Throwable) {}
+            } else {
+                $svc->decrementFavoritesReceived($creatorId);
+            }
+        }
+
+        return response()->json($this->statusPayload((int) $request->user()->id, $artworkId));
+    }
+
+    public function like(Request $request, int $artworkId): JsonResponse
+    {
+        $this->toggleSimple(
+            request: $request,
+            table: 'artwork_likes',
+            keyColumns: ['user_id', 'artwork_id'],
+            keyValues: ['user_id' => (int) $request->user()->id, 'artwork_id' => $artworkId],
+            insertPayload: ['created_at' => now(), 'updated_at' => now()],
+            requiredTable: 'artwork_likes'
+        );
+
+        $this->syncArtworkStats($artworkId);
+
+        return response()->json($this->statusPayload((int) $request->user()->id, $artworkId));
+    }
+
+    public function report(Request $request, int $artworkId): JsonResponse
+    {
+        if (! Schema::hasTable('artwork_reports')) {
+            return response()->json(['message' => 'Reporting unavailable'], 422);
+        }
+
+        $data = $request->validate([
+            'reason' => ['nullable', 'string', 'max:1000'],
+        ]);
+
+        DB::table('artwork_reports')->updateOrInsert(
+            [
+                'artwork_id' => $artworkId,
+                'reporter_user_id' => (int) $request->user()->id,
+            ],
+            [
+                'reason' => trim((string) ($data['reason'] ?? '')) ?: null,
+                'reported_at' => now(),
+                'created_at' => now(),
+                'updated_at' => now(),
+            ]
+        );
+
+        return response()->json(['ok' => true, 'reported' => true]);
+    }
+
+    public function follow(Request $request, int $userId): JsonResponse
+    {
+        $actorId = (int) $request->user()->id;
+
+        if ($actorId === $userId) {
+            return response()->json(['message' => 'Cannot follow yourself'], 422);
+        }
+
+        $svc   = app(FollowService::class);
+        $state = $request->boolean('state', true);
+
+        if ($state) {
+            $svc->follow($actorId, $userId);
+        } else {
+            $svc->unfollow($actorId, $userId);
+        }
+
+        return response()->json([
+            'ok'              => true,
+            'is_following'    => $state,
+            'followers_count' => $svc->followersCount($userId),
+        ]);
+    }
+
+    /**
+     * POST /api/artworks/{id}/share — record a share event (Phase 2 tracking).
+     */
+    public function share(Request $request, int $artworkId): JsonResponse
+    {
+        $data = $request->validate([
+            'platform' => ['required', 'string', 'in:facebook,twitter,pinterest,email,copy,embed'],
+        ]);
+
+        if (Schema::hasTable('artwork_shares')) {
+            DB::table('artwork_shares')->insert([
+                'artwork_id' => $artworkId,
+                'user_id'    => $request->user()?->id,
+                'platform'   => $data['platform'],
+                'created_at' => now(),
+            ]);
+        }
+
+        return response()->json(['ok' => true]);
+    }
+
+    private function toggleSimple(
+        Request $request,
+        string $table,
+        array $keyColumns,
+        array $keyValues,
+        array $insertPayload,
+        string $requiredTable
+    ): void {
+        if (! Schema::hasTable($requiredTable)) {
+            abort(422, 'Interaction unavailable');
+        }
+
+        $state = $request->boolean('state', true);
+
+        $query = DB::table($table);
+        foreach ($keyColumns as $column) {
+            $query->where($column, $keyValues[$column]);
+        }
+
+        if ($state) {
+            if (! $query->exists()) {
+                DB::table($table)->insert(array_merge($keyValues, $insertPayload));
+            }
+        } else {
+            $query->delete();
+        }
+    }
+
+    private function syncArtworkStats(int $artworkId): void
+    {
+        if (! Schema::hasTable('artwork_stats')) {
+            return;
+        }
+
+        $favorites = Schema::hasTable('artwork_favourites')
+            ? (int) DB::table('artwork_favourites')->where('artwork_id', $artworkId)->count()
+            : 0;
+
+        $likes = Schema::hasTable('artwork_likes')
+            ? (int) DB::table('artwork_likes')->where('artwork_id', $artworkId)->count()
+            : 0;
+
+        DB::table('artwork_stats')->updateOrInsert(
+            ['artwork_id' => $artworkId],
+            [
+                'favorites' => $favorites,
+                'rating_count' => $likes,
+            ]
+        );
+    }
+
+    private function statusPayload(int $viewerId, int $artworkId): array
+    {
+        $isFavorited = Schema::hasTable('artwork_favourites')
+            ? DB::table('artwork_favourites')->where('user_id', $viewerId)->where('artwork_id', $artworkId)->exists()
+            : false;
+
+        $isLiked = Schema::hasTable('artwork_likes')
+            ? DB::table('artwork_likes')->where('user_id', $viewerId)->where('artwork_id', $artworkId)->exists()
+            : false;
+
+        $favorites = Schema::hasTable('artwork_favourites')
+            ? (int) DB::table('artwork_favourites')->where('artwork_id', $artworkId)->count()
+            : 0;
+
+        $likes = Schema::hasTable('artwork_likes')
+            ? (int) DB::table('artwork_likes')->where('artwork_id', $artworkId)->count()
+            : 0;
+
+        return [
+            'ok' => true,
+            'is_favorited' => $isFavorited,
+            'is_liked' => $isLiked,
+            'stats' => [
+                'favorites' => $favorites,
+                'likes' => $likes,
+            ],
+        ];
+    }
+}

app/Http/Controllers/Api/ArtworkNavigationController.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Resources\ArtworkResource;
+use App\Models\Artwork;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Str;
+
+class ArtworkNavigationController extends Controller
+{
+    /**
+     * GET /api/artworks/navigation/{id}
+     *
+     * Returns prev/next published artworks by the same author.
+     */
+    public function neighbors(int $id): JsonResponse
+    {
+        $artwork = Artwork::published()
+            ->select(['id', 'user_id', 'title', 'slug'])
+            ->find($id);
+
+        if (! $artwork) {
+            return response()->json([
+                'prev_id'   => null, 'next_id'   => null,
+                'prev_url'  => null, 'next_url'  => null,
+                'prev_slug' => null, 'next_slug' => null,
+            ]);
+        }
+
+        $scope = Artwork::published()
+            ->select(['id', 'title', 'slug'])
+            ->where('user_id', $artwork->user_id);
+
+        $prev = (clone $scope)->where('id', '<', $id)->orderByDesc('id')->first();
+        $next = (clone $scope)->where('id', '>', $id)->orderBy('id')->first();
+
+        // Infinite loop: wrap around when reaching the first or last artwork
+        if (! $prev) {
+            $prev = (clone $scope)->where('id', '!=', $id)->orderByDesc('id')->first();
+        }
+        if (! $next) {
+            $next = (clone $scope)->where('id', '!=', $id)->orderBy('id')->first();
+        }
+
+        $prevSlug = $prev ? (Str::slug($prev->slug ?: $prev->title) ?: (string) $prev->id) : null;
+        $nextSlug = $next ? (Str::slug($next->slug ?: $next->title) ?: (string) $next->id) : null;
+
+        return response()->json([
+            'prev_id'   => $prev?->id,
+            'next_id'   => $next?->id,
+            'prev_url'  => $prev ? url('/art/' . $prev->id . '/' . $prevSlug) : null,
+            'next_url'  => $next ? url('/art/' . $next->id . '/' . $nextSlug) : null,
+            'prev_slug' => $prevSlug,
+            'next_slug' => $nextSlug,
+        ]);
+    }
+
+    /**
+     * GET /api/artworks/{id}/page
+     *
+     * Returns full artwork resource by numeric ID for client-side (no-reload) navigation.
+     */
+    public function pageData(int $id): JsonResponse
+    {
+        $artwork = Artwork::with(['user.profile', 'categories.contentType', 'categories.parent.contentType', 'tags', 'stats'])
+            ->published()
+            ->find($id);
+
+        if (! $artwork) {
+            return response()->json(['error' => 'Not found'], 404);
+        }
+
+        $resource = (new ArtworkResource($artwork))->toArray(request());
+
+        return response()->json($resource);
+    }
+}

app/Http/Controllers/Api/ArtworkTagController.php

@@ -0,0 +1,165 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Artworks\ArtworkTagsStoreRequest;
+use App\Http\Requests\Artworks\ArtworkTagsUpdateRequest;
+use App\Models\Artwork;
+use App\Models\Tag;
+use App\Services\TagService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+use App\Jobs\AutoTagArtworkJob;
+
+final class ArtworkTagController extends Controller
+{
+    public function __construct(
+        private readonly TagService $tags,
+    ) {
+    }
+
+    public function index(int $id): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound(request()->user(), $artwork);
+
+        $queueConnection = (string) config('queue.default', 'sync');
+        $visionEnabled = (bool) config('vision.enabled', true);
+
+        $queuedCount = 0;
+        $failedCount = 0;
+
+        if (in_array($queueConnection, ['database', 'redis'], true)) {
+            try {
+                $queuedCount = (int) DB::table('jobs')
+                    ->where('payload', 'like', '%AutoTagArtworkJob%')
+                    ->where('payload', 'like', '%' . $artwork->id . '%')
+                    ->count();
+            } catch (\Throwable) {
+                $queuedCount = 0;
+            }
+
+            try {
+                $failedCount = (int) DB::table('failed_jobs')
+                    ->where('payload', 'like', '%AutoTagArtworkJob%')
+                    ->where('payload', 'like', '%' . $artwork->id . '%')
+                    ->count();
+            } catch (\Throwable) {
+                $failedCount = 0;
+            }
+        }
+
+        $triggered = false;
+        $shouldTrigger = request()->boolean('trigger', false);
+        if ($shouldTrigger && $visionEnabled && ! empty($artwork->hash) && $queuedCount === 0) {
+            AutoTagArtworkJob::dispatch((int) $artwork->id, (string) $artwork->hash);
+            $triggered = true;
+            $queuedCount = max(1, $queuedCount);
+        }
+
+        $tags = $artwork->tags()
+            ->select('tags.id', 'tags.name', 'tags.slug')
+            ->withPivot(['source', 'confidence'])
+            ->orderByDesc('artwork_tag.confidence')
+            ->get()
+            ->map(static function ($tag): array {
+                $source = (string) ($tag->pivot->source ?? 'manual');
+                return [
+                    'id' => (int) $tag->id,
+                    'name' => (string) $tag->name,
+                    'slug' => (string) $tag->slug,
+                    'source' => $source,
+                    'confidence' => (float) ($tag->pivot->confidence ?? 0),
+                    'is_ai' => $source === 'ai',
+                ];
+            })
+            ->values();
+
+        return response()->json([
+            'vision_enabled' => $visionEnabled,
+            'tags' => $tags,
+            'ai_tags' => $tags->where('is_ai', true)->values(),
+            'debug' => [
+                'queue_connection' => $queueConnection,
+                'queued_jobs' => $queuedCount,
+                'failed_jobs' => $failedCount,
+                'triggered' => $triggered,
+                'ai_tag_count' => (int) $tags->where('is_ai', true)->count(),
+                'total_tag_count' => (int) $tags->count(),
+            ],
+        ]);
+    }
+
+    public function store(int $id, ArtworkTagsStoreRequest $request): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound($request->user(), $artwork);
+
+        try {
+            $payload = $request->validated();
+            $this->tags->attachUserTags($artwork, $payload['tags']);
+
+            return response()->json(['ok' => true], Response::HTTP_CREATED);
+        } catch (\Throwable $e) {
+            $ref = (string) Str::uuid();
+            logger()->error('Artwork tag attach failed', ['ref' => $ref, 'artwork_id' => $artwork->id, 'user_id' => $request->user()?->id, 'exception' => $e]);
+            return response()->json([
+                'message' => 'Unable to update tags right now.',
+                'ref' => $ref,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    public function update(int $id, ArtworkTagsUpdateRequest $request): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound($request->user(), $artwork);
+
+        try {
+            $payload = $request->validated();
+            $this->tags->syncTags($artwork, $payload['tags']);
+            return response()->json(['ok' => true]);
+        } catch (\Throwable $e) {
+            $ref = (string) Str::uuid();
+            logger()->error('Artwork tag sync failed', ['ref' => $ref, 'artwork_id' => $artwork->id, 'user_id' => $request->user()?->id, 'exception' => $e]);
+            return response()->json([
+                'message' => 'Unable to update tags right now.',
+                'ref' => $ref,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    public function destroy(int $id, Tag $tag): JsonResponse
+    {
+        $artwork = Artwork::query()->findOrFail($id);
+        $this->authorizeOrNotFound(request()->user(), $artwork);
+
+        try {
+            $this->tags->detachTags($artwork, [$tag->id]);
+            return response()->json(['ok' => true]);
+        } catch (\Throwable $e) {
+            $ref = (string) Str::uuid();
+            logger()->error('Artwork tag detach failed', ['ref' => $ref, 'artwork_id' => $artwork->id, 'tag_id' => $tag->id, 'user_id' => request()->user()?->id, 'exception' => $e]);
+            return response()->json([
+                'message' => 'Unable to update tags right now.',
+                'ref' => $ref,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    private function authorizeOrNotFound($user, Artwork $artwork): void
+    {
+        if (! $user) {
+            abort(404);
+        }
+
+        if (! $user->can('updateTags', $artwork)) {
+            abort(404);
+        }
+    }
+}

app/Http/Controllers/Api/ArtworkViewController.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Services\ArtworkStatsService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * POST /api/art/{id}/view
+ *
+ * Fire-and-forget view tracker.
+ *
+ * Deduplication strategy (layered):
+ *   1. Session key (`art_viewed.{id}`) — prevents double-counts within the
+ *      same browser session (survives page reloads).
+ *   2. Route throttle (5 per 10 minutes per IP+artwork) — catches bots that
+ *      don't send session cookies.
+ *
+ * The frontend should additionally guard with sessionStorage so it only
+ * calls this endpoint once per page load.
+ */
+final class ArtworkViewController extends Controller
+{
+    public function __construct(private readonly ArtworkStatsService $stats) {}
+
+    public function __invoke(Request $request, int $id): JsonResponse
+    {
+        $artwork = Artwork::public()
+            ->published()
+            ->where('id', $id)
+            ->first();
+
+        if (! $artwork) {
+            return response()->json(['error' => 'Not found'], 404);
+        }
+
+        $sessionKey = 'art_viewed.' . $id;
+
+        // Already counted this session — return early without touching the DB.
+        if ($request->hasSession() && $request->session()->has($sessionKey)) {
+            return response()->json(['ok' => true, 'counted' => false]);
+        }
+
+        // Write persistent event log (auth user_id or null for guests).
+        $this->stats->logViewEvent((int) $artwork->id, $request->user()?->id);
+
+        // Defer to Redis when available, fall back to direct DB increment.
+        $this->stats->incrementViews((int) $artwork->id, 1, defer: true);
+
+        // Mark this session so the artwork is not counted again.
+        if ($request->hasSession()) {
+            $request->session()->put($sessionKey, true);
+        }
+
+        return response()->json(['ok' => true, 'counted' => true]);
+    }
+}

app/Http/Controllers/Api/BrowseController.php

@@ -23,9 +23,14 @@ class BrowseController extends Controller
      */
     public function index(Request $request)
     {
-        $perPage = min(max((int) $request->get('per_page', 24), 1), 100);
+        $perPage = $this->resolvePerPage($request);
+        $sort = (string) $request->get('sort', 'latest');
 
-        $paginator = $this->service->browsePublicArtworks($perPage);
+        $paginator = $this->service->browsePublicArtworks($perPage, $sort);
+        $paginator->appends([
+            'limit' => $perPage,
+            'sort' => $sort,
+        ]);
 
         return ArtworkListResource::collection($paginator);
     }
@@ -36,14 +41,20 @@ class BrowseController extends Controller
      */
     public function byContentType(Request $request, string $contentTypeSlug)
     {
-        $perPage = min(max((int) $request->get('per_page', 24), 1), 100);
+        $perPage = $this->resolvePerPage($request);
+        $sort = (string) $request->get('sort', 'latest');
 
         try {
-            $paginator = $this->service->getArtworksByContentType($contentTypeSlug, $perPage);
+            $paginator = $this->service->getArtworksByContentType($contentTypeSlug, $perPage, $sort);
         } catch (ModelNotFoundException $e) {
             abort(404);
         }
 
+        $paginator->appends([
+            'limit' => $perPage,
+            'sort' => $sort,
+        ]);
+
         if ($paginator->count() === 0) {
             return response()->json(['message' => 'Gone'], 410);
         }
@@ -57,22 +68,38 @@ class BrowseController extends Controller
      */
     public function byCategoryPath(Request $request, string $contentTypeSlug, string $categoryPath)
     {
-        $perPage = min(max((int) $request->get('per_page', 24), 1), 100);
+        $perPage = $this->resolvePerPage($request);
+        $sort = (string) $request->get('sort', 'latest');
 
         $slugs = array_merge([
             strtolower($contentTypeSlug),
         ], array_values(array_filter(explode('/', trim($categoryPath, '/')))));
 
         try {
-            $paginator = $this->service->getArtworksByCategoryPath($slugs, $perPage);
+            $paginator = $this->service->getArtworksByCategoryPath($slugs, $perPage, $sort);
         } catch (ModelNotFoundException $e) {
             abort(404);
         }
 
+        $paginator->appends([
+            'limit' => $perPage,
+            'sort' => $sort,
+        ]);
+
         if ($paginator->count() === 0) {
             return response()->json(['message' => 'Gone'], 410);
         }
 
         return ArtworkListResource::collection($paginator);
     }
+
+    private function resolvePerPage(Request $request): int
+    {
+        $limit = (int) $request->query('limit', 0);
+        $perPage = (int) $request->query('per_page', 0);
+
+        $value = $limit > 0 ? $limit : ($perPage > 0 ? $perPage : 24);
+
+        return min(max($value, 1), 100);
+    }
 }

app/Http/Controllers/Api/DiscoveryEventController.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Jobs\IngestUserDiscoveryEventJob;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+
+final class DiscoveryEventController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'event_id' => ['nullable', 'uuid'],
+            'event_type' => ['required', 'string', 'in:view,click,favorite,download'],
+            'artwork_id' => ['required', 'integer', 'exists:artworks,id'],
+            'occurred_at' => ['nullable', 'date'],
+            'algo_version' => ['nullable', 'string', 'max:64'],
+            'meta' => ['nullable', 'array'],
+        ]);
+
+        $eventId = (string) ($payload['event_id'] ?? (string) Str::uuid());
+        $algoVersion = (string) ($payload['algo_version'] ?? config('discovery.algo_version', 'clip-cosine-v1'));
+        $occurredAt = isset($payload['occurred_at'])
+            ? (string) $payload['occurred_at']
+            : now()->toIso8601String();
+
+        IngestUserDiscoveryEventJob::dispatch(
+            eventId: $eventId,
+            userId: (int) $request->user()->id,
+            artworkId: (int) $payload['artwork_id'],
+            eventType: (string) $payload['event_type'],
+            algoVersion: $algoVersion,
+            occurredAt: $occurredAt,
+            meta: (array) ($payload['meta'] ?? [])
+        )->onQueue((string) config('discovery.queue', 'default'));
+
+        return response()->json([
+            'queued' => true,
+            'event_id' => $eventId,
+            'algo_version' => $algoVersion,
+        ], Response::HTTP_ACCEPTED);
+    }
+}

app/Http/Controllers/Api/FeedAnalyticsController.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class FeedAnalyticsController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'event_type' => ['required', 'string', 'in:feed_impression,feed_click'],
+            'artwork_id' => ['required', 'integer', 'exists:artworks,id'],
+            'position' => ['nullable', 'integer', 'min:1', 'max:500'],
+            'algo_version' => ['required', 'string', 'max:64'],
+            'source' => ['required', 'string', 'in:personalized,cold_start,fallback'],
+            'dwell_seconds' => ['nullable', 'integer', 'min:0', 'max:86400'],
+            'occurred_at' => ['nullable', 'date'],
+        ]);
+
+        $occurredAt = isset($payload['occurred_at']) ? now()->parse((string) $payload['occurred_at']) : now();
+
+        DB::table('feed_events')->insert([
+            'event_date' => $occurredAt->toDateString(),
+            'event_type' => (string) $payload['event_type'],
+            'user_id' => (int) $request->user()->id,
+            'artwork_id' => (int) $payload['artwork_id'],
+            'position' => isset($payload['position']) ? (int) $payload['position'] : null,
+            'algo_version' => (string) $payload['algo_version'],
+            'source' => (string) $payload['source'],
+            'dwell_seconds' => isset($payload['dwell_seconds']) ? (int) $payload['dwell_seconds'] : null,
+            'occurred_at' => $occurredAt,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        return response()->json(['success' => true], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/FeedController.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\Recommendations\PersonalizedFeedService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class FeedController extends Controller
+{
+    public function __construct(private readonly PersonalizedFeedService $feedService)
+    {
+    }
+
+    public function index(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'limit' => ['nullable', 'integer', 'min:1', 'max:50'],
+            'cursor' => ['nullable', 'string', 'max:512'],
+            'algo_version' => ['nullable', 'string', 'max:64'],
+        ]);
+
+        $result = $this->feedService->getFeed(
+            userId: (int) $request->user()->id,
+            limit: isset($payload['limit']) ? (int) $payload['limit'] : 24,
+            cursor: isset($payload['cursor']) ? (string) $payload['cursor'] : null,
+            algoVersion: isset($payload['algo_version']) ? (string) $payload['algo_version'] : null
+        );
+
+        return response()->json($result);
+    }
+}

app/Http/Controllers/Api/FollowController.php

@@ -0,0 +1,137 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use App\Services\FollowService;
+use App\Support\AvatarUrl;
+use App\Support\UsernamePolicy;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * API endpoints for the follow system.
+ *
+ * POST   /api/user/{username}/follow      → follow a user
+ * DELETE /api/user/{username}/follow      → unfollow a user
+ * GET    /api/user/{username}/followers   → paginated followers list
+ * GET    /api/user/{username}/following   → paginated following list
+ */
+final class FollowController extends Controller
+{
+    public function __construct(private readonly FollowService $followService) {}
+
+    // ─── POST /api/user/{username}/follow ────────────────────────────────────
+
+    public function follow(Request $request, string $username): JsonResponse
+    {
+        $target = $this->resolveUser($username);
+        $actor  = Auth::user();
+
+        if ($actor->id === $target->id) {
+            return response()->json(['error' => 'Cannot follow yourself.'], 422);
+        }
+
+        try {
+            $this->followService->follow((int) $actor->id, (int) $target->id);
+        } catch (\InvalidArgumentException $e) {
+            return response()->json(['error' => $e->getMessage()], 422);
+        }
+
+        return response()->json([
+            'following'       => true,
+            'followers_count' => $this->followService->followersCount((int) $target->id),
+        ]);
+    }
+
+    // ─── DELETE /api/user/{username}/follow ──────────────────────────────────
+
+    public function unfollow(Request $request, string $username): JsonResponse
+    {
+        $target = $this->resolveUser($username);
+        $actor  = Auth::user();
+
+        $this->followService->unfollow((int) $actor->id, (int) $target->id);
+
+        return response()->json([
+            'following'       => false,
+            'followers_count' => $this->followService->followersCount((int) $target->id),
+        ]);
+    }
+
+    // ─── GET /api/user/{username}/followers ──────────────────────────────────
+
+    public function followers(Request $request, string $username): JsonResponse
+    {
+        $target  = $this->resolveUser($username);
+        $perPage = min((int) $request->query('per_page', 24), 100);
+
+        $rows = DB::table('user_followers as uf')
+            ->join('users as u', 'u.id', '=', 'uf.follower_id')
+            ->leftJoin('user_profiles as up', 'up.user_id', '=', 'u.id')
+            ->where('uf.user_id', $target->id)
+            ->whereNull('u.deleted_at')
+            ->orderByDesc('uf.created_at')
+            ->select([
+                'u.id', 'u.username', 'u.name',
+                'up.avatar_hash',
+                'uf.created_at as followed_at',
+            ])
+            ->paginate($perPage)
+            ->through(fn ($row) => [
+                'id'          => $row->id,
+                'username'    => $row->username,
+                'display_name'=> $row->username ?? $row->name,
+                'avatar_url'  => AvatarUrl::forUser((int) $row->id, $row->avatar_hash, 50),
+                'profile_url' => '/@' . strtolower((string) ($row->username ?? $row->id)),
+                'followed_at' => $row->followed_at,
+            ]);
+
+        return response()->json($rows);
+    }
+
+    // ─── GET /api/user/{username}/following ──────────────────────────────────
+
+    public function following(Request $request, string $username): JsonResponse
+    {
+        $target  = $this->resolveUser($username);
+        $perPage = min((int) $request->query('per_page', 24), 100);
+
+        $rows = DB::table('user_followers as uf')
+            ->join('users as u', 'u.id', '=', 'uf.user_id')
+            ->leftJoin('user_profiles as up', 'up.user_id', '=', 'u.id')
+            ->where('uf.follower_id', $target->id)
+            ->whereNull('u.deleted_at')
+            ->orderByDesc('uf.created_at')
+            ->select([
+                'u.id', 'u.username', 'u.name',
+                'up.avatar_hash',
+                'uf.created_at as followed_at',
+            ])
+            ->paginate($perPage)
+            ->through(fn ($row) => [
+                'id'          => $row->id,
+                'username'    => $row->username,
+                'display_name'=> $row->username ?? $row->name,
+                'avatar_url'  => AvatarUrl::forUser((int) $row->id, $row->avatar_hash, 50),
+                'profile_url' => '/@' . strtolower((string) ($row->username ?? $row->id)),
+                'followed_at' => $row->followed_at,
+            ]);
+
+        return response()->json($rows);
+    }
+
+    // ─── Private helpers ─────────────────────────────────────────────────────
+
+    private function resolveUser(string $username): User
+    {
+        $normalized = UsernamePolicy::normalize($username);
+
+        return User::query()
+            ->whereRaw('LOWER(username) = ?', [$normalized])
+            ->firstOrFail();
+    }
+}

app/Http/Controllers/Api/LatestCommentsApiController.php

@@ -0,0 +1,113 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Models\ArtworkComment;
+use App\Support\AvatarUrl;
+use App\Services\ThumbnailPresenter;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Str;
+use Carbon\Carbon;
+
+class LatestCommentsApiController extends Controller
+{
+    private const PER_PAGE = 20;
+
+    public function index(Request $request): JsonResponse
+    {
+        $type = $request->query('type', 'all');
+
+        // Validate filter type
+        if (! in_array($type, ['all', 'following', 'mine'], true)) {
+            $type = 'all';
+        }
+
+        // 'mine' and 'following' require auth
+        if (in_array($type, ['mine', 'following'], true) && ! $request->user()) {
+            return response()->json(['error' => 'Unauthenticated'], 401);
+        }
+
+        $query = ArtworkComment::with(['user', 'user.profile', 'artwork'])
+            ->whereHas('artwork', function ($q) {
+                $q->public()->published()->whereNull('deleted_at');
+            })
+            ->orderByDesc('artwork_comments.created_at');
+
+        switch ($type) {
+            case 'mine':
+                $query->where('artwork_comments.user_id', $request->user()->id);
+                break;
+
+            case 'following':
+                $followingIds = $request->user()
+                    ->following()
+                    ->pluck('users.id');
+                $query->whereIn('artwork_comments.user_id', $followingIds);
+                break;
+
+            default:
+                // 'all' — cache the first page only
+                if ((int) $request->query('page', 1) === 1) {
+                    $cacheKey = 'comments.latest.all.page1';
+                    $ttl      = 120; // 2 minutes
+
+                    $paginator = Cache::remember($cacheKey, $ttl, fn () => $query->paginate(self::PER_PAGE));
+                } else {
+                    $paginator = $query->paginate(self::PER_PAGE);
+                }
+                break;
+        }
+
+        if (! isset($paginator)) {
+            $paginator = $query->paginate(self::PER_PAGE);
+        }
+
+        $items = $paginator->getCollection()->map(function (ArtworkComment $c) {
+            $art  = $c->artwork;
+            $user = $c->user;
+
+            $present = $art ? ThumbnailPresenter::present($art, 'md') : null;
+            $thumb   = $present ? ($present['url'] ?? null) : null;
+
+            $userId     = (int) ($c->user_id ?? 0);
+            $avatarHash = $user?->profile?->avatar_hash ?? null;
+
+            return [
+                'comment_id'   => $c->getKey(),
+                'comment_text' => e(strip_tags($c->content ?? '')),
+                'created_at'   => $c->created_at?->toIso8601String(),
+                'time_ago'     => $c->created_at ? Carbon::parse($c->created_at)->diffForHumans() : null,
+
+                'commenter' => [
+                    'id'          => $userId,
+                    'username'    => $user?->username ?? null,
+                    'display'     => $user?->username ?? $user?->name ?? 'User',
+                    'profile_url' => $user?->username ? '/@' . $user->username : '/profile/' . $userId,
+                    'avatar_url'  => AvatarUrl::forUser($userId, $avatarHash, 64),
+                ],
+
+                'artwork' => $art ? [
+                    'id'    => $art->id,
+                    'title' => $art->title,
+                    'slug'  => $art->slug ?? Str::slug($art->title ?? ''),
+                    'url'   => '/art/' . $art->id . '/' . ($art->slug ?? Str::slug($art->title ?? '')),
+                    'thumb' => $thumb,
+                ] : null,
+            ];
+        });
+
+        return response()->json([
+            'data' => $items,
+            'meta' => [
+                'current_page' => $paginator->currentPage(),
+                'last_page'    => $paginator->lastPage(),
+                'per_page'     => $paginator->perPage(),
+                'total'        => $paginator->total(),
+                'has_more'     => $paginator->hasMorePages(),
+            ],
+        ]);
+    }
+}

app/Http/Controllers/Api/Messaging/AttachmentController.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Controllers\Api\Messaging;
+
+use App\Http\Controllers\Controller;
+use App\Models\MessageAttachment;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+class AttachmentController extends Controller
+{
+    public function show(Request $request, int $id)
+    {
+        $attachment = MessageAttachment::query()
+            ->with('message:id,conversation_id')
+            ->findOrFail($id);
+
+        $conversationId = (int) ($attachment->message?->conversation_id ?? 0);
+        abort_if($conversationId <= 0, 404, 'Attachment not available.');
+
+        $authorized = \App\Models\ConversationParticipant::query()
+            ->where('conversation_id', $conversationId)
+            ->where('user_id', $request->user()->id)
+            ->whereNull('left_at')
+            ->exists();
+
+        abort_unless($authorized, 403, 'You are not allowed to access this attachment.');
+
+        $diskName = (string) config('messaging.attachments.disk', 'local');
+        $disk = Storage::disk($diskName);
+
+        return new StreamedResponse(function () use ($disk, $attachment): void {
+            echo $disk->get($attachment->storage_path);
+        }, 200, [
+            'Content-Type' => $attachment->mime,
+            'Content-Disposition' => 'inline; filename="' . addslashes($attachment->original_name) . '"',
+            'Content-Length' => (string) $attachment->size_bytes,
+        ]);
+    }
+}

app/Http/Controllers/Api/Messaging/ConversationController.php

@@ -0,0 +1,466 @@
+<?php
+
+namespace App\Http\Controllers\Api\Messaging;
+
+use App\Http\Controllers\Controller;
+use App\Models\Conversation;
+use App\Models\ConversationParticipant;
+use App\Models\Message;
+use App\Models\User;
+use App\Services\Messaging\MessageNotificationService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+class ConversationController extends Controller
+{
+    // ── GET /api/messages/conversations ─────────────────────────────────────
+
+    public function index(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        $page = max(1, (int) $request->integer('page', 1));
+        $cacheVersion = (int) Cache::get($this->cacheVersionKey($user->id), 1);
+        $cacheKey = $this->conversationListCacheKey($user->id, $page, $cacheVersion);
+
+        $conversations = Cache::remember($cacheKey, now()->addSeconds(20), function () use ($user, $page) {
+            return Conversation::query()
+                ->select('conversations.*')
+                ->join('conversation_participants as cp_me', function ($join) use ($user) {
+                    $join->on('cp_me.conversation_id', '=', 'conversations.id')
+                        ->where('cp_me.user_id', '=', $user->id)
+                        ->whereNull('cp_me.left_at');
+                })
+                ->addSelect([
+                    'unread_count' => Message::query()
+                        ->selectRaw('count(*)')
+                        ->whereColumn('messages.conversation_id', 'conversations.id')
+                        ->where('messages.sender_id', '!=', $user->id)
+                        ->whereNull('messages.deleted_at')
+                        ->where(function ($query) {
+                            $query->whereNull('cp_me.last_read_at')
+                                ->orWhereColumn('messages.created_at', '>', 'cp_me.last_read_at');
+                        }),
+                ])
+                ->with([
+                    'allParticipants' => fn ($q) => $q->whereNull('left_at')->with(['user:id,username']),
+                    'latestMessage.sender:id,username',
+                ])
+                ->orderByDesc('cp_me.is_pinned')
+                ->orderByDesc('cp_me.pinned_at')
+                ->orderByDesc('last_message_at')
+                ->orderByDesc('conversations.id')
+                ->paginate(20, ['conversations.*'], 'page', $page);
+        });
+
+        $conversations->through(function ($conv) use ($user) {
+            $conv->my_participant = $conv->allParticipants
+                ->firstWhere('user_id', $user->id);
+            return $conv;
+        });
+
+        return response()->json($conversations);
+    }
+
+    // ── GET /api/messages/conversation/{id} ─────────────────────────────────
+
+    public function show(Request $request, int $id): JsonResponse
+    {
+        $conv = $this->findAuthorized($request, $id);
+
+        $conv->load([
+            'allParticipants.user:id,username',
+            'creator:id,username',
+        ]);
+
+        return response()->json($conv);
+    }
+
+    // ── POST /api/messages/conversation ─────────────────────────────────────
+
+    public function store(Request $request): JsonResponse
+    {
+        $user = $request->user();
+
+        $data = $request->validate([
+            'type'             => 'required|in:direct,group',
+            'recipient_id'     => 'required_if:type,direct|integer|exists:users,id',
+            'participant_ids'  => 'required_if:type,group|array|min:2',
+            'participant_ids.*'=> 'integer|exists:users,id',
+            'title'            => 'required_if:type,group|nullable|string|max:120',
+            'body'             => 'required|string|max:5000',
+        ]);
+
+        if ($data['type'] === 'direct') {
+            return $this->createDirect($request, $user, $data);
+        }
+
+        return $this->createGroup($request, $user, $data);
+    }
+
+    // ── POST /api/messages/{conversation_id}/read ────────────────────────────
+
+    public function markRead(Request $request, int $id): JsonResponse
+    {
+        $participant = $this->participantRecord($request, $id);
+        $participant->update(['last_read_at' => now()]);
+        $this->touchConversationCachesForUsers([$request->user()->id]);
+
+        return response()->json(['ok' => true]);
+    }
+
+    // ── POST /api/messages/{conversation_id}/archive ─────────────────────────
+
+    public function archive(Request $request, int $id): JsonResponse
+    {
+        $participant = $this->participantRecord($request, $id);
+        $participant->update(['is_archived' => ! $participant->is_archived]);
+        $this->touchConversationCachesForUsers([$request->user()->id]);
+
+        return response()->json(['is_archived' => $participant->is_archived]);
+    }
+
+    // ── POST /api/messages/{conversation_id}/mute ────────────────────────────
+
+    public function mute(Request $request, int $id): JsonResponse
+    {
+        $participant = $this->participantRecord($request, $id);
+        $participant->update(['is_muted' => ! $participant->is_muted]);
+        $this->touchConversationCachesForUsers([$request->user()->id]);
+
+        return response()->json(['is_muted' => $participant->is_muted]);
+    }
+
+    public function pin(Request $request, int $id): JsonResponse
+    {
+        $participant = $this->participantRecord($request, $id);
+        $participant->update(['is_pinned' => true, 'pinned_at' => now()]);
+        $this->touchConversationCachesForUsers([$request->user()->id]);
+
+        return response()->json(['is_pinned' => true]);
+    }
+
+    public function unpin(Request $request, int $id): JsonResponse
+    {
+        $participant = $this->participantRecord($request, $id);
+        $participant->update(['is_pinned' => false, 'pinned_at' => null]);
+        $this->touchConversationCachesForUsers([$request->user()->id]);
+
+        return response()->json(['is_pinned' => false]);
+    }
+
+    // ── DELETE /api/messages/{conversation_id}/leave ─────────────────────────
+
+    public function leave(Request $request, int $id): JsonResponse
+    {
+        $conv        = $this->findAuthorized($request, $id);
+        $participant = $this->participantRecord($request, $id);
+        $participantUserIds = ConversationParticipant::where('conversation_id', $id)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+
+        if ($conv->isGroup()) {
+            // Last admin protection
+            $adminCount = ConversationParticipant::where('conversation_id', $id)
+                ->where('role', 'admin')
+                ->whereNull('left_at')
+                ->count();
+
+            if ($adminCount === 1 && $participant->role === 'admin') {
+                $otherMember = ConversationParticipant::where('conversation_id', $id)
+                    ->where('user_id', '!=', $request->user()->id)
+                    ->whereNull('left_at')
+                    ->first();
+
+                if ($otherMember) {
+                    $otherMember->update(['role' => 'admin']);
+                }
+            }
+        }
+
+        $participant->update(['left_at' => now()]);
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        return response()->json(['ok' => true]);
+    }
+
+    // ── POST /api/messages/{conversation_id}/add-user ────────────────────────
+
+    public function addUser(Request $request, int $id): JsonResponse
+    {
+        $conv = $this->findAuthorized($request, $id);
+        $this->requireAdmin($request, $id);
+        $participantUserIds = ConversationParticipant::where('conversation_id', $id)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+
+        $data = $request->validate([
+            'user_id' => 'required|integer|exists:users,id',
+        ]);
+
+        $existing = ConversationParticipant::where('conversation_id', $id)
+            ->where('user_id', $data['user_id'])
+            ->first();
+
+        if ($existing) {
+            if ($existing->left_at) {
+                $existing->update(['left_at' => null, 'joined_at' => now()]);
+            }
+        } else {
+            ConversationParticipant::create([
+                'conversation_id' => $id,
+                'user_id'         => $data['user_id'],
+                'role'            => 'member',
+                'joined_at'       => now(),
+            ]);
+        }
+
+        $participantUserIds[] = (int) $data['user_id'];
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        return response()->json(['ok' => true]);
+    }
+
+    // ── DELETE /api/messages/{conversation_id}/remove-user ───────────────────
+
+    public function removeUser(Request $request, int $id): JsonResponse
+    {
+        $this->requireAdmin($request, $id);
+
+        $data = $request->validate([
+            'user_id' => 'required|integer',
+        ]);
+
+        // Cannot remove the conversation creator
+        $conv = Conversation::findOrFail($id);
+        abort_if($conv->created_by === (int) $data['user_id'], 403, 'Cannot remove the conversation creator.');
+
+        $targetParticipant = ConversationParticipant::where('conversation_id', $id)
+            ->where('user_id', $data['user_id'])
+            ->whereNull('left_at')
+            ->first();
+
+        if ($targetParticipant && $targetParticipant->role === 'admin') {
+            $adminCount = ConversationParticipant::where('conversation_id', $id)
+                ->where('role', 'admin')
+                ->whereNull('left_at')
+                ->count();
+
+            abort_if($adminCount <= 1, 422, 'Cannot remove the last admin from this conversation.');
+        }
+
+        $participantUserIds = ConversationParticipant::where('conversation_id', $id)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+
+        ConversationParticipant::where('conversation_id', $id)
+            ->where('user_id', $data['user_id'])
+            ->whereNull('left_at')
+            ->update(['left_at' => now()]);
+
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        return response()->json(['ok' => true]);
+    }
+
+    // ── POST /api/messages/{conversation_id}/rename ──────────────────────────
+
+    public function rename(Request $request, int $id): JsonResponse
+    {
+        $conv = $this->findAuthorized($request, $id);
+        abort_unless($conv->isGroup(), 422, 'Only group conversations can be renamed.');
+        $this->requireAdmin($request, $id);
+
+        $data = $request->validate(['title' => 'required|string|max:120']);
+        $conv->update(['title' => $data['title']]);
+        $participantUserIds = ConversationParticipant::where('conversation_id', $id)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        return response()->json(['title' => $conv->title]);
+    }
+
+    // ── Private helpers ──────────────────────────────────────────────────────
+
+    private function createDirect(Request $request, User $user, array $data): JsonResponse
+    {
+        $recipient = User::findOrFail($data['recipient_id']);
+
+        abort_if($recipient->id === $user->id, 422, 'You cannot message yourself.');
+
+        if (! $recipient->allowsMessagesFrom($user)) {
+            abort(403, 'This user does not accept messages from you.');
+        }
+
+        $this->assertNotBlockedBetween($user, $recipient);
+
+        // Reuse existing conversation if one exists
+        $conv = Conversation::findDirect($user->id, $recipient->id);
+
+        if (! $conv) {
+            $conv = DB::transaction(function () use ($user, $recipient) {
+                $conv = Conversation::create([
+                    'type'       => 'direct',
+                    'created_by' => $user->id,
+                ]);
+
+                ConversationParticipant::insert([
+                    ['conversation_id' => $conv->id, 'user_id' => $user->id,      'role' => 'admin',  'joined_at' => now()],
+                    ['conversation_id' => $conv->id, 'user_id' => $recipient->id, 'role' => 'member', 'joined_at' => now()],
+                ]);
+
+                return $conv;
+            });
+        }
+
+        // Insert first / next message
+        $message = $conv->messages()->create([
+            'sender_id' => $user->id,
+            'body'      => $data['body'],
+        ]);
+
+        $conv->update(['last_message_at' => $message->created_at]);
+        app(MessageNotificationService::class)->notifyNewMessage($conv, $message, $user);
+        $this->touchConversationCachesForUsers([$user->id, $recipient->id]);
+
+        return response()->json($conv->load('allParticipants.user:id,username'), 201);
+    }
+
+    private function createGroup(Request $request, User $user, array $data): JsonResponse
+    {
+        $participantIds = array_unique(array_merge([$user->id], $data['participant_ids']));
+
+        $conv = DB::transaction(function () use ($user, $data, $participantIds) {
+            $conv = Conversation::create([
+                'type'       => 'group',
+                'title'      => $data['title'],
+                'created_by' => $user->id,
+            ]);
+
+            $rows = array_map(fn ($uid) => [
+                'conversation_id' => $conv->id,
+                'user_id'         => $uid,
+                'role'            => $uid === $user->id ? 'admin' : 'member',
+                'joined_at'       => now(),
+            ], $participantIds);
+
+            ConversationParticipant::insert($rows);
+
+            $message = $conv->messages()->create([
+                'sender_id' => $user->id,
+                'body'      => $data['body'],
+            ]);
+
+            $conv->update(['last_message_at' => $message->created_at]);
+
+            return [$conv, $message];
+        });
+
+        [$conversation, $message] = $conv;
+        app(MessageNotificationService::class)->notifyNewMessage($conversation, $message, $user);
+        $this->touchConversationCachesForUsers($participantIds);
+
+        return response()->json($conversation->load('allParticipants.user:id,username'), 201);
+    }
+
+    private function findAuthorized(Request $request, int $id): Conversation
+    {
+        $conv = Conversation::findOrFail($id);
+        $this->assertParticipant($request, $id);
+        return $conv;
+    }
+
+    private function participantRecord(Request $request, int $conversationId): ConversationParticipant
+    {
+        return ConversationParticipant::where('conversation_id', $conversationId)
+            ->where('user_id', $request->user()->id)
+            ->whereNull('left_at')
+            ->firstOrFail();
+    }
+
+    private function assertParticipant(Request $request, int $id): void
+    {
+        abort_unless(
+            ConversationParticipant::where('conversation_id', $id)
+                ->where('user_id', $request->user()->id)
+                ->whereNull('left_at')
+                ->exists(),
+            403,
+            'You are not a participant of this conversation.'
+        );
+    }
+
+    private function requireAdmin(Request $request, int $id): void
+    {
+        abort_unless(
+            ConversationParticipant::where('conversation_id', $id)
+                ->where('user_id', $request->user()->id)
+                ->where('role', 'admin')
+                ->whereNull('left_at')
+                ->exists(),
+            403,
+            'Only admins can perform this action.'
+        );
+    }
+
+    private function touchConversationCachesForUsers(array $userIds): void
+    {
+        foreach (array_unique($userIds) as $userId) {
+            if (! $userId) {
+                continue;
+            }
+
+            $versionKey = $this->cacheVersionKey((int) $userId);
+            Cache::add($versionKey, 1, now()->addDay());
+            Cache::increment($versionKey);
+        }
+    }
+
+    private function cacheVersionKey(int $userId): string
+    {
+        return "messages:conversations:version:{$userId}";
+    }
+
+    private function conversationListCacheKey(int $userId, int $page, int $version): string
+    {
+        return "messages:conversations:user:{$userId}:page:{$page}:v:{$version}";
+    }
+
+    private function assertNotBlockedBetween(User $sender, User $recipient): void
+    {
+        if (! Schema::hasTable('user_blocks')) {
+            return;
+        }
+
+        $blocked = false;
+
+        if (Schema::hasColumns('user_blocks', ['user_id', 'blocked_user_id'])) {
+            $blocked = DB::table('user_blocks')
+                ->where(function ($q) use ($sender, $recipient) {
+                    $q->where('user_id', $sender->id)->where('blocked_user_id', $recipient->id);
+                })
+                ->orWhere(function ($q) use ($sender, $recipient) {
+                    $q->where('user_id', $recipient->id)->where('blocked_user_id', $sender->id);
+                })
+                ->exists();
+        } elseif (Schema::hasColumns('user_blocks', ['blocker_id', 'blocked_id'])) {
+            $blocked = DB::table('user_blocks')
+                ->where(function ($q) use ($sender, $recipient) {
+                    $q->where('blocker_id', $sender->id)->where('blocked_id', $recipient->id);
+                })
+                ->orWhere(function ($q) use ($sender, $recipient) {
+                    $q->where('blocker_id', $recipient->id)->where('blocked_id', $sender->id);
+                })
+                ->exists();
+        }
+
+        abort_if($blocked, 403, 'Messaging is not available between these users.');
+    }
+}

app/Http/Controllers/Api/Messaging/MessageController.php

@@ -0,0 +1,351 @@
+<?php
+
+namespace App\Http\Controllers\Api\Messaging;
+
+use App\Events\MessageSent;
+use App\Http\Controllers\Controller;
+use App\Models\Conversation;
+use App\Models\ConversationParticipant;
+use App\Models\Message;
+use App\Models\MessageAttachment;
+use App\Models\MessageReaction;
+use App\Services\Messaging\MessageSearchIndexer;
+use App\Services\Messaging\MessageNotificationService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Storage;
+
+class MessageController extends Controller
+{
+    private const PAGE_SIZE = 30;
+
+    // ── GET /api/messages/{conversation_id} ──────────────────────────────────
+
+    public function index(Request $request, int $conversationId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+        $cursor = $request->integer('cursor');
+
+        $query = Message::withTrashed()
+            ->where('conversation_id', $conversationId)
+            ->with(['sender:id,username', 'reactions', 'attachments'])
+            ->orderByDesc('created_at')
+            ->orderByDesc('id');
+
+        if ($cursor) {
+            $query->where('id', '<', $cursor);
+        }
+
+        $chunk = $query->limit(self::PAGE_SIZE + 1)->get();
+        $hasMore = $chunk->count() > self::PAGE_SIZE;
+        $messages = $chunk->take(self::PAGE_SIZE)->reverse()->values();
+        $nextCursor = $hasMore && $messages->isNotEmpty() ? (int) $messages->first()->id : null;
+
+        return response()->json([
+            'data' => $messages,
+            'next_cursor' => $nextCursor,
+        ]);
+    }
+
+    // ── POST /api/messages/{conversation_id} ─────────────────────────────────
+
+    public function store(Request $request, int $conversationId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+
+        $data = $request->validate([
+            'body' => 'nullable|string|max:5000',
+            'attachments' => 'sometimes|array|max:5',
+            'attachments.*' => 'file|max:25600',
+        ]);
+
+        $body = trim((string) ($data['body'] ?? ''));
+        $files = $request->file('attachments', []);
+        abort_if($body === '' && empty($files), 422, 'Message body or attachment is required.');
+
+        $message = Message::create([
+            'conversation_id' => $conversationId,
+            'sender_id'       => $request->user()->id,
+            'body'            => $body,
+        ]);
+
+        foreach ($files as $file) {
+            if ($file instanceof UploadedFile) {
+                $this->storeAttachment($file, $message, (int) $request->user()->id);
+            }
+        }
+
+        Conversation::where('id', $conversationId)
+            ->update(['last_message_at' => $message->created_at]);
+
+        $conversation = Conversation::findOrFail($conversationId);
+        app(MessageNotificationService::class)->notifyNewMessage($conversation, $message, $request->user());
+        app(MessageSearchIndexer::class)->indexMessage($message);
+        event(new MessageSent($conversationId, $message->id, $request->user()->id));
+
+        $participantUserIds = ConversationParticipant::where('conversation_id', $conversationId)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        $message->load(['sender:id,username', 'attachments']);
+
+        return response()->json($message, 201);
+    }
+
+    // ── POST /api/messages/{conversation_id}/react ───────────────────────────
+
+    public function react(Request $request, int $conversationId, int $messageId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+
+        $data = $request->validate(['reaction' => 'required|string|max:32']);
+        $this->assertAllowedReaction($data['reaction']);
+
+        $existing = MessageReaction::where([
+            'message_id' => $messageId,
+            'user_id'    => $request->user()->id,
+            'reaction'   => $data['reaction'],
+        ])->first();
+
+        if ($existing) {
+            $existing->delete();
+        } else {
+            MessageReaction::create([
+                'message_id' => $messageId,
+                'user_id'    => $request->user()->id,
+                'reaction'   => $data['reaction'],
+            ]);
+        }
+
+        return response()->json($this->reactionSummary($messageId, (int) $request->user()->id));
+    }
+
+    // ── DELETE /api/messages/{conversation_id}/react ─────────────────────────
+
+    public function unreact(Request $request, int $conversationId, int $messageId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+
+        $data = $request->validate(['reaction' => 'required|string|max:32']);
+        $this->assertAllowedReaction($data['reaction']);
+
+        MessageReaction::where([
+            'message_id' => $messageId,
+            'user_id'    => $request->user()->id,
+            'reaction'   => $data['reaction'],
+        ])->delete();
+
+        return response()->json($this->reactionSummary($messageId, (int) $request->user()->id));
+    }
+
+    public function reactByMessage(Request $request, int $messageId): JsonResponse
+    {
+        $message = Message::query()->findOrFail($messageId);
+        $this->assertParticipant($request, (int) $message->conversation_id);
+
+        $data = $request->validate(['reaction' => 'required|string|max:32']);
+        $this->assertAllowedReaction($data['reaction']);
+
+        $existing = MessageReaction::where([
+            'message_id' => $messageId,
+            'user_id' => $request->user()->id,
+            'reaction' => $data['reaction'],
+        ])->first();
+
+        if ($existing) {
+            $existing->delete();
+        } else {
+            MessageReaction::create([
+                'message_id' => $messageId,
+                'user_id' => $request->user()->id,
+                'reaction' => $data['reaction'],
+            ]);
+        }
+
+        return response()->json($this->reactionSummary($messageId, (int) $request->user()->id));
+    }
+
+    public function unreactByMessage(Request $request, int $messageId): JsonResponse
+    {
+        $message = Message::query()->findOrFail($messageId);
+        $this->assertParticipant($request, (int) $message->conversation_id);
+
+        $data = $request->validate(['reaction' => 'required|string|max:32']);
+        $this->assertAllowedReaction($data['reaction']);
+
+        MessageReaction::where([
+            'message_id' => $messageId,
+            'user_id' => $request->user()->id,
+            'reaction' => $data['reaction'],
+        ])->delete();
+
+        return response()->json($this->reactionSummary($messageId, (int) $request->user()->id));
+    }
+
+    // ── PATCH /api/messages/message/{messageId} ───────────────────────────────
+
+    public function update(Request $request, int $messageId): JsonResponse
+    {
+        $message = Message::findOrFail($messageId);
+
+        abort_unless(
+            $message->sender_id === $request->user()->id,
+            403,
+            'You may only edit your own messages.'
+        );
+
+        abort_if($message->deleted_at !== null, 422, 'Cannot edit a deleted message.');
+
+        $data = $request->validate(['body' => 'required|string|max:5000']);
+
+        $message->update([
+            'body'      => $data['body'],
+            'edited_at' => now(),
+        ]);
+        app(MessageSearchIndexer::class)->updateMessage($message);
+
+        $participantUserIds = ConversationParticipant::where('conversation_id', $message->conversation_id)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        return response()->json($message->fresh());
+    }
+
+    // ── DELETE /api/messages/message/{messageId} ──────────────────────────────
+
+    public function destroy(Request $request, int $messageId): JsonResponse
+    {
+        $message = Message::findOrFail($messageId);
+
+        abort_unless(
+            $message->sender_id === $request->user()->id || $request->user()->isAdmin(),
+            403,
+            'You may only delete your own messages.'
+        );
+
+        $participantUserIds = ConversationParticipant::where('conversation_id', $message->conversation_id)
+            ->whereNull('left_at')
+            ->pluck('user_id')
+            ->all();
+        app(MessageSearchIndexer::class)->deleteMessage($message);
+        $message->delete();
+        $this->touchConversationCachesForUsers($participantUserIds);
+
+        return response()->json(['ok' => true]);
+    }
+
+    // ── Private helpers ──────────────────────────────────────────────────────
+
+    private function assertParticipant(Request $request, int $conversationId): void
+    {
+        abort_unless(
+            ConversationParticipant::where('conversation_id', $conversationId)
+                ->where('user_id', $request->user()->id)
+                ->whereNull('left_at')
+                ->exists(),
+            403,
+            'You are not a participant of this conversation.'
+        );
+    }
+
+    private function touchConversationCachesForUsers(array $userIds): void
+    {
+        foreach (array_unique($userIds) as $userId) {
+            if (! $userId) {
+                continue;
+            }
+
+            $versionKey = "messages:conversations:version:{$userId}";
+            Cache::add($versionKey, 1, now()->addDay());
+            Cache::increment($versionKey);
+        }
+    }
+
+    private function assertAllowedReaction(string $reaction): void
+    {
+        $allowed = (array) config('messaging.reactions.allowed', []);
+        abort_unless(in_array($reaction, $allowed, true), 422, 'Reaction is not allowed.');
+    }
+
+    private function reactionSummary(int $messageId, int $userId): array
+    {
+        $rows = MessageReaction::query()
+            ->selectRaw('reaction, count(*) as aggregate_count')
+            ->where('message_id', $messageId)
+            ->groupBy('reaction')
+            ->get();
+
+        $summary = [];
+        foreach ($rows as $row) {
+            $summary[(string) $row->reaction] = (int) $row->aggregate_count;
+        }
+
+        $mine = MessageReaction::query()
+            ->where('message_id', $messageId)
+            ->where('user_id', $userId)
+            ->pluck('reaction')
+            ->values()
+            ->all();
+
+        $summary['me'] = $mine;
+
+        return $summary;
+    }
+
+    private function storeAttachment(UploadedFile $file, Message $message, int $userId): void
+    {
+        $mime = (string) $file->getMimeType();
+        $finfoMime = (string) finfo_file(finfo_open(FILEINFO_MIME_TYPE), $file->getPathname());
+        $detectedMime = $finfoMime !== '' ? $finfoMime : $mime;
+
+        $allowedImage = (array) config('messaging.attachments.allowed_image_mimes', []);
+        $allowedFile = (array) config('messaging.attachments.allowed_file_mimes', []);
+
+        $type = in_array($detectedMime, $allowedImage, true) ? 'image' : 'file';
+        $allowed = $type === 'image' ? $allowedImage : $allowedFile;
+
+        abort_unless(in_array($detectedMime, $allowed, true), 422, 'Unsupported attachment type.');
+
+        $maxBytes = $type === 'image'
+            ? ((int) config('messaging.attachments.max_image_kb', 10240) * 1024)
+            : ((int) config('messaging.attachments.max_file_kb', 25600) * 1024);
+
+        abort_if($file->getSize() > $maxBytes, 422, 'Attachment exceeds allowed size.');
+
+        $year = now()->format('Y');
+        $month = now()->format('m');
+        $ext = strtolower($file->getClientOriginalExtension() ?: $file->extension() ?: 'bin');
+        $path = "messages/{$message->conversation_id}/{$year}/{$month}/" . uniqid('att_', true) . ".{$ext}";
+
+        $diskName = (string) config('messaging.attachments.disk', 'local');
+        Storage::disk($diskName)->put($path, file_get_contents($file->getPathname()));
+
+        $width = null;
+        $height = null;
+        if ($type === 'image') {
+            $dimensions = @getimagesize($file->getPathname());
+            $width = isset($dimensions[0]) ? (int) $dimensions[0] : null;
+            $height = isset($dimensions[1]) ? (int) $dimensions[1] : null;
+        }
+
+        MessageAttachment::query()->create([
+            'message_id' => $message->id,
+            'user_id' => $userId,
+            'type' => $type,
+            'mime' => $detectedMime,
+            'size_bytes' => (int) $file->getSize(),
+            'width' => $width,
+            'height' => $height,
+            'sha256' => hash_file('sha256', $file->getPathname()),
+            'original_name' => substr((string) $file->getClientOriginalName(), 0, 255),
+            'storage_path' => $path,
+            'created_at' => now(),
+        ]);
+    }
+}

app/Http/Controllers/Api/Messaging/MessageSearchController.php

@@ -0,0 +1,139 @@
+<?php
+
+namespace App\Http\Controllers\Api\Messaging;
+
+use App\Http\Controllers\Controller;
+use App\Models\ConversationParticipant;
+use App\Models\Message;
+use App\Services\Messaging\MessageSearchIndexer;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Meilisearch\Client;
+
+class MessageSearchController extends Controller
+{
+    public function __construct(
+        private readonly MessageSearchIndexer $indexer,
+    ) {}
+
+    public function index(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        $data = $request->validate([
+            'q' => 'required|string|min:1|max:200',
+            'conversation_id' => 'nullable|integer|exists:conversations,id',
+            'cursor' => 'nullable|integer|min:0',
+        ]);
+
+        $allowedConversationIds = ConversationParticipant::query()
+            ->where('user_id', $user->id)
+            ->whereNull('left_at')
+            ->pluck('conversation_id')
+            ->map(fn ($id) => (int) $id)
+            ->all();
+
+        $conversationId = isset($data['conversation_id']) ? (int) $data['conversation_id'] : null;
+        if ($conversationId !== null && ! in_array($conversationId, $allowedConversationIds, true)) {
+            abort(403, 'You are not a participant of this conversation.');
+        }
+
+        if (empty($allowedConversationIds)) {
+            return response()->json(['data' => [], 'next_cursor' => null]);
+        }
+
+        $limit = max(1, (int) config('messaging.search.page_size', 20));
+        $offset = max(0, (int) ($data['cursor'] ?? 0));
+
+        $hits = collect();
+        $estimated = 0;
+
+        try {
+            $client = new Client(
+                config('scout.meilisearch.host'),
+                config('scout.meilisearch.key')
+            );
+
+            $prefix = (string) config('scout.prefix', '');
+            $indexName = $prefix . (string) config('messaging.search.index', 'messages');
+
+            $conversationFilter = $conversationId !== null
+                ? "conversation_id = {$conversationId}"
+                : 'conversation_id IN [' . implode(',', $allowedConversationIds) . ']';
+
+            $result = $client
+                ->index($indexName)
+                ->search((string) $data['q'], [
+                    'limit' => $limit,
+                    'offset' => $offset,
+                    'sort' => ['created_at:desc'],
+                    'filter' => $conversationFilter,
+                ]);
+
+            $hits = collect($result->getHits() ?? []);
+            $estimated = (int) ($result->getEstimatedTotalHits() ?? $hits->count());
+        } catch (\Throwable) {
+            $query = Message::query()
+                ->select('id')
+                ->whereNull('deleted_at')
+                ->whereIn('conversation_id', $allowedConversationIds)
+                ->when($conversationId !== null, fn ($q) => $q->where('conversation_id', $conversationId))
+                ->where('body', 'like', '%' . (string) $data['q'] . '%')
+                ->orderByDesc('created_at')
+                ->orderByDesc('id');
+
+            $estimated = (clone $query)->count();
+            $hits = $query->offset($offset)->limit($limit)->get()->map(fn ($row) => ['id' => (int) $row->id]);
+        }
+        $messageIds = $hits->pluck('id')->map(fn ($id) => (int) $id)->all();
+
+        $messages = Message::query()
+            ->whereIn('id', $messageIds)
+            ->whereIn('conversation_id', $allowedConversationIds)
+            ->whereNull('deleted_at')
+            ->with(['sender:id,username', 'attachments'])
+            ->get()
+            ->keyBy('id');
+
+        $ordered = $hits
+            ->map(function (array $hit) use ($messages) {
+                $message = $messages->get((int) ($hit['id'] ?? 0));
+                if (! $message) {
+                    return null;
+                }
+
+                return [
+                    'id' => $message->id,
+                    'conversation_id' => $message->conversation_id,
+                    'sender_id' => $message->sender_id,
+                    'sender' => $message->sender,
+                    'body' => $message->body,
+                    'created_at' => optional($message->created_at)?->toISOString(),
+                    'has_attachments' => $message->attachments->isNotEmpty(),
+                ];
+            })
+            ->filter()
+            ->values();
+
+        $nextCursor = ($offset + $limit) < $estimated ? ($offset + $limit) : null;
+
+        return response()->json([
+            'data' => $ordered,
+            'next_cursor' => $nextCursor,
+        ]);
+    }
+
+    public function rebuild(Request $request): JsonResponse
+    {
+        abort_unless($request->user()?->isAdmin(), 403, 'Admin access required.');
+
+        $conversationId = $request->integer('conversation_id');
+        if ($conversationId > 0) {
+            $this->indexer->rebuildConversation($conversationId);
+            return response()->json(['queued' => true, 'scope' => 'conversation']);
+        }
+
+        $this->indexer->rebuildAll();
+
+        return response()->json(['queued' => true, 'scope' => 'all']);
+    }
+}

app/Http/Controllers/Api/Messaging/MessagingSettingsController.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Http\Controllers\Api\Messaging;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * Manages per-user messaging privacy preference.
+ *
+ * GET  /api/messages/settings  → return current setting
+ * PATCH /api/messages/settings → update setting
+ */
+class MessagingSettingsController extends Controller
+{
+    public function show(Request $request): JsonResponse
+    {
+        return response()->json([
+            'allow_messages_from' => $request->user()->allow_messages_from ?? 'everyone',
+            'realtime_enabled' => (bool) config('messaging.realtime', false),
+        ]);
+    }
+
+    public function update(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'allow_messages_from' => 'required|in:everyone,followers,mutual_followers,nobody',
+        ]);
+
+        $request->user()->update($data);
+
+        return response()->json([
+            'allow_messages_from' => $request->user()->allow_messages_from,
+            'realtime_enabled' => (bool) config('messaging.realtime', false),
+        ]);
+    }
+}

app/Http/Controllers/Api/Messaging/TypingController.php

@@ -0,0 +1,96 @@
+<?php
+
+namespace App\Http\Controllers\Api\Messaging;
+
+use App\Events\TypingStarted;
+use App\Events\TypingStopped;
+use App\Http\Controllers\Controller;
+use App\Models\ConversationParticipant;
+use Illuminate\Cache\Repository;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+
+class TypingController extends Controller
+{
+    public function start(Request $request, int $conversationId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+
+        $ttl = max(5, (int) config('messaging.typing.ttl_seconds', 8));
+        $this->store()->put($this->key($conversationId, (int) $request->user()->id), 1, now()->addSeconds($ttl));
+
+        if ((bool) config('messaging.realtime', false)) {
+            event(new TypingStarted($conversationId, (int) $request->user()->id));
+        }
+
+        return response()->json(['ok' => true]);
+    }
+
+    public function stop(Request $request, int $conversationId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+        $this->store()->forget($this->key($conversationId, (int) $request->user()->id));
+
+        if ((bool) config('messaging.realtime', false)) {
+            event(new TypingStopped($conversationId, (int) $request->user()->id));
+        }
+
+        return response()->json(['ok' => true]);
+    }
+
+    public function index(Request $request, int $conversationId): JsonResponse
+    {
+        $this->assertParticipant($request, $conversationId);
+        $userId = (int) $request->user()->id;
+
+        $participants = ConversationParticipant::query()
+            ->where('conversation_id', $conversationId)
+            ->whereNull('left_at')
+            ->where('user_id', '!=', $userId)
+            ->with('user:id,username')
+            ->get();
+
+        $typing = $participants
+            ->filter(fn ($p) => $this->store()->has($this->key($conversationId, (int) $p->user_id)))
+            ->map(fn ($p) => [
+                'user_id' => (int) $p->user_id,
+                'username' => (string) ($p->user->username ?? ''),
+            ])
+            ->values();
+
+        return response()->json(['typing' => $typing]);
+    }
+
+    private function assertParticipant(Request $request, int $conversationId): void
+    {
+        abort_unless(
+            ConversationParticipant::query()
+                ->where('conversation_id', $conversationId)
+                ->where('user_id', $request->user()->id)
+                ->whereNull('left_at')
+                ->exists(),
+            403,
+            'You are not a participant of this conversation.'
+        );
+    }
+
+    private function key(int $conversationId, int $userId): string
+    {
+        return "typing:{$conversationId}:{$userId}";
+    }
+
+    private function store(): Repository
+    {
+        $store = (string) config('messaging.typing.cache_store', 'redis');
+        if ($store === 'redis' && ! class_exists('Redis')) {
+            return Cache::store();
+        }
+
+        try {
+            return Cache::store($store);
+        } catch (\Throwable) {
+            return Cache::store();
+        }
+    }
+}

app/Http/Controllers/Api/RankController.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Resources\ArtworkListResource;
+use App\Models\Artwork;
+use App\Models\Category;
+use App\Models\ContentType;
+use App\Services\RankingService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+
+/**
+ * RankController
+ *
+ * Serves pre-computed ranked artwork lists.
+ *
+ * Endpoints:
+ *   GET /api/rank/global?type=trending|new_hot|best
+ *   GET /api/rank/category/{id}?type=trending|new_hot|best
+ *   GET /api/rank/type/{contentType}?type=trending|new_hot|best
+ */
+class RankController extends Controller
+{
+    public function __construct(private readonly RankingService $ranking) {}
+
+    /**
+     * GET /api/rank/global
+     *
+     * Returns: { data: [...], meta: { list_type, computed_at, model_version, fallback } }
+     */
+    public function global(Request $request): AnonymousResourceCollection|JsonResponse
+    {
+        $listType = $this->resolveListType($request);
+        $result   = $this->ranking->getList('global', null, $listType);
+
+        return $this->buildResponse($result, $listType);
+    }
+
+    /**
+     * GET /api/rank/category/{id}
+     */
+    public function byCategory(Request $request, int $id): AnonymousResourceCollection|JsonResponse
+    {
+        if (! Category::where('id', $id)->where('is_active', true)->exists()) {
+            return response()->json(['message' => 'Category not found.'], 404);
+        }
+
+        $listType = $this->resolveListType($request);
+        $result   = $this->ranking->getList('category', $id, $listType);
+
+        return $this->buildResponse($result, $listType);
+    }
+
+    /**
+     * GET /api/rank/type/{contentType}
+     *
+     * {contentType} is accepted as either a slug (string) or numeric id.
+     */
+    public function byContentType(Request $request, string $contentType): AnonymousResourceCollection|JsonResponse
+    {
+        $ct = is_numeric($contentType)
+            ? ContentType::find((int) $contentType)
+            : ContentType::where('slug', $contentType)->first();
+
+        if ($ct === null) {
+            return response()->json(['message' => 'Content type not found.'], 404);
+        }
+
+        $listType = $this->resolveListType($request);
+        $result   = $this->ranking->getList('content_type', $ct->id, $listType);
+
+        return $this->buildResponse($result, $listType);
+    }
+
+    // ── Private helpers ────────────────────────────────────────────────────
+
+    /**
+     * Validate and normalise the ?type query param.
+     * Defaults to 'trending'.
+     */
+    private function resolveListType(Request $request): string
+    {
+        $allowed = ['trending', 'new_hot', 'best'];
+        $type    = $request->query('type', 'trending');
+
+        return in_array($type, $allowed, true) ? $type : 'trending';
+    }
+
+    /**
+     * Hydrate artwork IDs into Eloquent models (no N+1) and wrap in resources.
+     *
+     * @param  array{ids: int[], computed_at: string|null, model_version: string, fallback: bool} $result
+     */
+    private function buildResponse(array $result, string $listType = 'trending'): AnonymousResourceCollection
+    {
+        $ids      = $result['ids'];
+        $artworks = collect();
+
+        if (! empty($ids)) {
+            // Single whereIn query — no N+1
+            $keyed = Artwork::whereIn('id', $ids)
+                ->with([
+                    'user:id,name',
+                    'user.profile:user_id,avatar_hash',
+                    'categories' => function ($q): void {
+                        $q->select(
+                            'categories.id',
+                            'categories.content_type_id',
+                            'categories.parent_id',
+                            'categories.name',
+                            'categories.slug',
+                            'categories.sort_order'
+                        )->with(['parent:id,parent_id,content_type_id,name,slug', 'contentType:id,slug,name']);
+                    },
+                ])
+                ->get()
+                ->keyBy('id');
+
+            // Restore the ranked order
+            $artworks = collect($ids)
+                ->filter(fn ($id) => $keyed->has($id))
+                ->map(fn ($id) => $keyed[$id]);
+        }
+
+        $collection = ArtworkListResource::collection($artworks);
+
+        // Attach ranking meta as additional data
+        $collection->additional([
+            'meta' => [
+                'list_type'     => $listType,
+                'computed_at'   => $result['computed_at'],
+                'model_version' => $result['model_version'],
+                'fallback'      => $result['fallback'],
+                'count'         => $artworks->count(),
+            ],
+        ]);
+
+        return $collection;
+    }
+}

app/Http/Controllers/Api/ReactionController.php

@@ -0,0 +1,192 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Enums\ReactionType;
+use App\Http\Controllers\Controller;
+use App\Models\ArtworkComment;
+use App\Models\ArtworkReaction;
+use App\Models\CommentReaction;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Handles reaction toggling for artworks and comments.
+ *
+ * POST /api/artworks/{id}/reactions        → toggle artwork reaction
+ * POST /api/comments/{id}/reactions        → toggle comment reaction
+ * GET  /api/artworks/{id}/reactions        → list artwork reactions
+ * GET  /api/comments/{id}/reactions        → list comment reactions
+ */
+class ReactionController extends Controller
+{
+    // ─────────────────────────────────────────────────────────────────────────
+    // Artwork reactions
+    // ─────────────────────────────────────────────────────────────────────────
+
+    public function artworkReactions(Request $request, int $artworkId): JsonResponse
+    {
+        return $this->listReactions('artwork', $artworkId, $request->user()?->id);
+    }
+
+    public function toggleArtworkReaction(Request $request, int $artworkId): JsonResponse
+    {
+        $this->validateExists('artworks', $artworkId);
+        $slug = $this->validateReactionSlug($request);
+
+        return $this->toggle(
+            model:   new ArtworkReaction(),
+            where:   ['artwork_id' => $artworkId, 'user_id' => $request->user()->id, 'reaction' => $slug],
+            countWhere: ['artwork_id' => $artworkId],
+            entityId: $artworkId,
+            entityType: 'artwork',
+            userId: $request->user()->id,
+            slug: $slug,
+        );
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Comment reactions
+    // ─────────────────────────────────────────────────────────────────────────
+
+    public function commentReactions(Request $request, int $commentId): JsonResponse
+    {
+        return $this->listReactions('comment', $commentId, $request->user()?->id);
+    }
+
+    public function toggleCommentReaction(Request $request, int $commentId): JsonResponse
+    {
+        // Make sure comment exists and belongs to a public artwork
+        $comment = ArtworkComment::with('artwork')
+            ->where('id', $commentId)
+            ->whereHas('artwork', fn ($q) => $q->public()->published())
+            ->firstOrFail();
+
+        $slug = $this->validateReactionSlug($request);
+
+        return $this->toggle(
+            model:      new CommentReaction(),
+            where:      ['comment_id' => $commentId, 'user_id' => $request->user()->id, 'reaction' => $slug],
+            countWhere: ['comment_id' => $commentId],
+            entityId:   $commentId,
+            entityType: 'comment',
+            userId:     $request->user()->id,
+            slug:       $slug,
+        );
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Shared internals
+    // ─────────────────────────────────────────────────────────────────────────
+
+    private function toggle(
+        \Illuminate\Database\Eloquent\Model $model,
+        array  $where,
+        array  $countWhere,
+        int    $entityId,
+        string $entityType,
+        int    $userId,
+        string $slug,
+    ): JsonResponse {
+        $table    = $model->getTable();
+        $existing = DB::table($table)->where($where)->first();
+
+        if ($existing) {
+            // Toggle off
+            DB::table($table)->where($where)->delete();
+            $active = false;
+        } else {
+            // Toggle on
+            DB::table($table)->insertOrIgnore(array_merge($where, [
+                'created_at' => now(),
+            ]));
+            $active = true;
+        }
+
+        // Return fresh totals per reaction type
+        $totals = $this->getTotals($table, $countWhere, $userId);
+
+        return response()->json([
+            'entity_type' => $entityType,
+            'entity_id'   => $entityId,
+            'reaction'    => $slug,
+            'active'      => $active,
+            'totals'      => $totals,
+        ]);
+    }
+
+    private function listReactions(string $entityType, int $entityId, ?int $userId): JsonResponse
+    {
+        if ($entityType === 'artwork') {
+            $table = 'artwork_reactions';
+            $where = ['artwork_id' => $entityId];
+        } else {
+            $table = 'comment_reactions';
+            $where = ['comment_id' => $entityId];
+        }
+
+        $totals = $this->getTotals($table, $where, $userId);
+
+        return response()->json([
+            'entity_type' => $entityType,
+            'entity_id'   => $entityId,
+            'totals'      => $totals,
+        ]);
+    }
+
+    /**
+     * Return per-slug totals and whether the current user has each reaction.
+     */
+    private function getTotals(string $table, array $where, ?int $userId): array
+    {
+        $rows = DB::table($table)
+            ->where($where)
+            ->selectRaw('reaction, COUNT(*) as total')
+            ->groupBy('reaction')
+            ->get()
+            ->keyBy('reaction');
+
+        $totals = [];
+        foreach (ReactionType::cases() as $type) {
+            $slug  = $type->value;
+            $count = (int) ($rows[$slug]->total ?? 0);
+
+            // Check if current user has this reaction
+            $mine = false;
+            if ($userId && $count > 0) {
+                $mine = DB::table($table)
+                    ->where($where)
+                    ->where('reaction', $slug)
+                    ->where('user_id', $userId)
+                    ->exists();
+            }
+
+            $totals[$slug] = [
+                'emoji' => $type->emoji(),
+                'label' => $type->label(),
+                'count' => $count,
+                'mine'  => $mine,
+            ];
+        }
+
+        return $totals;
+    }
+
+    private function validateReactionSlug(Request $request): string
+    {
+        $request->validate([
+            'reaction' => ['required', 'string', 'in:' . implode(',', ReactionType::values())],
+        ]);
+
+        return $request->input('reaction');
+    }
+
+    private function validateExists(string $table, int $id): void
+    {
+        if (! DB::table($table)->where('id', $id)->exists()) {
+            throw new ModelNotFoundException("No [{$table}] record found with id [{$id}].");
+        }
+    }
+}

app/Http/Controllers/Api/ReportController.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\ConversationParticipant;
+use App\Models\Message;
+use App\Models\Report;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class ReportController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $user = $request->user();
+
+        $data = $request->validate([
+            'target_type' => 'required|in:message,conversation,user',
+            'target_id' => 'required|integer|min:1',
+            'reason' => 'required|string|max:120',
+            'details' => 'nullable|string|max:4000',
+        ]);
+
+        $targetType = $data['target_type'];
+        $targetId = (int) $data['target_id'];
+
+        if ($targetType === 'message') {
+            $message = Message::query()->findOrFail($targetId);
+            $allowed = ConversationParticipant::query()
+                ->where('conversation_id', $message->conversation_id)
+                ->where('user_id', $user->id)
+                ->whereNull('left_at')
+                ->exists();
+            abort_unless($allowed, 403, 'You are not allowed to report this message.');
+        }
+
+        if ($targetType === 'conversation') {
+            $allowed = ConversationParticipant::query()
+                ->where('conversation_id', $targetId)
+                ->where('user_id', $user->id)
+                ->whereNull('left_at')
+                ->exists();
+            abort_unless($allowed, 403, 'You are not allowed to report this conversation.');
+        }
+
+        if ($targetType === 'user') {
+            User::query()->findOrFail($targetId);
+        }
+
+        $report = Report::query()->create([
+            'reporter_id' => $user->id,
+            'target_type' => $targetType,
+            'target_id' => $targetId,
+            'reason' => $data['reason'],
+            'details' => $data['details'] ?? null,
+            'status' => 'open',
+        ]);
+
+        return response()->json(['id' => $report->id, 'status' => $report->status], 201);
+    }
+}

app/Http/Controllers/Api/Search/ArtworkSearchController.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\Search;
+
+use App\Http\Controllers\Controller;
+use App\Http\Resources\ArtworkListResource;
+use App\Models\Artwork;
+use App\Models\Tag;
+use App\Services\ArtworkSearchService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * Artwork search endpoints powered by Meilisearch.
+ *
+ * GET /api/search/artworks?q=&tags[]=&category=&orientation=&sort=
+ * GET /api/search/artworks/tag/{slug}
+ * GET /api/search/artworks/category/{cat}
+ * GET /api/search/artworks/related/{id}
+ */
+class ArtworkSearchController extends Controller
+{
+    public function __construct(
+        private readonly ArtworkSearchService $search
+    ) {}
+
+    /**
+     * GET /api/search/artworks
+     */
+    public function index(Request $request): JsonResponse
+    {
+        $validated = $request->validate([
+            'q'           => ['nullable', 'string', 'max:200'],
+            'tags'        => ['nullable', 'array', 'max:10'],
+            'tags.*'      => ['string', 'max:80'],
+            'category'    => ['nullable', 'string', 'max:80'],
+            'orientation' => ['nullable', 'in:landscape,portrait,square'],
+            'resolution'  => ['nullable', 'string', 'max:20'],
+            'author_id'   => ['nullable', 'integer', 'min:1'],
+            'sort'        => ['nullable', 'string', 'regex:/^(created_at|downloads|likes|views):(asc|desc)$/'],
+            'per_page'    => ['nullable', 'integer', 'min:1', 'max:100'],
+        ]);
+
+        $results = $this->search->search(
+            q: (string) ($validated['q'] ?? ''),
+            filters: array_filter([
+                'tags'        => $validated['tags'] ?? [],
+                'category'    => $validated['category'] ?? null,
+                'orientation' => $validated['orientation'] ?? null,
+                'resolution'  => $validated['resolution'] ?? null,
+                'author_id'   => $validated['author_id'] ?? null,
+                'sort'        => $validated['sort'] ?? null,
+            ]),
+            perPage: (int) ($validated['per_page'] ?? 24),
+        );
+
+        // Eager-load relations needed by ArtworkListResource
+        $results->getCollection()->loadMissing(['user', 'categories.contentType']);
+
+        return ArtworkListResource::collection($results)->response();
+    }
+
+    /**
+     * GET /api/search/artworks/tag/{slug}
+     */
+    public function byTag(Request $request, string $slug): JsonResponse
+    {
+        $tag = Tag::where('slug', $slug)->first();
+
+        if (! $tag) {
+            return response()->json(['message' => 'Tag not found.'], 404);
+        }
+
+        $results = $this->search->byTag($slug, (int) $request->query('per_page', 24));
+
+        return response()->json([
+            'tag'     => ['id' => $tag->id, 'name' => $tag->name, 'slug' => $tag->slug],
+            'results' => $results,
+        ]);
+    }
+
+    /**
+     * GET /api/search/artworks/category/{cat}
+     */
+    public function byCategory(Request $request, string $cat): JsonResponse
+    {
+        $results = $this->search->byCategory($cat, (int) $request->query('per_page', 24));
+
+        return response()->json($results);
+    }
+
+    /**
+     * GET /api/search/artworks/related/{id}
+     */
+    public function related(int $id): JsonResponse
+    {
+        $artwork = Artwork::with(['tags'])->find($id);
+
+        if (! $artwork) {
+            return response()->json(['message' => 'Artwork not found.'], 404);
+        }
+
+        $results = $this->search->related($artwork, 12);
+
+        return response()->json($results);
+    }
+}

app/Http/Controllers/Api/Search/UserSearchController.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace App\Http\Controllers\Api\Search;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use App\Support\AvatarUrl;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class UserSearchController extends Controller
+{
+    /**
+     * GET /api/search/users?q=gregor&per_page=4
+     *
+     * Public, rate-limited. Strips a leading @ from the query so that
+     * typing "@gregor" and "gregor" both work.
+     */
+    public function __invoke(Request $request): JsonResponse
+    {
+        $raw = trim((string) $request->query('q', ''));
+        $q   = ltrim($raw, '@');
+
+        if (strlen($q) < 2) {
+            return response()->json(['data' => []]);
+        }
+
+        $perPage = min((int) $request->query('per_page', 4), 8);
+
+        $users = User::query()
+            ->where('is_active', 1)
+            ->whereNull('deleted_at')
+            ->where(function ($qb) use ($q) {
+                $qb->whereRaw('LOWER(username) LIKE ?', ['%' . strtolower($q) . '%']);
+            })
+            ->with(['profile', 'statistics'])
+            ->orderByRaw('LOWER(username) = ? DESC', [strtolower($q)])   // exact match first
+            ->orderBy('username')
+            ->limit($perPage)
+            ->get(['id', 'username']);
+
+        $data = $users->map(function (User $user) {
+            $username       = strtolower((string) ($user->username ?? ''));
+            $avatarHash     = $user->profile?->avatar_hash;
+            $uploadsCount   = (int) ($user->statistics?->uploads_count ?? 0);
+
+            return [
+                'id'            => $user->id,
+                'type'          => 'user',
+                'username'      => $username,
+                'avatar_url'    => AvatarUrl::forUser((int) $user->id, $avatarHash, 64),
+                'uploads_count' => $uploadsCount,
+                'profile_url'   => '/@' . $username,
+            ];
+        });
+
+        return response()->json(['data' => $data]);
+    }
+}

app/Http/Controllers/Api/SimilarArtworkAnalyticsController.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Symfony\Component\HttpFoundation\Response;
+
+final class SimilarArtworkAnalyticsController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $payload = $request->validate([
+            'event_type' => ['required', 'string', 'in:impression,click'],
+            'algo_version' => ['required', 'string', 'max:64'],
+            'source_artwork_id' => ['required', 'integer', 'exists:artworks,id'],
+            'similar_artwork_id' => ['nullable', 'integer', 'exists:artworks,id'],
+            'position' => ['nullable', 'integer', 'min:1', 'max:100'],
+            'items_count' => ['nullable', 'integer', 'min:0', 'max:100'],
+        ]);
+
+        DB::table('similar_artwork_events')->insert([
+            'event_date' => now()->toDateString(),
+            'event_type' => (string) $payload['event_type'],
+            'algo_version' => (string) $payload['algo_version'],
+            'source_artwork_id' => (int) $payload['source_artwork_id'],
+            'similar_artwork_id' => isset($payload['similar_artwork_id']) ? (int) $payload['similar_artwork_id'] : null,
+            'position' => isset($payload['position']) ? (int) $payload['position'] : null,
+            'items_count' => isset($payload['items_count']) ? (int) $payload['items_count'] : null,
+            'occurred_at' => now(),
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        return response()->json(['success' => true], Response::HTTP_OK);
+    }
+}

app/Http/Controllers/Api/SimilarArtworksController.php

@@ -0,0 +1,172 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Services\ArtworkSearchService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Cache;
+
+/**
+ * GET /api/art/{id}/similar
+ *
+ * Returns up to 12 similar artworks based on:
+ *   1. Tag overlap (primary signal)
+ *   2. Same category
+ *   3. Similar orientation
+ *
+ * Uses Meilisearch via ArtworkSearchService for fast retrieval.
+ * Current artwork and its creator are excluded from results.
+ */
+final class SimilarArtworksController extends Controller
+{
+    private const LIMIT     = 12;
+    /** Spec §5: cache similar artworks 30–60 min; using config with 30 min default. */
+    private const CACHE_TTL = 1800; // 30 minutes
+
+    public function __construct(private readonly ArtworkSearchService $search) {}
+
+    public function __invoke(int $id): JsonResponse
+    {
+        $artwork = Artwork::public()
+            ->published()
+            ->with(['tags:id,slug', 'categories:id,slug'])
+            ->find($id);
+
+        if (! $artwork) {
+            return response()->json(['error' => 'Artwork not found'], 404);
+        }
+
+        $cacheKey = "api.similar.{$artwork->id}";
+
+        $items = Cache::remember($cacheKey, self::CACHE_TTL, function () use ($artwork) {
+            return $this->findSimilar($artwork);
+        });
+
+        return response()->json(['data' => $items]);
+    }
+
+    private function findSimilar(Artwork $artwork): array
+    {
+        $tagSlugs      = $artwork->tags->pluck('slug')->values()->all();
+        $categorySlugs = $artwork->categories->pluck('slug')->values()->all();
+        $srcOrientation = $this->orientation($artwork);
+
+        // Build Meilisearch filter: exclude self and same creator
+        $filterParts = [
+            'is_public = true',
+            'is_approved = true',
+            'id != ' . $artwork->id,
+            'author_id != ' . $artwork->user_id,
+        ];
+
+        // Priority 1: tag overlap (OR match across tags)
+        if ($tagSlugs !== []) {
+            $tagFilter = implode(' OR ', array_map(
+                fn (string $t): string => 'tags = "' . addslashes($t) . '"',
+                $tagSlugs
+            ));
+            $filterParts[] = '(' . $tagFilter . ')';
+        } elseif ($categorySlugs !== []) {
+            // Fallback to category if no tags
+            $catFilter = implode(' OR ', array_map(
+                fn (string $c): string => 'category = "' . addslashes($c) . '"',
+                $categorySlugs
+            ));
+            $filterParts[] = '(' . $catFilter . ')';
+        }
+
+        // ── Fetch 200-candidate pool from Meilisearch ─────────────────────────
+        $results = Artwork::search('')
+            ->options([
+                'filter' => implode(' AND ', $filterParts),
+                'sort'   => ['trending_score_7d:desc', 'created_at:desc'],
+            ])
+            ->paginate(200, 'page', 1);
+
+        $collection = $results->getCollection();
+        $collection->load(['tags:id,slug', 'stats', 'user:id,name', 'user.profile:user_id,avatar_hash']);
+
+        // ── PHP reranking ──────────────────────────────────────────────────────
+        // Weights: tag_overlap ×0.60, orientation_bonus +0.10, resolution_bonus
+        // +0.05, popularity (log-views) ≤0.15, freshness (exp decay) ×0.10
+        $srcTagSet = array_flip($tagSlugs);
+        $srcW      = (int) ($artwork->width  ?? 0);
+        $srcH      = (int) ($artwork->height ?? 0);
+
+        $scored = $collection->map(function (Artwork $candidate) use (
+            $srcTagSet, $tagSlugs, $srcOrientation, $srcW, $srcH
+        ): array {
+            $cTagSlugs  = $candidate->tags->pluck('slug')->all();
+            $cTagSet    = array_flip($cTagSlugs);
+
+            // Tag overlap (Sørensen–Dice-like)
+            $common     = count(array_intersect_key($srcTagSet, $cTagSet));
+            $total      = max(1, count($srcTagSet) + count($cTagSet) - $common);
+            $tagOverlap = $common / $total;
+
+            // Orientation bonus
+            $orientBonus = $this->orientation($candidate) === $srcOrientation ? 0.10 : 0.0;
+
+            // Resolution proximity bonus (both axes within 25 %)
+            $cW = (int) ($candidate->width  ?? 0);
+            $cH = (int) ($candidate->height ?? 0);
+            $resBonus = ($srcW > 0 && $srcH > 0 && $cW > 0 && $cH > 0
+                && abs($cW - $srcW) / $srcW <= 0.25
+                && abs($cH - $srcH) / $srcH <= 0.25
+            ) ? 0.05 : 0.0;
+
+            // Popularity boost (log-normalised views, capped at 0.15)
+            $views      = max(0, (int) ($candidate->stats?->views ?? 0));
+            $popularity = min(0.15, log(1 + $views) / 13.0);
+
+            // Freshness boost (exp decay, 60-day half-life, weight 0.10)
+            $publishedAt = $candidate->published_at ?? $candidate->created_at ?? now();
+            $ageDays     = max(0.0, (float) $publishedAt->diffInSeconds(now()) / 86400);
+            $freshness   = exp(-$ageDays / 60.0) * 0.10;
+
+            $score = $tagOverlap * 0.60
+                   + $orientBonus
+                   + $resBonus
+                   + $popularity
+                   + $freshness;
+
+            return ['score' => $score, 'artwork' => $candidate];
+        })->all();
+
+        usort($scored, fn ($a, $b) => $b['score'] <=> $a['score']);
+
+        return array_values(
+            array_map(fn (array $item): array => [
+                'id'          => $item['artwork']->id,
+                'title'       => $item['artwork']->title,
+                'slug'        => $item['artwork']->slug,
+                'thumb'       => $item['artwork']->thumbUrl('md'),
+                'url'         => '/art/' . $item['artwork']->id . '/' . $item['artwork']->slug,
+                'author'      => $item['artwork']->user?->name ?? 'Artist',
+                'author_avatar' => $item['artwork']->user?->profile?->avatar_url,
+                'author_id'   => $item['artwork']->user_id,
+                'orientation' => $this->orientation($item['artwork']),
+                'width'       => $item['artwork']->width,
+                'height'      => $item['artwork']->height,
+                'score'       => round((float) $item['score'], 5),
+            ], array_slice($scored, 0, self::LIMIT))
+        );
+    }
+
+    private function orientation(Artwork $artwork): string
+    {
+        if (! $artwork->width || ! $artwork->height) {
+            return 'square';
+        }
+
+        return match (true) {
+            $artwork->width > $artwork->height => 'landscape',
+            $artwork->height > $artwork->width => 'portrait',
+            default => 'square',
+        };
+    }
+}

app/Http/Controllers/Api/SuggestedCreatorsController.php

@@ -0,0 +1,217 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\Recommendation\UserPreferenceBuilder;
+use App\Support\AvatarUrl;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * GET /api/user/suggestions/creators
+ *
+ * Returns up to 12 creators the authenticated user might want to follow.
+ *
+ * Ranking algorithm (Phase 1 – no embeddings):
+ *   1. Creators followed by people you follow (mutual-follow signal)
+ *   2. Creators whose recent works overlap your top tags
+ *   3. High-quality creators (followers_count / artworks_count) in your categories
+ *
+ * Exclusions: yourself, already-followed creators.
+ *
+ * Cached per user for config('recommendations.ttl.creator_suggestions') seconds (default 30 min).
+ */
+final class SuggestedCreatorsController extends Controller
+{
+    private const LIMIT = 12;
+
+    public function __construct(private readonly UserPreferenceBuilder $prefBuilder) {}
+
+    public function __invoke(Request $request): JsonResponse
+    {
+        $user = $request->user();
+
+        $ttl      = (int) config('recommendations.ttl.creator_suggestions', 30 * 60);
+        $cacheKey = "creator_suggestions:{$user->id}";
+
+        $data = Cache::remember($cacheKey, $ttl, function () use ($user) {
+            return $this->buildSuggestions($user);
+        });
+
+        return response()->json(['data' => $data]);
+    }
+
+    private function buildSuggestions(\App\Models\User $user): array
+    {
+        try {
+            $profile     = $this->prefBuilder->build($user);
+            $followingIds = $profile->strongCreatorIds;
+            $topTagSlugs  = array_slice($profile->topTagSlugs, 0, 10);
+
+            // ── 1. Mutual-follow candidates ───────────────────────────────────
+            $mutualCandidates = [];
+            if ($followingIds !== []) {
+                $rows = DB::table('user_followers as uf')
+                    ->join('users as u', 'u.id', '=', 'uf.user_id')
+                    ->leftJoin('user_profiles as up', 'up.user_id', '=', 'u.id')
+                    ->leftJoin('user_statistics as us', 'us.user_id', '=', 'u.id')
+                    ->whereIn('uf.follower_id', $followingIds)
+                    ->where('uf.user_id', '!=', $user->id)
+                    ->whereNotIn('uf.user_id', array_merge($followingIds, [$user->id]))
+                    ->where('u.is_active', true)
+                    ->selectRaw('
+                        u.id,
+                        u.name,
+                        u.username,
+                        up.avatar_hash,
+                        COALESCE(us.followers_count, 0) as followers_count,
+                        COALESCE(us.artworks_count, 0)  as artworks_count,
+                        COUNT(*) as mutual_weight
+                    ')
+                    ->groupBy('u.id', 'u.name', 'u.username', 'up.avatar_hash', 'us.followers_count', 'us.artworks_count')
+                    ->orderByDesc('mutual_weight')
+                    ->limit(20)
+                    ->get();
+
+                foreach ($rows as $row) {
+                    $mutualCandidates[(int) $row->id] = [
+                        'id'              => (int) $row->id,
+                        'name'            => $row->name,
+                        'username'        => $row->username,
+                        'avatar_hash'     => $row->avatar_hash,
+                        'followers_count' => (int) $row->followers_count,
+                        'artworks_count'  => (int) $row->artworks_count,
+                        'score'           => (float) $row->mutual_weight * 3.0,
+                        'reason'          => 'Popular among creators you follow',
+                    ];
+                }
+            }
+
+            // ── 2. Tag-affinity candidates ────────────────────────────────────
+            $tagCandidates = [];
+            if ($topTagSlugs !== []) {
+                $tagFilter = implode(',', array_fill(0, count($topTagSlugs), '?'));
+
+                $rows = DB::table('tags as t')
+                    ->join('artwork_tag as at', 'at.tag_id', '=', 't.id')
+                    ->join('artworks as a', 'a.id', '=', 'at.artwork_id')
+                    ->join('users as u', 'u.id', '=', 'a.user_id')
+                    ->leftJoin('user_profiles as up', 'up.user_id', '=', 'u.id')
+                    ->leftJoin('user_statistics as us', 'us.user_id', '=', 'u.id')
+                    ->whereIn('t.slug', $topTagSlugs)
+                    ->where('a.is_public', true)
+                    ->where('a.is_approved', true)
+                    ->whereNull('a.deleted_at')
+                    ->where('u.id', '!=', $user->id)
+                    ->whereNotIn('u.id', array_merge($followingIds, [$user->id]))
+                    ->where('u.is_active', true)
+                    ->selectRaw('
+                        u.id,
+                        u.name,
+                        u.username,
+                        up.avatar_hash,
+                        COALESCE(us.followers_count, 0) as followers_count,
+                        COALESCE(us.artworks_count, 0)  as artworks_count,
+                        COUNT(DISTINCT t.id) as matched_tags
+                    ')
+                    ->groupBy('u.id', 'u.name', 'u.username', 'up.avatar_hash', 'us.followers_count', 'us.artworks_count')
+                    ->orderByDesc('matched_tags')
+                    ->limit(20)
+                    ->get();
+
+                foreach ($rows as $row) {
+                    if (isset($mutualCandidates[(int) $row->id])) {
+                        // Boost mutual candidate that also matches tags
+                        $mutualCandidates[(int) $row->id]['score'] += (float) $row->matched_tags;
+                        continue;
+                    }
+
+                    $tagCandidates[(int) $row->id] = [
+                        'id'              => (int) $row->id,
+                        'name'            => $row->name,
+                        'username'        => $row->username,
+                        'avatar_hash'     => $row->avatar_hash,
+                        'followers_count' => (int) $row->followers_count,
+                        'artworks_count'  => (int) $row->artworks_count,
+                        'score'           => (float) $row->matched_tags * 2.0,
+                        'reason'          => 'Matches your interests',
+                    ];
+                }
+            }
+
+            // ── 3. Merge & rank ───────────────────────────────────────────────
+            $combined = array_values(array_merge($mutualCandidates, $tagCandidates));
+            usort($combined, fn ($a, $b) => $b['score'] <=> $a['score']);
+            $top = array_slice($combined, 0, self::LIMIT);
+
+            if (count($top) < self::LIMIT) {
+                $topIds = array_column($top, 'id');
+                $excluded = array_unique(array_merge($followingIds, [$user->id], $topIds));
+                $top = array_merge($top, $this->highQualityFallback($excluded, self::LIMIT - count($top)));
+            }
+
+            return array_map(fn (array $c): array => [
+                'id'              => $c['id'],
+                'name'            => $c['name'],
+                'username'        => $c['username'],
+                'url'             => $c['username'] ? '/@' . $c['username'] : '/profile/' . $c['id'],
+                'avatar'          => AvatarUrl::forUser((int) $c['id'], $c['avatar_hash'] ?? null, 64),
+                'followers_count' => (int) ($c['followers_count'] ?? 0),
+                'artworks_count'  => (int) ($c['artworks_count']  ?? 0),
+                'reason'          => $c['reason'] ?? null,
+            ], $top);
+        } catch (\Throwable $e) {
+            Log::warning('SuggestedCreatorsController: failed', [
+                'user_id' => $user->id,
+                'error'   => $e->getMessage(),
+            ]);
+
+            return [];
+        }
+    }
+
+    /**
+     * @param array<int, int> $excludedIds
+     * @return array<int, array<string, mixed>>
+     */
+    private function highQualityFallback(array $excludedIds, int $limit): array
+    {
+        if ($limit <= 0) {
+            return [];
+        }
+
+        $rows = DB::table('users as u')
+            ->join('user_profiles as up', 'up.user_id', '=', 'u.id')
+            ->leftJoin('user_statistics as us', 'us.user_id', '=', 'u.id')
+            ->whereNotIn('u.id', $excludedIds)
+            ->where('u.is_active', true)
+            ->selectRaw('
+                u.id,
+                u.name,
+                u.username,
+                up.avatar_hash,
+                COALESCE(us.followers_count, 0) as followers_count,
+                COALESCE(us.artworks_count, 0) as artworks_count
+            ')
+            ->orderByDesc('followers_count')
+            ->limit($limit)
+            ->get();
+
+        return $rows->map(fn ($r) => [
+            'id'              => (int) $r->id,
+            'name'            => $r->name,
+            'username'        => $r->username,
+            'avatar_hash'     => $r->avatar_hash,
+            'followers_count' => (int) $r->followers_count,
+            'artworks_count'  => (int) $r->artworks_count,
+            'score'           => (float) $r->followers_count * 0.1,
+            'reason'          => 'Popular creator',
+        ])->all();
+    }
+}

app/Http/Controllers/Api/SuggestedTagsController.php

@@ -0,0 +1,152 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\Recommendation\UserPreferenceBuilder;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * GET /api/user/suggestions/tags
+ *
+ * Returns up to 20 tag suggestions for the authenticated user.
+ *
+ * Sources:
+ *   1. Tags from the user's favourited artworks and awards (affinity-ranked)
+ *   2. Trending tags from global activity (fallback / discovery)
+ *
+ * Does NOT require the user to follow tags.  This endpoint provides the foundation
+ * for a future "follow tags" feature while being useful immediately as discovery input.
+ *
+ * Cached per user for config('recommendations.ttl.tag_suggestions') seconds (default 60 min).
+ */
+final class SuggestedTagsController extends Controller
+{
+    private const LIMIT = 20;
+
+    public function __construct(private readonly UserPreferenceBuilder $prefBuilder) {}
+
+    public function __invoke(Request $request): JsonResponse
+    {
+        $user = $request->user();
+
+        $ttl      = (int) config('recommendations.ttl.tag_suggestions', 60 * 60);
+        $cacheKey = "tag_suggestions:{$user->id}";
+
+        $data = Cache::remember($cacheKey, $ttl, function () use ($user) {
+            return $this->buildSuggestions($user);
+        });
+
+        return response()->json(['data' => $data]);
+    }
+
+    private function buildSuggestions(\App\Models\User $user): array
+    {
+        try {
+            $profile       = $this->prefBuilder->build($user);
+            $knownTagSlugs = $profile->topTagSlugs; // already in user's profile – skip
+
+            // ── Personalised tags (with normalised weights) ───────────────────
+            $personalised = [];
+            foreach ($profile->tagWeights as $slug => $weight) {
+                if ($weight > 0.0) {
+                    $personalised[$slug] = (float) $weight;
+                }
+            }
+            arsort($personalised);
+
+            // ── Trending tags (global, last 7 days) ───────────────────────────
+            $trending = $this->trendingTags(40);
+
+            // ── Merge: personalised first, then trending discovery ─────────────
+            $merged = [];
+            foreach ($personalised as $slug => $weight) {
+                $merged[$slug] = [
+                    'slug'   => $slug,
+                    'score'  => $weight * 2.0, // boost personal signal
+                    'source' => 'affinity',
+                ];
+            }
+
+            foreach ($trending as $row) {
+                $slug = (string) $row->slug;
+                if (isset($merged[$slug])) {
+                    $merged[$slug]['score'] += (float) $row->trend_score;
+                } else {
+                    $merged[$slug] = [
+                        'slug'   => $slug,
+                        'score'  => (float) $row->trend_score,
+                        'source' => 'trending',
+                    ];
+                }
+            }
+
+            uasort($merged, fn ($a, $b) => $b['score'] <=> $a['score']);
+            $top = array_slice(array_values($merged), 0, self::LIMIT);
+
+            // ── Hydrate with DB info ──────────────────────────────────────────
+            $slugs   = array_column($top, 'slug');
+            $tagRows = DB::table('tags')
+                ->whereIn('slug', $slugs)
+                ->where('is_active', true)
+                ->get(['id', 'name', 'slug', 'usage_count'])
+                ->keyBy('slug');
+
+            $result = [];
+            foreach ($top as $item) {
+                $tag = $tagRows->get($item['slug']);
+                if ($tag === null) {
+                    continue;
+                }
+
+                $result[] = [
+                    'id'          => (int)    $tag->id,
+                    'name'        => (string) $tag->name,
+                    'slug'        => (string) $tag->slug,
+                    'usage_count' => (int)    $tag->usage_count,
+                    'source'      => (string) $item['source'],
+                ];
+            }
+
+            return $result;
+        } catch (\Throwable $e) {
+            Log::warning('SuggestedTagsController: failed', [
+                'user_id' => $user->id,
+                'error'   => $e->getMessage(),
+            ]);
+
+            return [];
+        }
+    }
+
+    /**
+     * Aggregate tag usage over the last 7 days as a proxy for trend score.
+     * Uses artwork_tag + artworks.published_at to avoid a heavy events table dependency.
+     *
+     * @return \Illuminate\Support\Collection<int, object{slug:string, trend_score:float}>
+     */
+    private function trendingTags(int $limit): \Illuminate\Support\Collection
+    {
+        $since = now()->subDays(7);
+
+        return DB::table('artwork_tag as at')
+            ->join('tags as t', 't.id', '=', 'at.tag_id')
+            ->join('artworks as a', 'a.id', '=', 'at.artwork_id')
+            ->where('a.published_at', '>=', $since)
+            ->where('a.is_public', true)
+            ->where('a.is_approved', true)
+            ->whereNull('a.deleted_at')
+            ->where('t.is_active', true)
+            ->selectRaw('t.slug, COUNT(*) / 1.0 as trend_score')
+            ->groupBy('t.id', 't.slug')
+            ->orderByDesc('trend_score')
+            ->limit($limit)
+            ->get();
+    }
+}

app/Http/Controllers/Api/TagController.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Tags\PopularTagsRequest;
+use App\Http\Requests\Tags\TagSearchRequest;
+use App\Models\Tag;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Cache;
+
+final class TagController extends Controller
+{
+    public function search(TagSearchRequest $request): JsonResponse
+    {
+        $q = trim((string) ($request->validated()['q'] ?? ''));
+
+        // Short results cached for 2 min; empty-query (popular suggestions) for 5 min.
+        $ttl      = $q === '' ? 300 : 120;
+        $cacheKey = 'tags.search.' . ($q === '' ? '__empty__' : md5($q));
+
+        $data = Cache::remember($cacheKey, $ttl, function () use ($q): mixed {
+            $query = Tag::query()->where('is_active', true);
+            if ($q !== '') {
+                $query->where(function ($sub) use ($q): void {
+                    $sub->where('name', 'like', $q . '%')
+                        ->orWhere('slug', 'like', $q . '%');
+                });
+            }
+
+            return $query
+                ->orderByDesc('usage_count')
+                ->limit(20)
+                ->get(['id', 'name', 'slug', 'usage_count']);
+        });
+
+        return response()->json(['data' => $data]);
+    }
+
+    public function popular(PopularTagsRequest $request): JsonResponse
+    {
+        $limit    = (int) ($request->validated()['limit'] ?? 20);
+        $cacheKey = 'tags.popular.' . $limit;
+
+        $data = Cache::remember($cacheKey, 300, function () use ($limit): mixed {
+            return Tag::query()
+                ->where('is_active', true)
+                ->orderByDesc('usage_count')
+                ->limit($limit)
+                ->get(['id', 'name', 'slug', 'usage_count']);
+        });
+
+        return response()->json(['data' => $data]);
+    }
+}

app/Http/Controllers/Api/UploadController.php

@@ -0,0 +1,558 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Uploads\UploadFinishRequest;
+use App\Http\Requests\Uploads\UploadInitRequest;
+use App\Http\Requests\Uploads\UploadChunkRequest;
+use App\Http\Requests\Uploads\UploadCancelRequest;
+use App\Http\Requests\Uploads\UploadStatusRequest;
+use App\Jobs\GenerateDerivativesJob;
+use App\Jobs\AutoTagArtworkJob;
+use App\Jobs\GenerateArtworkEmbeddingJob;
+use App\Repositories\Uploads\UploadSessionRepository;
+use App\Services\Uploads\UploadChunkService;
+use App\Services\Uploads\UploadCancelService;
+use App\Services\Uploads\UploadAuditService;
+use App\Services\Uploads\UploadPipelineService;
+use App\Services\Uploads\UploadQuotaService;
+use App\Services\Uploads\UploadSessionStatus;
+use App\Services\Uploads\UploadStatusService;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Symfony\Component\HttpFoundation\Response;
+use Throwable;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Validator;
+use App\Services\Upload\Contracts\UploadDraftServiceInterface;
+use Carbon\Carbon;
+use App\Uploads\Jobs\VirusScanJob;
+use App\Uploads\Services\PublishService;
+use App\Uploads\Exceptions\UploadNotFoundException;
+use App\Uploads\Exceptions\UploadOwnershipException;
+use App\Uploads\Exceptions\UploadPublishValidationException;
+use App\Uploads\Services\ArchiveInspectorService;
+use App\Uploads\Services\DraftQuotaService;
+use App\Uploads\Exceptions\DraftQuotaException;
+use App\Models\Artwork;
+use Illuminate\Support\Str;
+
+final class UploadController extends Controller
+{
+    public function init(
+        UploadInitRequest $request,
+        UploadPipelineService $pipeline,
+        UploadQuotaService $quota,
+        UploadAuditService $audit
+    )
+    {
+        $user = $request->user();
+
+        try {
+            $quota->enforce($user->id);
+        } catch (Throwable $e) {
+            return response()->json([
+                'message' => $e->getMessage(),
+            ], Response::HTTP_TOO_MANY_REQUESTS);
+        }
+
+        $result = $pipeline->initSession($user->id, (string) $request->ip());
+
+        $audit->log($user->id, 'upload_init_issued', (string) $request->ip(), [
+            'session_id' => $result->sessionId,
+        ]);
+
+        return response()->json([
+            'session_id' => $result->sessionId,
+            'upload_token' => $result->token,
+            'status' => $result->status,
+        ], Response::HTTP_OK);
+    }
+
+    public function finish(
+        UploadFinishRequest $request,
+        UploadPipelineService $pipeline,
+        UploadSessionRepository $sessions,
+        UploadAuditService $audit
+    ) {
+        $user = $request->user();
+        $sessionId = (string) $request->validated('session_id');
+        $artworkId = (int) $request->validated('artwork_id');
+
+        $session = $sessions->getOrFail($sessionId);
+
+        $request->artwork();
+
+        $validated = $pipeline->validateAndHash($sessionId);
+        if (! $validated->validation->ok || ! $validated->hash) {
+            return response()->json([
+                'message' => 'Upload validation failed.',
+                'reason' => $validated->validation->reason,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $scan = $pipeline->scan($sessionId);
+        if (! $scan->ok) {
+            return response()->json([
+                'message' => 'Upload scan failed.',
+                'reason' => $scan->reason,
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        try {
+            $status = DB::transaction(function () use ($pipeline, $sessionId, $validated, $artworkId) {
+                if ((bool) config('uploads.queue_derivatives', false)) {
+                    GenerateDerivativesJob::dispatch($sessionId, $validated->hash, $artworkId)->afterCommit();
+                    return 'queued';
+                }
+
+                $pipeline->processAndPublish($sessionId, $validated->hash, $artworkId);
+
+                // Derivatives are available now; dispatch AI auto-tagging.
+                AutoTagArtworkJob::dispatch($artworkId, $validated->hash)->afterCommit();
+                GenerateArtworkEmbeddingJob::dispatch($artworkId, $validated->hash)->afterCommit();
+                return UploadSessionStatus::PROCESSED;
+            });
+
+            $audit->log($user->id, 'upload_finished', $session->ip, [
+                'session_id' => $sessionId,
+                'hash' => $validated->hash,
+                'artwork_id' => $artworkId,
+                'status' => $status,
+            ]);
+
+            return response()->json([
+                'artwork_id' => $artworkId,
+                'status' => $status,
+            ], Response::HTTP_OK);
+        } catch (Throwable $e) {
+            Log::error('Upload finish failed', [
+                'session_id' => $sessionId,
+                'artwork_id' => $artworkId,
+                'error' => $e->getMessage(),
+            ]);
+
+            return response()->json([
+                'message' => 'Upload finish failed.',
+            ], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
+    public function chunk(UploadChunkRequest $request, UploadChunkService $chunks)
+    {
+        $user = $request->user();
+        $chunkFile = $request->file('chunk');
+
+        // Debug: log uploaded file object details to help diagnose missing chunk
+        try {
+            if (! $chunkFile) {
+                logger()->warning('Chunk upload: no file present on request', [
+                    'session_id' => (string) $request->input('session_id'),
+                    'headers' => $request->headers->all(),
+                ]);
+            } else {
+                logger()->warning('Chunk upload file details', [
+                    'session_id' => (string) $request->input('session_id'),
+                    'client_name' => $chunkFile->getClientOriginalName() ?? null,
+                    'client_size' => $chunkFile->getSize() ?? null,
+                    'error' => $chunkFile->getError(),
+                    'realpath' => $chunkFile->getRealPath(),
+                ]);
+            }
+        } catch (\Throwable $e) {
+            logger()->warning('Chunk upload debug logging failed', ['error' => $e->getMessage()]);
+        }
+
+        try {
+            // Use getPathname() — this returns the PHP temp filename even when
+            // getRealPath() may be false (platform/stream wrappers can cause
+            // getRealPath() to return false). getPathname() is safe for reading
+            // the uploaded chunk file.
+            $chunkPath = $chunkFile ? $chunkFile->getPathname() : '';
+
+            $result = $chunks->appendChunk(
+                (string) $request->input('session_id'),
+                (string) $chunkPath,
+                (int) $request->input('offset'),
+                (int) $request->input('chunk_size'),
+                (int) $request->input('total_size'),
+                (int) $user->id,
+                (string) $request->ip()
+            );
+
+            return response()->json([
+                'session_id' => $result->sessionId,
+                'status' => $result->status,
+                'received_bytes' => $result->receivedBytes,
+                'total_bytes' => $result->totalBytes,
+                'progress' => $result->progress,
+            ], Response::HTTP_OK);
+        } catch (\Throwable $e) {
+            logger()->warning('Upload chunk failed', [
+                'session_id' => (string) $request->input('session_id'),
+                'error' => $e->getMessage(),
+            ]);
+
+            // Include the underlying error message in the response during debugging
+            // so the frontend can show a useful description. Remove or hide this
+            // in production if you prefer more generic errors.
+            return response()->json([
+                'message' => 'Upload chunk failed.',
+                'error' => $e->getMessage(),
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+
+    public function status(string $id, UploadStatusRequest $request, UploadStatusService $statusService, UploadAuditService $audit)
+    {
+        $user = $request->user();
+        $payload = $statusService->get($id);
+
+        $audit->log($user->id, 'upload_status_checked', (string) $request->ip(), [
+            'session_id' => $id,
+            'status' => $payload['status'],
+        ]);
+
+        return response()->json([
+            'session_id' => $payload['session_id'],
+            'status' => $payload['status'],
+            'progress' => $payload['progress'],
+            'failure_reason' => $payload['failure_reason'],
+            'received_bytes' => $payload['received_bytes'] ?? 0,
+        ], Response::HTTP_OK);
+    }
+
+    public function cancel(UploadCancelRequest $request, UploadCancelService $cancel)
+    {
+        $user = $request->user();
+
+        try {
+            $result = $cancel->cancel(
+                (string) $request->input('session_id'),
+                (int) $user->id,
+                (string) $request->ip()
+            );
+
+            return response()->json([
+                'session_id' => $result['session_id'],
+                'status' => $result['status'],
+            ], Response::HTTP_OK);
+        } catch (\Throwable $e) {
+            logger()->warning('Upload cancel failed', [
+                'session_id' => (string) $request->input('session_id'),
+                'error' => $e->getMessage(),
+            ]);
+
+            return response()->json([
+                'message' => 'Upload cancel failed.',
+            ], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
+    /**
+     * Preload an upload draft: validate main file, create draft and store files.
+     *
+     * Returns JSON: { upload_id, status, expires_at }
+     */
+    public function preload(Request $request, UploadDraftServiceInterface $draftService, ArchiveInspectorService $archiveInspector, DraftQuotaService $draftQuotaService)
+    {
+        $user = $request->user();
+
+        $request->validate([
+            'main' => ['required', 'file'],
+            'screenshots' => ['sometimes', 'array'],
+            'screenshots.*' => ['file', 'image', 'max:5120'],
+        ]);
+
+        $main = $request->file('main');
+
+        // Detect type from mime
+        $mime = (string) $main->getClientMimeType();
+        $type = null;
+        if (str_starts_with($mime, 'image/')) {
+            $type = 'image';
+        } elseif (in_array($mime, ['application/zip', 'application/x-zip-compressed', 'application/x-tar', 'application/x-gzip', 'application/x-rar-compressed', 'application/octet-stream'])) {
+            $type = 'archive';
+        }
+
+        if ($type === null) {
+            return response()->json([
+                'message' => 'Invalid main file type.',
+                'errors' => [
+                    'main' => ['The main file must be an image or archive.'],
+                ],
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        if ($type === 'archive') {
+            $validator = Validator::make($request->all(), [
+                'screenshots' => ['required', 'array', 'min:1'],
+                'screenshots.*' => ['file', 'image', 'max:5120'],
+            ]);
+
+            if ($validator->fails()) {
+                return response()->json([
+                    'message' => 'The given data was invalid.',
+                    'errors' => $validator->errors(),
+                ], Response::HTTP_UNPROCESSABLE_ENTITY);
+            }
+
+            $inspection = $archiveInspector->inspect((string) $main->getPathname());
+            if (! $inspection->valid) {
+                return response()->json([
+                    'message' => 'Archive inspection failed.',
+                    'reason' => $inspection->reason,
+                    'stats' => $inspection->stats,
+                ], Response::HTTP_UNPROCESSABLE_ENTITY);
+            }
+        }
+
+        $incomingFiles = [$main];
+        if ($type === 'archive' && $request->hasFile('screenshots')) {
+            foreach ($request->file('screenshots') as $screenshot) {
+                $incomingFiles[] = $screenshot;
+            }
+        }
+
+        $mainHash = $draftService->calculateHash((string) $main->getPathname());
+
+        try {
+            $warnings = $draftQuotaService->assertCanCreateDraft($user, [
+                'files' => $incomingFiles,
+                'main_hash' => $mainHash,
+            ]);
+        } catch (DraftQuotaException $e) {
+            return response()->json([
+                'message' => $e->machineCode(),
+                'code' => $e->machineCode(),
+            ], $e->httpStatus());
+        }
+
+        // Create draft record (meta-only) and store main file via service
+        $draft = $draftService->createDraft(['user_id' => $user->id, 'type' => $type]);
+
+        try {
+            $mainInfo = $draftService->storeMainFile($draft['id'], $main);
+
+            // If archive, allow optional screenshots to be uploaded in the same request
+            if ($type === 'archive' && $request->hasFile('screenshots')) {
+                foreach ($request->file('screenshots') as $ss) {
+                    try {
+                        $draftService->storeScreenshot($draft['id'], $ss);
+                    } catch (Throwable $e) {
+                        // Keep controller thin: log and continue
+                        logger()->warning('Screenshot store failed during preload', ['error' => $e->getMessage(), 'draft' => $draft['id']]);
+                    }
+                }
+            }
+
+            // Set expiration (default 7 days) and return info
+            $ttlDays = (int) config('uploads.draft_ttl_days', 7);
+            $expiresAt = Carbon::now()->addDays($ttlDays);
+            $draftService->setExpiration($draft['id'], $expiresAt);
+
+            VirusScanJob::dispatch($draft['id']);
+
+            $response = [
+                'upload_id' => $draft['id'],
+                'status' => 'draft',
+                'expires_at' => $expiresAt->toISOString(),
+            ];
+
+            if (! empty($warnings)) {
+                $response['warnings'] = array_values($warnings);
+            }
+
+            return response()->json($response, Response::HTTP_OK);
+        } catch (Throwable $e) {
+            logger()->error('Upload preload failed', ['error' => $e->getMessage()]);
+            return response()->json(['message' => 'Preload failed.'], Response::HTTP_INTERNAL_SERVER_ERROR);
+        }
+    }
+
+    public function autosave(string $id, Request $request)
+    {
+        $user = $request->user();
+
+        $upload = DB::table('uploads')->where('id', $id)->first();
+        if (! $upload) {
+            return response()->json(['message' => 'Upload draft not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        if ((int) $upload->user_id !== (int) $user->id) {
+            return response()->json(['message' => 'Forbidden.'], Response::HTTP_FORBIDDEN);
+        }
+
+        if ((string) $upload->status !== 'draft') {
+            return response()->json([
+                'message' => 'Only draft uploads can be autosaved.',
+            ], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+
+        $validated = $request->validate([
+            'title' => ['nullable', 'string', 'max:255'],
+            'category_id' => ['nullable', 'exists:categories,id'],
+            'description' => ['nullable', 'string'],
+            'tags' => ['nullable', 'array'],
+            'license' => ['nullable', 'string'],
+            'nsfw' => ['nullable', 'boolean'],
+        ]);
+
+        $updates = [];
+        foreach (['title', 'category_id', 'description', 'tags', 'license', 'nsfw'] as $field) {
+            if (array_key_exists($field, $validated)) {
+                $updates[$field] = $validated[$field];
+            }
+        }
+
+        $dirty = [];
+        foreach ($updates as $field => $value) {
+            $current = $upload->{$field} ?? null;
+
+            if ($field === 'tags') {
+                $current = $current ? json_decode((string) $current, true) : null;
+            }
+
+            if ($field === 'nsfw') {
+                $current = is_null($current) ? null : (bool) $current;
+                $value = is_null($value) ? null : (bool) $value;
+            }
+
+            if ($current !== $value) {
+                $dirty[$field] = $value;
+            }
+        }
+
+        if (array_key_exists('tags', $dirty)) {
+            $dirty['tags'] = json_encode($dirty['tags']);
+        }
+
+        if (! empty($dirty)) {
+            $dirty['updated_at'] = now();
+            DB::table('uploads')->where('id', $id)->update($dirty);
+            $upload = DB::table('uploads')->where('id', $id)->first();
+        }
+
+        return response()->json([
+            'success' => true,
+            'updated_at' => (string) ($upload->updated_at ?? now()->toDateTimeString()),
+        ], Response::HTTP_OK);
+    }
+
+    public function processingStatus(string $id, Request $request)
+    {
+        $user = $request->user();
+
+        $upload = DB::table('uploads')->where('id', $id)->first();
+        if (! $upload) {
+            return response()->json(['message' => 'Upload not found.'], Response::HTTP_NOT_FOUND);
+        }
+
+        if ((int) $upload->user_id !== (int) $user->id) {
+            return response()->json(['message' => 'Forbidden.'], Response::HTTP_FORBIDDEN);
+        }
+
+        $status = (string) ($upload->status ?? 'draft');
+        $isScanned = (bool) ($upload->is_scanned ?? false);
+        $previewReady = ! empty($upload->preview_path);
+        $hasTags = (bool) ($upload->has_tags ?? false);
+        $processingState = (string) ($upload->processing_state ?? 'pending_scan');
+
+        return response()->json([
+            'id' => (string) $upload->id,
+            'status' => $status,
+            'is_scanned' => $isScanned,
+            'preview_ready' => $previewReady,
+            'has_tags' => $hasTags,
+            'processing_state' => $processingState,
+        ], Response::HTTP_OK);
+    }
+
+    public function publish(string $id, Request $request, PublishService $publishService)
+    {
+        $user = $request->user();
+
+        $validated = $request->validate([
+            'title' => ['nullable', 'string', 'max:150'],
+            'description' => ['nullable', 'string'],
+        ]);
+
+        if (ctype_digit($id)) {
+            $artworkId = (int) $id;
+            $artwork = Artwork::query()->find($artworkId);
+            if (! $artwork) {
+                return response()->json(['message' => 'Artwork not found.'], Response::HTTP_NOT_FOUND);
+            }
+
+            if ((int) $artwork->user_id !== (int) $user->id) {
+                return response()->json(['message' => 'Forbidden.'], Response::HTTP_FORBIDDEN);
+            }
+
+            $title = trim((string) ($validated['title'] ?? $artwork->title ?? ''));
+            if ($title === '') {
+                $title = 'Untitled artwork';
+            }
+
+            $slugBase = Str::slug($title);
+            if ($slugBase === '') {
+                $slugBase = 'artwork';
+            }
+
+            $slug = $slugBase;
+            $suffix = 2;
+            while (Artwork::query()->where('slug', $slug)->where('id', '!=', $artwork->id)->exists()) {
+                $slug = $slugBase . '-' . $suffix;
+                $suffix++;
+            }
+
+            $artwork->title = $title;
+            if (array_key_exists('description', $validated)) {
+                $artwork->description = $validated['description'];
+            }
+            $artwork->slug = $slug;
+            $artwork->is_public = true;
+            $artwork->is_approved = true;
+            $artwork->published_at = now();
+            $artwork->save();
+
+            // Record upload activity event
+            try {
+                \App\Models\ActivityEvent::record(
+                    actorId:    (int) $user->id,
+                    type:       \App\Models\ActivityEvent::TYPE_UPLOAD,
+                    targetType: \App\Models\ActivityEvent::TARGET_ARTWORK,
+                    targetId:   (int) $artwork->id,
+                );
+            } catch (\Throwable) {}
+
+            return response()->json([
+                'success' => true,
+                'artwork_id' => (int) $artwork->id,
+                'status' => 'published',
+                'slug' => (string) $artwork->slug,
+                'published_at' => optional($artwork->published_at)->toISOString(),
+            ], Response::HTTP_OK);
+        }
+
+        try {
+            $upload = $publishService->publish($id, $user);
+
+            return response()->json([
+                'success' => true,
+                'upload_id' => (string) $upload->id,
+                'status' => (string) $upload->status,
+                'published_at' => optional($upload->published_at)->toISOString(),
+                'final_path' => (string) ($upload->final_path ?? ''),
+            ], Response::HTTP_OK);
+        } catch (UploadOwnershipException $e) {
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_FORBIDDEN);
+        } catch (UploadNotFoundException $e) {
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_NOT_FOUND);
+        } catch (UploadPublishValidationException $e) {
+            return response()->json(['message' => $e->getMessage()], Response::HTTP_UNPROCESSABLE_ENTITY);
+        }
+    }
+}

app/Http/Controllers/Api/UsernameAvailabilityController.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\UsernameRequest;
+use App\Models\User;
+use App\Support\UsernamePolicy;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class UsernameAvailabilityController extends Controller
+{
+    public function __invoke(Request $request): JsonResponse
+    {
+        $candidate = UsernamePolicy::normalize((string) $request->query('username', ''));
+
+        $validator = validator(
+            ['username' => $candidate],
+            ['username' => UsernameRequest::formatRules()]
+        );
+
+        if ($validator->fails()) {
+            return response()->json([
+                'available' => false,
+                'normalized' => $candidate,
+                'errors' => $validator->errors()->toArray(),
+            ], 422);
+        }
+
+        $ignoreUserId = $request->user()?->id;
+        $exists = User::query()
+            ->whereRaw('LOWER(username) = ?', [$candidate])
+            ->when($ignoreUserId !== null, fn ($q) => $q->where('id', '!=', (int) $ignoreUserId))
+            ->exists();
+
+        return response()->json([
+            'available' => ! $exists,
+            'normalized' => $candidate,
+        ]);
+    }
+}

app/Http/Controllers/ArtworkController.php

@@ -1,10 +1,12 @@
 <?php
 namespace App\Http\Controllers;
 
+use App\Http\Controllers\Web\BrowseGalleryController;
+use App\Http\Controllers\Controller;
 use App\Http\Requests\ArtworkIndexRequest;
 use App\Models\Artwork;
 use App\Models\Category;
-use Illuminate\Http\RedirectResponse;
+use App\Services\Recommendations\SimilarArtworksService;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
 
@@ -51,14 +53,128 @@ class ArtworkController extends Controller
     }
 
     /**
-     * Show a single artwork by slug. Ensure it's public, approved and not deleted.
+     * Show a single artwork by slug. Resolve the slug manually to avoid implicit
+     * route-model binding exceptions when the slug does not correspond to an artwork.
      */
-    public function show(Artwork $artwork): View
+    public function show(Request $request, string $contentTypeSlug, string $categoryPath, $artwork = null)
     {
-        if (! $artwork->is_public || ! $artwork->is_approved || $artwork->trashed()) {
+        // Manually resolve artwork by slug when provided. The route may bind
+        // the 'artwork' parameter to an Artwork model or pass the slug string.
+        $foundArtwork = null;
+        $artworkSlug = null;
+        if ($artwork instanceof Artwork) {
+            $foundArtwork = $artwork;
+            $artworkSlug = $artwork->slug;
+        } elseif ($artwork) {
+            $artworkSlug = (string) $artwork;
+            $foundArtwork = Artwork::where('slug', $artworkSlug)->first();
+        }
+
+        // When the URL can represent a nested category path (e.g. /skins/audio/winamp),
+        // prefer category rendering over artwork slug collisions so same-level groups
+        // behave consistently.
+        if (! empty($artworkSlug)) {
+            $combinedPath = trim($categoryPath . '/' . $artworkSlug, '/');
+            $resolvedCategory = Category::findByPath($contentTypeSlug, $combinedPath);
+            if ($resolvedCategory) {
+                return app(BrowseGalleryController::class)->content(request(), $contentTypeSlug, $combinedPath);
+            }
+        }
+
+        // If no artwork was found, treat the request as a category path.
+        // The route places the artwork slug in the last segment, so include it.
+        // Delegate to BrowseGalleryController to render the same modern gallery
+        // layout used by routes like /skins/audio.
+        if (! $foundArtwork) {
+            $combinedPath = $categoryPath;
+            if ($artworkSlug) {
+                $combinedPath = trim($categoryPath . '/' . $artworkSlug, '/');
+            }
+            return app(BrowseGalleryController::class)->content(request(), $contentTypeSlug, $combinedPath);
+        }
+
+        if (! $foundArtwork->is_public || ! $foundArtwork->is_approved || $foundArtwork->trashed()) {
             abort(404);
         }
 
-        return view('artworks.show', ['artwork' => $artwork]);
+        $foundArtwork->loadMissing(['categories.contentType', 'user']);
+
+        $defaultAlgoVersion = (string) config('recommendations.embedding.algo_version', 'clip-cosine-v1');
+        $selectedAlgoVersion = $this->selectAlgoVersionForRequest($request, $defaultAlgoVersion);
+
+        $similarService = app(SimilarArtworksService::class);
+        $similarArtworks = $similarService->forArtwork((int) $foundArtwork->id, 12, $selectedAlgoVersion);
+
+        if ($similarArtworks->isEmpty() && $selectedAlgoVersion !== $defaultAlgoVersion) {
+            $similarArtworks = $similarService->forArtwork((int) $foundArtwork->id, 12, $defaultAlgoVersion);
+            $selectedAlgoVersion = $defaultAlgoVersion;
+        }
+
+        $similarArtworks->each(static function (Artwork $item): void {
+            $item->loadMissing(['categories.contentType', 'user']);
+        });
+
+        $similarItems = $similarArtworks
+            ->map(function (Artwork $item): ?array {
+                $category = $item->categories->first();
+                $contentType = $category?->contentType;
+
+                if (! $category || ! $contentType || empty($item->slug)) {
+                    return null;
+                }
+
+                return [
+                    'id' => (int) $item->id,
+                    'title' => html_entity_decode((string) $item->title, ENT_QUOTES | ENT_HTML5, 'UTF-8'),
+                    'author' => html_entity_decode((string) optional($item->user)->name, ENT_QUOTES | ENT_HTML5, 'UTF-8'),
+                    'thumb' => (string) ($item->thumb_url ?? $item->thumb ?? '/gfx/sb_join.jpg'),
+                    'thumb_srcset' => (string) ($item->thumb_srcset ?? ''),
+                    'url' => route('artworks.show', [
+                        'contentTypeSlug' => (string) $contentType->slug,
+                        'categoryPath' => (string) $category->slug,
+                        'artwork' => (string) $item->slug,
+                    ]),
+                ];
+            })
+            ->filter()
+            ->values();
+
+        return view('artworks.show', [
+            'artwork' => $foundArtwork,
+            'similarItems' => $similarItems,
+            'similarAlgoVersion' => $selectedAlgoVersion,
+        ]);
+    }
+
+    private function selectAlgoVersionForRequest(Request $request, string $default): string
+    {
+        $configured = (array) config('recommendations.ab.algo_versions', []);
+        $versions = array_values(array_filter(array_map(static fn ($value): string => trim((string) $value), $configured)));
+
+        if ($versions === []) {
+            return $default;
+        }
+
+        if (! in_array($default, $versions, true)) {
+            array_unshift($versions, $default);
+            $versions = array_values(array_unique($versions));
+        }
+
+        $forced = trim((string) $request->query('algo_version', ''));
+        if ($forced !== '' && in_array($forced, $versions, true)) {
+            return $forced;
+        }
+
+        if (count($versions) === 1) {
+            return $versions[0];
+        }
+
+        $visitorKey = $request->user()?->id
+            ? 'u:' . (string) $request->user()->id
+            : 's:' . (string) $request->session()->getId();
+
+        $bucket = abs(crc32($visitorKey)) % count($versions);
+
+        return $versions[$bucket] ?? $default;
     }
 }

app/Http/Controllers/Auth/RegisteredUserController.php

@@ -2,24 +2,51 @@
 
 namespace App\Http\Controllers\Auth;
 
+use App\Jobs\SendVerificationEmailJob;
 use App\Http\Controllers\Controller;
+use App\Models\EmailSendEvent;
 use App\Models\User;
-use Illuminate\Auth\Events\Registered;
+use App\Services\Auth\DisposableEmailService;
+use App\Services\Auth\RegistrationVerificationTokenService;
+use App\Services\Security\TurnstileVerifier;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Hash;
-use Illuminate\Validation\Rules;
+use Illuminate\Support\Facades\RateLimiter;
+use Illuminate\Support\Str;
 use Illuminate\View\View;
 
 class RegisteredUserController extends Controller
 {
+    public function __construct(
+        private readonly TurnstileVerifier $turnstileVerifier,
+        private readonly DisposableEmailService $disposableEmailService,
+        private readonly RegistrationVerificationTokenService $verificationTokenService,
+    )
+    {
+    }
+
     /**
      * Display the registration view.
      */
-    public function create(): View
+    public function create(Request $request): View
     {
-        return view('auth.register');
+        return view('auth.register', [
+            'prefillEmail' => (string) $request->query('email', ''),
+            'requiresTurnstile' => $this->shouldRequireTurnstile($request->ip()),
+            'turnstileSiteKey' => (string) config('services.turnstile.site_key', ''),
+        ]);
+    }
+
+    public function notice(Request $request): View
+    {
+        $email = (string) session('registration_email', '');
+        $remaining = $email === '' ? 0 : $this->resendRemainingSeconds($email);
+
+        return view('auth.register-notice', [
+            'email' => $email,
+            'resendSeconds' => $remaining,
+        ]);
     }
 
     /**
@@ -29,22 +56,252 @@ class RegisteredUserController extends Controller
      */
     public function store(Request $request): RedirectResponse
     {
-        $request->validate([
-            'name' => ['required', 'string', 'max:255'],
-            'email' => ['required', 'string', 'lowercase', 'email', 'max:255', 'unique:'.User::class],
-            'password' => ['required', 'confirmed', Rules\Password::defaults()],
+        $validated = $request->validate([
+            'email' => ['required', 'string', 'lowercase', 'email', 'max:255'],
+            'website' => ['nullable', 'max:0'],
+            'cf-turnstile-response' => ['nullable', 'string'],
         ]);
 
-        $user = User::create([
-            'name' => $request->name,
-            'email' => $request->email,
-            'password' => Hash::make($request->password),
+        $email = strtolower(trim((string) $validated['email']));
+        $ip = $request->ip();
+
+        $this->trackRegisterAttempt($ip);
+
+        if ($this->shouldRequireTurnstile($ip)) {
+            $verified = $this->turnstileVerifier->verify(
+                (string) $request->input('cf-turnstile-response', ''),
+                $ip
+            );
+
+            if (! $verified) {
+                return back()
+                    ->withInput($request->except('website'))
+                    ->withErrors(['captcha' => 'Captcha verification failed. Please try again.']);
+            }
+        }
+
+        if ($this->disposableEmailService->isDisposableEmail($email)) {
+            $this->logEmailEvent($email, $ip, null, 'blocked', 'disposable');
+
+            return back()
+                ->withInput($request->except('website'))
+                ->withErrors(['email' => 'Please use a real email provider.']);
+        }
+
+        $user = User::query()->where('email', $email)->first();
+
+        if ($user && $user->email_verified_at !== null) {
+            $this->logEmailEvent($email, $ip, (int) $user->id, 'blocked', 'already-verified');
+
+            return $this->redirectToRegisterNotice($email);
+        }
+
+        if (! $user) {
+            $user = User::query()->create([
+                'username' => null,
+                'name' => Str::before($email, '@'),
+                'email' => $email,
+                'password' => Hash::make(Str::random(64)),
+                'is_active' => false,
+                'onboarding_step' => 'email',
+                'username_changed_at' => now(),
+            ]);
+        }
+
+        if ($this->isWithinEmailCooldown($user)) {
+            $this->logEmailEvent($email, $ip, (int) $user->id, 'blocked', 'cooldown');
+
+            return $this->redirectToRegisterNotice($email);
+        }
+
+        $token = $this->verificationTokenService->createForUser((int) $user->id);
+        $event = $this->logEmailEvent($email, $ip, (int) $user->id, 'queued', null);
+
+        SendVerificationEmailJob::dispatch(
+            emailEventId: (int) $event->id,
+            email: $email,
+            token: $token,
+            userId: (int) $user->id,
+            ip: $ip
+        );
+
+        $this->markVerificationEmailSent($user);
+
+        return $this->redirectToRegisterNotice($email);
+    }
+
+    public function resendVerification(Request $request): RedirectResponse
+    {
+        $validated = $request->validate([
+            'email' => ['required', 'string', 'lowercase', 'email', 'max:255'],
         ]);
 
-        event(new Registered($user));
+        $email = strtolower(trim((string) $validated['email']));
+        $ip = $request->ip();
 
-        Auth::login($user);
+        $user = User::query()
+            ->where('email', $email)
+            ->whereNull('email_verified_at')
+            ->where('onboarding_step', 'email')
+            ->first();
 
-        return redirect(route('dashboard', absolute: false));
+        if (! $user) {
+            $this->logEmailEvent($email, $ip, null, 'blocked', 'missing');
+
+            return $this->redirectToRegisterNotice($email);
+        }
+
+        if ($this->isWithinEmailCooldown($user)) {
+            $this->logEmailEvent($email, $ip, (int) $user->id, 'blocked', 'cooldown');
+
+            return $this->redirectToRegisterNotice($email);
+        }
+
+        $token = $this->verificationTokenService->createForUser((int) $user->id);
+        $event = $this->logEmailEvent($email, $ip, (int) $user->id, 'queued', null);
+
+        SendVerificationEmailJob::dispatch(
+            emailEventId: (int) $event->id,
+            email: $email,
+            token: $token,
+            userId: (int) $user->id,
+            ip: $ip
+        );
+
+        $this->markVerificationEmailSent($user);
+
+        return $this->redirectToRegisterNotice($email);
+    }
+
+    private function redirectToRegisterNotice(string $email): RedirectResponse
+    {
+        return redirect(route('register.notice', absolute: false))
+            ->with('status', $this->genericSuccessMessage())
+            ->with('registration_email', $email);
+    }
+
+    private function genericSuccessMessage(): string
+    {
+        return (string) config('registration.generic_success_message', 'If that email is valid, we sent a verification link.');
+    }
+
+    private function logEmailEvent(string $email, ?string $ip, ?int $userId, string $status, ?string $reason): EmailSendEvent
+    {
+        return EmailSendEvent::query()->create([
+            'type' => 'verify_email',
+            'email' => $email,
+            'ip' => $ip,
+            'user_id' => $userId,
+            'status' => $status,
+            'reason' => $reason,
+            'created_at' => now(),
+        ]);
+    }
+
+    private function shouldRequireTurnstile(?string $ip): bool
+    {
+        if (! $this->turnstileVerifier->isEnabled()) {
+            return false;
+        }
+
+        if ($ip === null || $ip === '') {
+            return false;
+        }
+
+        $threshold = max(1, (int) config('registration.turnstile_suspicious_attempts', 2));
+        $attempts = (int) cache()->get($this->registerAttemptCacheKey($ip), 0);
+
+        if ($attempts >= $threshold) {
+            return true;
+        }
+
+        $minuteLimit = max(1, (int) config('registration.ip_per_minute_limit', 3));
+        $dailyLimit = max(1, (int) config('registration.ip_per_day_limit', 20));
+
+        if (RateLimiter::tooManyAttempts($this->registerIpRateKey($ip), $minuteLimit)) {
+            return true;
+        }
+
+        return RateLimiter::tooManyAttempts($this->registerIpDailyRateKey($ip), $dailyLimit);
+    }
+
+    private function trackRegisterAttempt(?string $ip): void
+    {
+        if ($ip === null || $ip === '') {
+            return;
+        }
+
+        $key = $this->registerAttemptCacheKey($ip);
+        $windowMinutes = max(1, (int) config('registration.turnstile_attempt_window_minutes', 30));
+        $seconds = $windowMinutes * 60;
+
+        $attempts = (int) cache()->get($key, 0);
+        cache()->put($key, $attempts + 1, $seconds);
+    }
+
+    private function registerAttemptCacheKey(string $ip): string
+    {
+        return 'register:attempts:' . sha1($ip);
+    }
+
+    private function registerIpRateKey(string $ip): string
+    {
+        return 'register:ip:' . $ip;
+    }
+
+    private function registerIpDailyRateKey(string $ip): string
+    {
+        return 'register:ip:daily:' . $ip;
+    }
+
+    private function isWithinEmailCooldown(User $user): bool
+    {
+        if ($user->last_verification_sent_at === null) {
+            return false;
+        }
+
+        $cooldownMinutes = max(1, (int) config('registration.email_cooldown_minutes', 30));
+
+        return $user->last_verification_sent_at->gt(now()->subMinutes($cooldownMinutes));
+    }
+
+    private function markVerificationEmailSent(User $user): void
+    {
+        $now = now();
+
+        $windowStartedAt = $user->verification_send_window_started_at;
+        if (! $windowStartedAt || $windowStartedAt->lt($now->copy()->subDay())) {
+            $user->verification_send_window_started_at = $now;
+            $user->verification_send_count_24h = 1;
+        } else {
+            $user->verification_send_count_24h = ((int) $user->verification_send_count_24h) + 1;
+        }
+
+        $user->last_verification_sent_at = $now;
+        $user->save();
+    }
+
+    private function resendCooldownSeconds(): int
+    {
+        return max(60, ((int) config('registration.email_cooldown_minutes', 30)) * 60);
+    }
+
+    private function resendRemainingSeconds(string $email): int
+    {
+        $user = User::query()
+            ->where('email', strtolower(trim($email)))
+            ->whereNull('email_verified_at')
+            ->first();
+
+        if (! $user || $user->last_verification_sent_at === null) {
+            return 0;
+        }
+
+        $remaining = $user->last_verification_sent_at
+            ->copy()
+            ->addSeconds($this->resendCooldownSeconds())
+            ->diffInSeconds(now(), false);
+
+        return $remaining >= 0 ? 0 : abs((int) $remaining);
     }
 }

app/Http/Controllers/Auth/RegistrationVerificationController.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Http\Controllers\Auth;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use App\Services\Auth\RegistrationVerificationTokenService;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
+
+class RegistrationVerificationController extends Controller
+{
+    public function __construct(
+        private readonly RegistrationVerificationTokenService $tokenService
+    )
+    {
+    }
+
+    public function __invoke(string $token): RedirectResponse
+    {
+        $record = $this->tokenService->findValidRecord($token);
+
+        if (! $record) {
+            return redirect(route('login', absolute: false))
+                ->withErrors(['email' => 'Verification link is invalid.']);
+        }
+
+        $user = User::query()->find((int) $record->user_id);
+        if (! $user) {
+            DB::table('user_verification_tokens')->where('id', $record->id)->delete();
+
+            return redirect(route('login', absolute: false))
+                ->withErrors(['email' => 'Verification link is invalid.']);
+        }
+
+        $user->forceFill([
+            'email_verified_at' => $user->email_verified_at ?? now(),
+            'onboarding_step' => 'verified',
+            'is_active' => true,
+        ])->save();
+
+        DB::table('user_verification_tokens')
+            ->where('id', $record->id)
+            ->delete();
+
+        Auth::login($user);
+
+        return redirect('/setup/password')->with('status', 'Email verified. Continue with password setup.');
+    }
+}

app/Http/Controllers/Auth/SetupPasswordController.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Http\Controllers\Auth;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\View\View;
+
+class SetupPasswordController extends Controller
+{
+    public function create(Request $request): View
+    {
+        return view('auth.setup-password', [
+            'email' => (string) ($request->user()?->email ?? ''),
+        ]);
+    }
+
+    public function store(Request $request): RedirectResponse
+    {
+        $validated = $request->validate([
+            'password' => [
+                'required',
+                'string',
+                'min:10',
+                'regex:/\d/',
+                'regex:/[^\w\s]/',
+                'confirmed',
+            ],
+        ], [
+            'password.min' => 'Your password must be at least 10 characters.',
+            'password.regex' => 'Your password must include at least one number and one symbol.',
+            'password.confirmed' => 'Password confirmation does not match.',
+        ]);
+
+        $request->user()->forceFill([
+            'password' => Hash::make((string) $validated['password']),
+            'onboarding_step' => 'password',
+            'needs_password_reset' => false,
+        ])->save();
+
+        return redirect('/setup/username')->with('status', 'Password saved. Choose your public username to finish setup.');
+    }
+}

app/Http/Controllers/Auth/SetupUsernameController.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Http\Controllers\Auth;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\UsernameRequest;
+use App\Services\UsernameApprovalService;
+use App\Support\UsernamePolicy;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\View\View;
+
+class SetupUsernameController extends Controller
+{
+    public function __construct(private readonly UsernameApprovalService $usernameApprovalService)
+    {
+    }
+
+    public function create(Request $request): View
+    {
+        return view('auth.setup-username', [
+            'username' => (string) ($request->user()?->username ?? ''),
+        ]);
+    }
+
+    public function store(Request $request): RedirectResponse
+    {
+        $normalized = UsernamePolicy::normalize((string) $request->input('username', ''));
+        $request->merge(['username' => $normalized]);
+
+        $validated = $request->validate([
+            'username' => UsernameRequest::rulesFor((int) $request->user()->id),
+        ], [
+            'username.required' => 'Please choose a username to continue.',
+            'username.unique' => 'This username is already taken.',
+            'username.regex' => 'Use only letters, numbers, underscores, or hyphens.',
+            'username.min' => 'Username must be at least 3 characters.',
+            'username.max' => 'Username must be at most 20 characters.',
+        ]);
+
+        $candidate = (string) $validated['username'];
+        $user = $request->user();
+
+        $similar = UsernamePolicy::similarReserved($candidate);
+        if ($similar !== null && ! UsernamePolicy::hasApprovedOverride($candidate, (int) $user->id)) {
+            $this->usernameApprovalService->submit($user, $candidate, 'onboarding_username', [
+                'current_username' => (string) ($user->username ?? ''),
+            ]);
+
+            return back()
+                ->withInput()
+                ->with('status', 'Your request has been submitted for manual username review.')
+                ->withErrors([
+                    'username' => 'This username is too similar to a reserved name and requires manual approval.',
+                ]);
+        }
+
+        DB::transaction(function () use ($user, $candidate): void {
+            $oldUsername = (string) ($user->username ?? '');
+
+            if ($oldUsername !== '' && strtolower($oldUsername) !== strtolower($candidate) && Schema::hasTable('username_history')) {
+                DB::table('username_history')->insert([
+                    'user_id' => (int) $user->id,
+                    'old_username' => strtolower($oldUsername),
+                    'changed_at' => now(),
+                    'created_at' => now(),
+                    'updated_at' => now(),
+                ]);
+            }
+
+            if ($oldUsername !== '' && strtolower($oldUsername) !== strtolower($candidate) && Schema::hasTable('username_redirects')) {
+                DB::table('username_redirects')->updateOrInsert(
+                    ['old_username' => strtolower($oldUsername)],
+                    [
+                        'new_username' => strtolower($candidate),
+                        'user_id' => (int) $user->id,
+                        'created_at' => now(),
+                        'updated_at' => now(),
+                    ]
+                );
+            }
+
+            $user->forceFill([
+                'username' => strtolower($candidate),
+                'onboarding_step' => 'complete',
+                'username_changed_at' => now(),
+            ])->save();
+        });
+
+        return redirect('/@' . strtolower($candidate));
+    }
+}

app/Http/Controllers/CategoryPageController.php

@@ -4,19 +4,24 @@ namespace App\Http\Controllers;
 
 use App\Models\Category;
 use App\Models\ContentType;
-use App\Models\Artwork;
+use App\Services\ArtworkService;
 use Illuminate\Http\Request;
-use Illuminate\Pagination\LengthAwarePaginator;
 
 class CategoryPageController extends Controller
 {
-    public function show(Request $request, string $contentTypeSlug, string $categoryPath = null)
+    public function __construct(private ArtworkService $artworkService)
+    {
+    }
+
+    public function show(Request $request, string $contentTypeSlug, ?string $categoryPath = null)
     {
         $contentType = ContentType::where('slug', strtolower($contentTypeSlug))->first();
         if (! $contentType) {
             abort(404);
         }
 
+        $sort = (string) $request->get('sort', 'latest');
+
 
         if ($categoryPath === null || $categoryPath === '') {
             // No category path: show content-type landing page (e.g., /wallpapers)
@@ -24,38 +29,38 @@ class CategoryPageController extends Controller
             $page_title = $contentType->name;
             $page_meta_description = $contentType->description ?? ($contentType->name . ' artworks on Skinbase');
 
-            return view('legacy.content-type', compact(
+            // Load artworks for this content type (show gallery on the root page)
+            $perPage = 40;
+            $artworks = $this->artworkService->getArtworksByContentType($contentType->slug, $perPage, $sort);
+
+            return view('legacy::content-type', compact(
                 'contentType',
                 'rootCategories',
+                'artworks',
                 'page_title',
                 'page_meta_description'
             ));
         }
 
         $segments = array_filter(explode('/', $categoryPath));
-        if (empty($segments)) {
+        $slugs = array_values(array_map('strtolower', $segments));
+        if (empty($slugs)) {
             return redirect('/browse-categories');
         }
 
-        // Traverse categories by slug path within the content type
-        $current = Category::where('content_type_id', $contentType->id)
-            ->whereNull('parent_id')
-            ->where('slug', strtolower(array_shift($segments)))
-            ->first();
+        // If the first slug exists but under a different content type, redirect to its canonical URL
+        $firstSlug = $slugs[0];
+        $globalRoot = Category::whereNull('parent_id')->where('slug', $firstSlug)->first();
+        if ($globalRoot && $globalRoot->contentType && $globalRoot->contentType->slug !== strtolower($contentType->slug)) {
+            $redirectPath = '/' . $globalRoot->contentType->slug . '/' . implode('/', $slugs);
+            return redirect($redirectPath, 301);
+        }
 
-
-        if (! $current) {
+        // Resolve category by path using the helper that validates parent chain and content type
+        $category = Category::findByPath($contentType->slug, $slugs);
+        if (! $category) {
             abort(404);
         }
-
-        foreach ($segments as $slug) {
-            $current = $current->children()->where('slug', strtolower($slug))->first();
-            if (! $current) {
-                abort(404);
-            }
-        }
-
-        $category = $current;
         $subcategories = $category->children()->orderBy('sort_order')->orderBy('name')->get();
         $rootCategories = $contentType->rootCategories()->orderBy('sort_order')->orderBy('name')->get();
 
@@ -71,22 +76,23 @@ class CategoryPageController extends Controller
         $category->load('children');
         $gather($category);
 
-        // Load artworks that are attached to any of these categories
-        $query = Artwork::whereHas('categories', function ($q) use ($collected) {
-            $q->whereIn('categories.id', $collected);
-        })->published()->public();
-
-        // Paginate results
+        // Load artworks via ArtworkService to support arbitrary-depth category paths
         $perPage = 40;
-        $artworks = $query->orderBy('published_at', 'desc')
-            ->paginate($perPage)
-            ->withQueryString();
+        try {
+            // service expects an array with contentType slug first, then category slugs
+            $pathSlugs = array_merge([strtolower($contentTypeSlug)], $slugs);
+            $artworks = $this->artworkService->getArtworksByCategoryPath($pathSlugs, $perPage, $sort);
+        } catch (\Throwable $e) {
+            abort(404);
+        }
 
         $page_title = $category->name;
         $page_meta_description = $category->description ?? ($contentType->name . ' artworks on Skinbase');
         $page_meta_keywords = strtolower($contentType->slug) . ', skinbase, artworks, wallpapers, skins, photography';
 
-        return view('legacy.category-slug', compact(
+        // resolved category and breadcrumbs are used by the view
+
+        return view('legacy::category-slug', compact(
             'contentType',
             'category',
             'subcategories',

app/Http/Controllers/Community/ChatController.php

@@ -0,0 +1,80 @@
+<?php
+
+namespace App\Http\Controllers\Community;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+class ChatController extends Controller
+{
+    public function index(Request $request)
+    {
+        $page_title = 'Online Chat';
+
+        $store = $request->input('store_chat');
+        $chat_text = $request->input('chat_txt');
+
+        $chat = new \App\Chat();
+
+        if (!empty($store) && $store === 'true' && !empty($chat_text)) {
+            if (!empty($_SESSION['web_login']['status'])) {
+                $chat->StoreMessage($chat_text);
+                $chat->UpdateChatFile('cron/chat_log.txt', 10);
+            }
+        }
+
+        ob_start();
+        \App\Banner::ShowResponsiveAd();
+        $adHtml = ob_get_clean();
+
+        ob_start();
+        $userID = $_SESSION['web_login']['user_id'] ?? null;
+        $chat->ShowChat(50, $userID);
+        $chatHtml = ob_get_clean();
+
+        try {
+            $smileys = DB::table('smileys')->select('code', 'picture', 'emotion')->get();
+        } catch (\Throwable $e) {
+            $smileys = collect();
+        }
+
+        return view('community.chat', compact('page_title', 'adHtml', 'chatHtml', 'smileys'));
+    }
+
+    /**
+     * Handle legacy AJAX chat posts from old JS.
+     */
+    public function post(Request $request)
+    {
+        $message = $request->input('message') ?? $request->input('chat_txt') ?? null;
+        if (empty($message)) {
+            return response()->json(['ok' => false, 'error' => 'empty_message'], 400);
+        }
+
+        // Ensure legacy $_SESSION keys exist for Chat class (best-effort sync from Laravel session/auth)
+        if (empty($_SESSION['web_login']['user_id'])) {
+            $webLogin = session('web_login');
+            if ($webLogin && isset($webLogin['user_id'])) {
+                $_SESSION['web_login'] = $webLogin;
+            } elseif (auth()->check()) {
+                $user = auth()->user();
+                $_SESSION['web_login'] = [
+                    'user_id' => $user->id,
+                    'username' => $user->username ?? $user->name ?? null,
+                    'status' => true,
+                ];
+            }
+        }
+
+        $chat = new \App\Chat();
+        try {
+            $chat->StoreMessage($message);
+            $chat->UpdateChatFile('cron/chat_log.txt', 50);
+        } catch (\Throwable $e) {
+            return response()->json(['ok' => false, 'error' => 'store_failed', 'message' => $e->getMessage()], 500);
+        }
+
+        return response()->json(['ok' => true]);
+    }
+}

app/Http/Controllers/Community/InterviewController.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace App\Http\Controllers\Community;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+class InterviewController extends Controller
+{
+    public function index(Request $request)
+    {
+        try {
+            $interviews = DB::table('interviews as i')
+                ->leftJoin('users as u', 'u.username', '=', 'i.username')
+                ->select('i.id', 'i.headline', 'i.username', 'u.id as user_id', 'u.name as uname', 'u.icon')
+                ->orderByDesc('i.id')
+                ->get();
+        } catch (\Throwable $e) {
+            $interviews = collect();
+        }
+
+        return view('legacy::interviews', [
+            'interviews' => $interviews,
+            'page_title' => 'Interviews',
+        ]);
+    }
+
+    public function show(Request $request, $id, $slug = null)
+    {
+        $id = (int) $id;
+
+        if ($request->isMethod('post')) {
+            $action = $request->input('action');
+            if ($action === 'store' && (!empty($_SESSION['web_login']['user_type']) && $_SESSION['web_login']['user_type'] > 1)) {
+                $comment = $request->input('comment');
+                $tekst = nl2br(htmlspecialchars($comment ?? '', ENT_QUOTES, 'UTF-8'));
+                $interviewId = (int) $request->input('interview_id');
+
+                try {
+                    DB::table('interviews_comment')->insert([
+                        'nid' => $interviewId,
+                        'author' => $_SESSION['web_login']['username'] ?? 'Anonymous',
+                        'datum' => DB::raw('CURRENT_TIMESTAMP'),
+                        'tekst' => $tekst,
+                    ]);
+
+                    $ar2 = DB::table('users')
+                        ->where('uname', $_SESSION['web_login']['username'])
+                        ->first();
+
+                    if (!empty($ar2->user_id)) {
+                        DB::table('users_statistics')
+                            ->where('user_id', $ar2->user_id)
+                            ->increment('newscomment');
+                    }
+                } catch (\Throwable $e) {
+                    // fail silently
+                }
+            }
+        }
+
+        try {
+            $ar = DB::table('interviews')->where('id', $id)->first();
+        } catch (\Throwable $e) {
+            $ar = null;
+        }
+
+        if (! $ar) {
+            return redirect('/interviews');
+        }
+
+        try {
+            $artworks = DB::table('wallz')
+                ->where('uname', $ar->username)
+                ->inRandomOrder()
+                ->limit(2)
+                ->get();
+        } catch (\Throwable $e) {
+            $artworks = collect();
+        }
+
+        try {
+            $comments = DB::table('interviews_comment as c')
+                ->leftJoin('users as u', 'u.uname', '=', 'c.author')
+                ->where('c.nid', $id)
+                ->select('c.*', 'u.user_id', 'u.user_type', 'u.signature', 'u.icon')
+                ->orderBy('c.datum')
+                ->get();
+        } catch (\Throwable $e) {
+            $comments = collect();
+        }
+
+        $authors = $comments->pluck('author')->unique()->values()->all();
+        $postCounts = [];
+        if (!empty($authors)) {
+            try {
+                $counts = DB::table('interviews_comment')
+                    ->select('author', DB::raw('COUNT(*) as cnt'))
+                    ->whereIn('author', $authors)
+                    ->groupBy('author')
+                    ->get();
+
+                foreach ($counts as $c) {
+                    $postCounts[$c->author] = $c->cnt;
+                }
+            } catch (\Throwable $e) {
+            }
+        }
+
+        $page_title = 'Interview with ' . ($ar->username ?? '');
+
+        return view('community.interview', [
+            'ar' => $ar,
+            'artworks' => $artworks,
+            'comments' => $comments,
+            'postCounts' => $postCounts,
+            'page_title' => $page_title,
+        ]);
+    }
+}

app/Http/Controllers/Community/LatestCommentsController.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace App\Http\Controllers\Community;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use App\Models\ArtworkComment;
+use App\Support\AvatarUrl;
+use App\Services\ThumbnailPresenter;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Str;
+use Carbon\Carbon;
+
+class LatestCommentsController extends Controller
+{
+    private const PER_PAGE = 20;
+
+    public function index(Request $request)
+    {
+        $page_title = 'Latest Comments';
+
+        // Build initial (first-page, type=all) data for React SSR props
+        $initialData = Cache::remember('comments.latest.all.page1', 120, function () {
+            return ArtworkComment::with(['user', 'user.profile', 'artwork'])
+                ->whereHas('artwork', function ($q) {
+                    $q->public()->published()->whereNull('deleted_at');
+                })
+                ->orderByDesc('artwork_comments.created_at')
+                ->paginate(self::PER_PAGE);
+        });
+
+        $items = $initialData->getCollection()->map(function (ArtworkComment $c) {
+            $art  = $c->artwork;
+            $user = $c->user;
+
+            $present    = $art ? ThumbnailPresenter::present($art, 'md') : null;
+            $thumb      = $present ? ($present['url'] ?? null) : null;
+            $userId     = (int) ($c->user_id ?? 0);
+            $avatarHash = $user?->profile?->avatar_hash ?? null;
+
+            return [
+                'comment_id'   => $c->getKey(),
+                'comment_text' => e(strip_tags($c->content ?? '')),
+                'created_at'   => $c->created_at?->toIso8601String(),
+                'time_ago'     => $c->created_at ? Carbon::parse($c->created_at)->diffForHumans() : null,
+
+                'commenter' => [
+                    'id'          => $userId,
+                    'username'    => $user?->username ?? null,
+                    'display'     => $user?->username ?? $user?->name ?? 'User',
+                    'profile_url' => $user?->username ? '/@' . $user->username : '/profile/' . $userId,
+                    'avatar_url'  => AvatarUrl::forUser($userId, $avatarHash, 64),
+                ],
+
+                'artwork' => $art ? [
+                    'id'    => $art->id,
+                    'title' => $art->title,
+                    'slug'  => $art->slug ?? Str::slug($art->title ?? ''),
+                    'url'   => '/art/' . $art->id . '/' . ($art->slug ?? Str::slug($art->title ?? '')),
+                    'thumb' => $thumb,
+                ] : null,
+            ];
+        });
+
+        $props = [
+            'initialComments' => $items->values()->all(),
+            'initialMeta'     => [
+                'current_page' => $initialData->currentPage(),
+                'last_page'    => $initialData->lastPage(),
+                'per_page'     => $initialData->perPage(),
+                'total'        => $initialData->total(),
+                'has_more'     => $initialData->hasMorePages(),
+            ],
+            'isAuthenticated' => (bool) auth()->user(),
+        ];
+
+        return view('web.comments.latest', compact('page_title', 'props'));
+    }
+}

app/Http/Controllers/Community/LatestController.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Http\Controllers\Community;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Services\ArtworkService;
+use Illuminate\Http\Request;
+
+class LatestController extends Controller
+{
+    protected ArtworkService $artworks;
+
+    public function __construct(ArtworkService $artworks)
+    {
+        $this->artworks = $artworks;
+    }
+
+    public function index(Request $request)
+    {
+        $perPage = 21;
+
+        $artworks = $this->artworks->browsePublicArtworks($perPage);
+
+        $artworks->getCollection()->transform(function (Artwork $artwork) {
+            $primaryCategory = $artwork->categories->sortBy('sort_order')->first();
+            $categoryName = $primaryCategory->name ?? '';
+            $gid = $primaryCategory ? ((int) $primaryCategory->id % 5) * 5 : 0;
+            $present = \App\Services\ThumbnailPresenter::present($artwork, 'md');
+
+            return (object) [
+                'id' => $artwork->id,
+                'name' => $artwork->title,
+                'category_name' => $categoryName,
+                'gid_num' => $gid,
+                'thumb_url' => $present['url'],
+                'thumb_srcset' => $present['srcset'] ?? $present['url'],
+                'uname' => $artwork->user->name ?? 'Skinbase',
+                'published_at' => $artwork->published_at, // required by CursorPaginator
+            ];
+        });
+
+        return view('web.uploads.latest', [
+            'artworks' => $artworks,
+            'page_title' => 'Latest Artworks',
+        ]);
+    }
+}

app/Http/Controllers/Community/NewsController.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Controllers\Community;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+class NewsController extends Controller
+{
+    public function show(Request $request, $id, $slug = null)
+    {
+        $id = (int) $id;
+
+        try {
+            $news = DB::table('news as t1')
+                ->leftJoin('users as t2', 't1.user_id', '=', 't2.user_id')
+                ->where('t1.news_id', $id)
+                ->select('t1.*', 't2.uname', 't2.user_type', 't2.signature', 't2.icon')
+                ->first();
+        } catch (\Throwable $e) {
+            $news = null;
+        }
+
+        if (empty($news)) {
+            return redirect('/');
+        }
+
+        // redirect to canonical slug for SEO if available
+        try {
+            $correct = \Illuminate\Support\Str::slug($news->headline ?? 'news-' . $id);
+            if ($slug !== $correct) {
+                $qs = $request->getQueryString();
+                $url = route('legacy.news.show', ['id' => $id, 'slug' => $correct]);
+                if ($qs) $url .= '?' . $qs;
+                return redirect($url, 301);
+            }
+        } catch (\Throwable $e) {
+            // ignore
+        }
+
+        try {
+            $comments = DB::table('news_comment as c')
+                ->leftJoin('users as u', 'c.user_id', '=', 'u.user_id')
+                ->where('c.news_id', $id)
+                ->select('c.posted', 'c.message', 'c.user_id', 'u.user_type', 'u.signature', 'u.icon', 'u.uname')
+                ->orderBy('c.posted')
+                ->get();
+        } catch (\Throwable $e) {
+            $comments = collect();
+        }
+
+        $page_title = ($news->headline ?? 'News') . ' - SkinBase News';
+
+        return view('community.news', compact('news', 'comments', 'page_title'));
+    }
+}

app/Http/Controllers/ContentRouterController.php

@@ -0,0 +1,45 @@
+<?php
+namespace App\Http\Controllers;
+
+use App\Http\Controllers\ArtworkController;
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+class ContentRouterController extends Controller
+{
+    /**
+     * Universal router for content-type roots, nested category paths, and artwork slugs.
+     * Delegates to existing controllers to keep business logic centralized.
+     */
+    public function handle(Request $request, string $contentTypeSlug, ?string $categoryPath = null, $artwork = null)
+    {
+        if (! empty($artwork)) {
+            $normalizedCategoryPath = trim((string) $categoryPath, '/');
+
+            return app(ArtworkController::class)->show($request, $contentTypeSlug, $normalizedCategoryPath, $artwork);
+        }
+
+        $path = $categoryPath;
+
+        // If no path provided, render the content-type landing (root) page
+        if (empty($path)) {
+            // Special-case photography root to use legacy controller
+            if (strtolower($contentTypeSlug) === 'photography') {
+                return app(\App\Http\Controllers\Legacy\PhotographyController::class)->index($request);
+            }
+
+            return app(\App\Http\Controllers\CategoryPageController::class)->show($request, $contentTypeSlug, null);
+        }
+
+        $segments = array_values(array_filter(explode('/', $path)));
+        if (empty($segments)) {
+            return app(\App\Http\Controllers\CategoryPageController::class)->show($request, $contentTypeSlug, null);
+        }
+
+        // Treat the last segment as an artwork slug candidate and delegate to ArtworkController::show
+        $artworkSlug = array_pop($segments);
+        $categoryPath = implode('/', $segments);
+
+        return app(ArtworkController::class)->show($request, $contentTypeSlug, $categoryPath, $artworkSlug);
+    }
+}

app/Http/Controllers/Dashboard/ArtworkController.php

@@ -3,8 +3,9 @@
 namespace App\Http\Controllers\Dashboard;
 
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Dashboard\ArtworkEditRequest;
+use App\Http\Requests\Dashboard\ArtworkDestroyRequest;
 use App\Http\Requests\Dashboard\UpdateArtworkRequest;
-use App\Models\Artwork;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Storage;
@@ -25,10 +26,9 @@ class ArtworkController extends Controller
         ]);
     }
 
-    public function edit(Request $request, int $id): View
+    public function edit(ArtworkEditRequest $request, int $id): View
     {
-        $artwork = $request->user()->artworks()->whereKey($id)->firstOrFail();
-        $this->authorize('update', $artwork);
+        $artwork = $request->artwork();
 
         return view('artworks.edit', [
             'artwork' => $artwork,
@@ -38,8 +38,7 @@ class ArtworkController extends Controller
 
     public function update(UpdateArtworkRequest $request, int $id): RedirectResponse
     {
-        $artwork = $request->user()->artworks()->whereKey($id)->firstOrFail();
-        $this->authorize('update', $artwork);
+        $artwork = $request->artwork();
 
         $data = $request->validated();
 
@@ -83,10 +82,9 @@ class ArtworkController extends Controller
             ->with('status', 'Artwork updated.');
     }
 
-    public function destroy(Request $request, int $id): RedirectResponse
+    public function destroy(ArtworkDestroyRequest $request, int $id): RedirectResponse
     {
-        $artwork = $request->user()->artworks()->whereKey($id)->firstOrFail();
-        $this->authorize('delete', $artwork);
+        $artwork = $request->artwork();
 
         // Best-effort remove stored file.
         if (! empty($artwork->file_path) && Storage::disk('public')->exists($artwork->file_path)) {

app/Http/Controllers/Dashboard/CommentController.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Http\Controllers\Dashboard;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+class CommentController extends Controller
+{
+    public function index(Request $request)
+    {
+        $user = $request->user();
+        // Minimal placeholder: real implementation should query comments received or made
+        $comments = [];
+
+        return view('dashboard.comments', ['comments' => $comments]);
+    }
+}

app/Http/Controllers/Dashboard/DashboardAwardsController.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Http\Controllers\Dashboard;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+
+class DashboardAwardsController extends Controller
+{
+    public function index(Request $request): View
+    {
+        $user = $request->user();
+
+        $artworks = Artwork::query()
+            ->where('user_id', (int) $user->id)
+            ->whereHas('awards')
+            ->with(['awardStat', 'stats', 'categories.contentType'])
+            ->orderByDesc(
+                \App\Models\ArtworkAwardStat::select('score_total')
+                    ->whereColumn('artwork_id', 'artworks.id')
+                    ->limit(1)
+            )
+            ->paginate(24)
+            ->withQueryString();
+
+        return view('dashboard.awards', [
+            'artworks'  => $artworks,
+            'page_title' => 'My Awards – SkinBase',
+        ]);
+    }
+}

app/Http/Controllers/Dashboard/DashboardGalleryController.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Http\Controllers\Dashboard;
+
+use App\Http\Controllers\Controller;
+use App\Models\Artwork;
+use App\Models\ContentType;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+
+class DashboardGalleryController extends Controller
+{
+    public function index(Request $request): View
+    {
+        $user = $request->user();
+        $perPage = 24;
+
+        $query = Artwork::query()
+            ->where('user_id', (int) $user->id)
+            ->orderBy('published_at', 'desc');
+
+        $artworks = $query->paginate($perPage)->withQueryString();
+
+        $mainCategories = ContentType::orderBy('id')
+            ->get(['name', 'slug'])
+            ->map(function (ContentType $type) {
+                return (object) [
+                    'id' => $type->id,
+                    'name' => $type->name,
+                    'slug' => $type->slug,
+                    'url' => '/' . strtolower($type->slug),
+                ];
+            });
+
+        return view('gallery.index', [
+            'gallery_type' => 'dashboard',
+            'mainCategories' => $mainCategories,
+            'subcategories' => $mainCategories,
+            'contentType' => null,
+            'category' => null,
+            'artworks' => $artworks,
+            'hero_title' => 'My Gallery',
+            'hero_description' => 'Your uploaded artworks.',
+            'breadcrumbs' => collect(),
+            'page_title' => 'My Gallery - SkinBase',
+            'page_meta_description' => 'My uploaded artworks on SkinBase',
+            'page_meta_keywords' => 'my gallery, uploads, skinbase',
+            'page_canonical' => url('/dashboard/gallery'),
+        ]);
+    }
+}