Implement academy analytics, billing, and web stories updates

app/Console/Commands/AcademyAnalyticsHealthCommand.php

@@ -0,0 +1,183 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\AcademyContentMetricDaily;
+use App\Models\AcademyEvent;
+use App\Models\AcademyLike;
+use App\Models\AcademySave;
+use App\Models\AcademySearchLog;
+use App\Models\AcademyUserProgress;
+use App\Support\AcademyAnalytics\AcademyAnalyticsEventType;
+use Illuminate\Console\Command;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Schema;
+
+final class AcademyAnalyticsHealthCommand extends Command
+{
+    protected $signature = 'academy:analytics-health {--json : Output machine-readable JSON}';
+
+    protected $description = 'Inspect Academy analytics collection health, rollup freshness, and privacy safeguards';
+
+    private const RETENTION_DAYS = 180;
+
+    public function handle(): int
+    {
+        $report = $this->buildReport();
+
+        if ((bool) $this->option('json')) {
+            $this->line(json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) ?: '{}');
+
+            return self::SUCCESS;
+        }
+
+        $this->line('Academy Analytics Health Check');
+        $this->line('==============================');
+        $this->newLine();
+        $this->line(sprintf('Events last 24h: %d', $report['events_last_24h']));
+        $this->line(sprintf('Events last 7d: %d', $report['events_last_7d']));
+        $this->line(sprintf('Latest event: %s', $report['latest_event_at'] ?? 'none'));
+        $this->line(sprintf('Latest rollup date: %s', $report['latest_rollup_date'] ?? 'none'));
+        $this->line(sprintf('Search logs: %d', $report['search_logs']));
+        $this->line(sprintf('Search clicks: %d', $report['search_clicks']));
+        $this->line(sprintf('Likes: %d', $report['likes']));
+        $this->line(sprintf('Saves: %d', $report['saves']));
+        $this->line(sprintf('Progress records: %d', $report['progress_records']));
+        $this->line(sprintf('Prompt copies: %d', $report['prompt_copies']));
+        $this->line(sprintf('Upgrade clicks: %d', $report['upgrade_clicks']));
+        $this->line(sprintf('Human events: %d', $report['human_events']));
+        $this->line(sprintf('Bot/admin events: %d', $report['bot_admin_events']));
+        $this->line(sprintf('Recent daily metric rows: %d', $report['recent_daily_metric_rows']));
+        $this->line(sprintf('Raw IP storage detected: %s', $report['raw_ip_storage_detected'] ? 'yes' : 'no'));
+        $this->line(sprintf('Events older than retention: %d', $report['events_older_than_retention']));
+        $this->newLine();
+
+        foreach ($report['warnings'] as $warning) {
+            $this->warn(sprintf('WARNING: %s', $warning));
+        }
+
+        $this->info(sprintf('Status: %s', $report['status']));
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function buildReport(): array
+    {
+        $now = now();
+        $last24Hours = $now->copy()->subDay();
+        $last7Days = $now->copy()->subDays(7);
+        $retentionCutoff = $now->copy()->subDays(self::RETENTION_DAYS);
+        $warnings = [];
+        $rawIpStorageDetected = $this->rawIpStorageDetected();
+        $eventsTableExists = Schema::hasTable('academy_events');
+        $metricsTableExists = Schema::hasTable('academy_content_metrics_daily');
+        $searchLogsTableExists = Schema::hasTable('academy_search_logs');
+        $likesTableExists = Schema::hasTable('academy_likes');
+        $savesTableExists = Schema::hasTable('academy_saves');
+        $progressTableExists = Schema::hasTable('academy_user_progress');
+
+        $latestEvent = $eventsTableExists ? AcademyEvent::query()->latest('occurred_at')->value('occurred_at') : null;
+        $latestRollup = $metricsTableExists ? AcademyContentMetricDaily::query()->latest('date')->value('date') : null;
+        $searchLogCount = $searchLogsTableExists ? AcademySearchLog::query()->count() : 0;
+        $searchClickCount = $searchLogsTableExists ? AcademySearchLog::query()->whereNotNull('clicked_content_id')->count() : 0;
+        $eventsOlderThanRetention = $eventsTableExists ? AcademyEvent::query()->where('occurred_at', '<', $retentionCutoff)->count() : 0;
+        $recentDailyMetricRows = $metricsTableExists
+            ? AcademyContentMetricDaily::query()->whereBetween('date', [$now->copy()->subDays(6)->toDateString(), $now->toDateString()])->count()
+            : 0;
+
+        $report = [
+            'events_last_24h' => $eventsTableExists ? AcademyEvent::query()->where('occurred_at', '>=', $last24Hours)->count() : 0,
+            'events_last_7d' => $eventsTableExists ? AcademyEvent::query()->where('occurred_at', '>=', $last7Days)->count() : 0,
+            'latest_event_at' => $latestEvent ? Carbon::parse((string) $latestEvent)->toDateTimeString() : null,
+            'latest_rollup_date' => $latestRollup ? Carbon::parse((string) $latestRollup)->toDateString() : null,
+            'search_logs' => $searchLogCount,
+            'search_clicks' => $searchClickCount,
+            'likes' => $likesTableExists ? AcademyLike::query()->count() : 0,
+            'saves' => $savesTableExists ? AcademySave::query()->count() : 0,
+            'progress_records' => $progressTableExists ? AcademyUserProgress::query()->count() : 0,
+            'prompt_copies' => $eventsTableExists ? AcademyEvent::query()->where('event_type', AcademyAnalyticsEventType::PROMPT_COPY)->count() : 0,
+            'upgrade_clicks' => $eventsTableExists ? AcademyEvent::query()->where('event_type', AcademyAnalyticsEventType::UPGRADE_CLICK)->count() : 0,
+            'human_events' => $eventsTableExists ? AcademyEvent::query()->where('is_bot', false)->where('is_admin', false)->where('is_suspicious', false)->count() : 0,
+            'bot_admin_events' => $eventsTableExists ? AcademyEvent::query()->where(function ($query): void {
+                $query->where('is_bot', true)->orWhere('is_admin', true)->orWhere('is_suspicious', true);
+            })->count() : 0,
+            'raw_ip_storage_detected' => $rawIpStorageDetected,
+            'events_older_than_retention' => $eventsOlderThanRetention,
+            'recent_daily_metric_rows' => $recentDailyMetricRows,
+            'retention_days' => self::RETENTION_DAYS,
+            'tables_present' => [
+                'academy_events' => $eventsTableExists,
+                'academy_content_metrics_daily' => $metricsTableExists,
+                'academy_search_logs' => $searchLogsTableExists,
+                'academy_likes' => $likesTableExists,
+                'academy_saves' => $savesTableExists,
+                'academy_user_progress' => $progressTableExists,
+            ],
+            'warnings' => [],
+            'status' => 'OK',
+        ];
+
+        foreach ($report['tables_present'] as $table => $present) {
+            if (! $present) {
+                $warnings[] = sprintf('Analytics table %s is missing.', $table);
+            }
+        }
+
+        if ($report['events_last_24h'] === 0) {
+            $warnings[] = 'No events received in last 24 hours.';
+        }
+
+        if ($report['events_last_7d'] === 0) {
+            $warnings[] = 'No events received in last 7 days.';
+        }
+
+        if ($report['latest_rollup_date'] === null) {
+            $warnings[] = 'No rollup rows exist yet.';
+        } elseif ($report['latest_rollup_date'] !== $now->toDateString()) {
+            $warnings[] = 'Rollup has not run for today.';
+        }
+
+        if ($searchLogCount > 0 && $searchClickCount === 0) {
+            $warnings[] = 'Search clicks are zero although search logs exist.';
+        }
+
+        if ($eventsOlderThanRetention > 0) {
+            $warnings[] = 'Raw events older than configured retention period exist.';
+        }
+
+        if ($recentDailyMetricRows === 0) {
+            $warnings[] = 'No daily metrics exist for recent days.';
+        }
+
+        if ($rawIpStorageDetected) {
+            $warnings[] = 'Raw IP storage indicators were found in Academy analytics tables.';
+        }
+
+        $report['warnings'] = $warnings;
+        $report['status'] = $warnings === [] ? 'OK' : 'WARNING';
+
+        return $report;
+    }
+
+    private function rawIpStorageDetected(): bool
+    {
+        foreach (['academy_events', 'academy_search_logs', 'academy_content_metrics_daily', 'academy_likes', 'academy_saves', 'academy_user_progress'] as $table) {
+            if (! Schema::hasTable($table)) {
+                continue;
+            }
+
+            foreach (['ip', 'ip_address', 'visitor_ip', 'raw_ip', 'remote_addr'] as $column) {
+                if (Schema::hasColumn($table, $column)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+}

app/Console/Commands/AcademyAnalyticsPruneEventsCommand.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\AcademyEvent;
+use Illuminate\Console\Command;
+
+final class AcademyAnalyticsPruneEventsCommand extends Command
+{
+    protected $signature = 'academy:analytics-prune-events {--days=180}';
+
+    protected $description = 'Delete old raw Academy analytics events while keeping daily rollups';
+
+    public function handle(): int
+    {
+        $days = max(1, (int) $this->option('days'));
+        $deleted = AcademyEvent::query()
+            ->where('occurred_at', '<', now()->subDays($days)->startOfDay())
+            ->delete();
+
+        $this->info(sprintf('Pruned %d Academy analytics event(s).', $deleted));
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/AcademyAnalyticsRecalculatePopularityCommand.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\AcademyContentMetricDaily;
+use App\Services\Academy\AcademyPopularityService;
+use Illuminate\Console\Command;
+
+final class AcademyAnalyticsRecalculatePopularityCommand extends Command
+{
+    protected $signature = 'academy:analytics-recalculate-popularity {--days=30}';
+
+    protected $description = 'Recalculate Academy daily popularity and conversion scores';
+
+    public function __construct(private readonly AcademyPopularityService $popularity)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $days = max(1, (int) $this->option('days'));
+
+        AcademyContentMetricDaily::query()
+            ->where('date', '>=', now()->subDays($days - 1)->toDateString())
+            ->chunkById(500, function ($rows): void {
+                foreach ($rows as $row) {
+                    $row->forceFill([
+                        'popularity_score' => $this->popularity->calculatePopularityScore($row->toArray()),
+                        'conversion_score' => $this->popularity->calculateConversionScore($row->toArray()),
+                    ])->save();
+                }
+            });
+
+        $this->info(sprintf('Recalculated Academy popularity for the last %d day(s).', $days));
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/AcademyAnalyticsRollupCommand.php

@@ -0,0 +1,258 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\AcademyContentMetricDaily;
+use App\Models\AcademyEvent;
+use App\Models\AcademyLike;
+use App\Models\AcademySave;
+use App\Models\AcademySearchLog;
+use App\Services\Academy\AcademyPopularityService;
+use App\Support\AcademyAnalytics\AcademyAnalyticsContentType;
+use Carbon\CarbonPeriod;
+use Illuminate\Console\Command;
+use Illuminate\Support\Carbon;
+
+final class AcademyAnalyticsRollupCommand extends Command
+{
+    protected $signature = 'academy:analytics-rollup {--date=} {--from=} {--to=}';
+
+    protected $description = 'Aggregate Academy analytics raw events and interaction records into daily content metrics';
+
+    public function __construct(private readonly AcademyPopularityService $popularity)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        [$from, $to] = $this->resolveRange();
+
+        foreach (CarbonPeriod::create($from, $to) as $date) {
+            $this->rollupDate(Carbon::parse($date));
+            $this->line(sprintf('Rolled up Academy analytics for %s.', Carbon::parse($date)->toDateString()));
+        }
+
+        return self::SUCCESS;
+    }
+
+    private function rollupDate(Carbon $date): void
+    {
+        $start = $date->copy()->startOfDay();
+        $end = $date->copy()->endOfDay();
+        $metrics = [];
+        $uniqueVisitors = [];
+        $engagedDurations = [];
+
+        AcademyEvent::query()
+            ->whereBetween('occurred_at', [$start, $end])
+            ->orderBy('id')
+            ->chunkById(1000, function ($events) use (&$metrics, &$uniqueVisitors, &$engagedDurations): void {
+                foreach ($events as $event) {
+                    if ($event->is_bot || $event->is_admin || $event->is_suspicious) {
+                        continue;
+                    }
+
+                    $key = $this->metricKey((string) ($event->content_type ?? ''), $event->content_id ? (int) $event->content_id : null);
+                    $this->ensureMetric($metrics, (string) ($event->content_type ?? ''), $event->content_id ? (int) $event->content_id : null, $key);
+
+                    $visitorKey = $event->user_id ? sprintf('user:%d', (int) $event->user_id) : trim((string) ($event->visitor_id ?? ''));
+                    if ($visitorKey !== '') {
+                        $uniqueVisitors[$key][$visitorKey] = true;
+                    }
+
+                    $eventType = (string) $event->event_type;
+                    if (in_array($eventType, ['academy_page_view', 'academy_content_view', 'academy_lesson_view', 'academy_course_view', 'academy_prompt_pack_view', 'academy_challenge_view'], true)) {
+                        $metrics[$key]['views']++;
+                        if ($event->is_logged_in) {
+                            $metrics[$key]['user_views']++;
+                        } else {
+                            $metrics[$key]['guest_views']++;
+                        }
+                        if ($event->is_subscriber) {
+                            $metrics[$key]['subscriber_views']++;
+                        }
+                    }
+
+                    if ($eventType === 'academy_engaged_view') {
+                        $metrics[$key]['engaged_views']++;
+                        $engagedDurations[$key][] = max(0, (int) ($event->metadata['engaged_seconds'] ?? 15));
+                    }
+
+                    if ($eventType === 'academy_scroll_50') {
+                        $metrics[$key]['scroll_50']++;
+                    }
+                    if ($eventType === 'academy_scroll_75') {
+                        $metrics[$key]['scroll_75']++;
+                    }
+                    if ($eventType === 'academy_scroll_100') {
+                        $metrics[$key]['scroll_100']++;
+                    }
+                    if ($eventType === 'academy_prompt_copy') {
+                        $metrics[$key]['prompt_copies']++;
+                    }
+                    if ($eventType === 'academy_prompt_negative_copy') {
+                        $metrics[$key]['negative_prompt_copies']++;
+                    }
+                    if (in_array($eventType, ['academy_lesson_started', 'academy_course_started', 'academy_challenge_started'], true)) {
+                        $metrics[$key]['starts']++;
+                    }
+                    if (in_array($eventType, ['academy_lesson_completed', 'academy_course_completed', 'academy_challenge_submitted'], true)) {
+                        $metrics[$key]['completions']++;
+                    }
+                    if ($eventType === 'academy_upgrade_click') {
+                        $metrics[$key]['upgrade_clicks']++;
+                    }
+                    if ($eventType === 'academy_premium_preview_view') {
+                        $metrics[$key]['premium_preview_views']++;
+                    }
+                    if ($eventType === 'academy_search_result_click') {
+                        $metrics[$key]['search_clicks']++;
+
+                        $searchKey = $this->metricKey(AcademyAnalyticsContentType::SEARCH, null);
+                        $this->ensureMetric($metrics, AcademyAnalyticsContentType::SEARCH, null, $searchKey);
+                        $metrics[$searchKey]['search_clicks']++;
+                    }
+                }
+            });
+
+        foreach (AcademyLike::query()->whereBetween('created_at', [$start, $end])->get() as $like) {
+            $key = $this->metricKey((string) $like->content_type, (int) $like->content_id);
+            $this->ensureMetric($metrics, (string) $like->content_type, (int) $like->content_id, $key);
+            $metrics[$key]['likes']++;
+        }
+
+        foreach (AcademySave::query()->whereBetween('created_at', [$start, $end])->get() as $save) {
+            $key = $this->metricKey((string) $save->content_type, (int) $save->content_id);
+            $this->ensureMetric($metrics, (string) $save->content_type, (int) $save->content_id, $key);
+            $metrics[$key]['saves']++;
+        }
+
+        foreach (AcademySearchLog::query()->whereBetween('created_at', [$start, $end])->get() as $searchLog) {
+            $key = $this->metricKey(AcademyAnalyticsContentType::SEARCH, null);
+            $this->ensureMetric($metrics, AcademyAnalyticsContentType::SEARCH, null, $key);
+            $metrics[$key]['search_impressions']++;
+            if ((int) $searchLog->results_count === 0) {
+                $metrics[$key]['bounce_count']++;
+            }
+
+            $visitorKey = $searchLog->user_id ? sprintf('user:%d', (int) $searchLog->user_id) : trim((string) ($searchLog->visitor_id ?? ''));
+            if ($visitorKey !== '') {
+                $uniqueVisitors[$key][$visitorKey] = true;
+            }
+        }
+
+        foreach ($metrics as $key => $metric) {
+            $metric['unique_visitors'] = isset($uniqueVisitors[$key]) ? count($uniqueVisitors[$key]) : 0;
+            $metric['avg_engaged_seconds'] = isset($engagedDurations[$key]) && $engagedDurations[$key] !== []
+                ? (int) round(array_sum($engagedDurations[$key]) / count($engagedDurations[$key]))
+                : null;
+            $metric['bounce_count'] = max((int) ($metric['bounce_count'] ?? 0), max(0, (int) $metric['views'] - (int) $metric['engaged_views']));
+            $metric['popularity_score'] = $this->popularity->calculatePopularityScore($metric);
+            $metric['conversion_score'] = $this->popularity->calculateConversionScore($metric);
+
+            AcademyContentMetricDaily::query()->upsert([
+                array_merge($metric, [
+                    'date' => $date->copy()->startOfDay(),
+                    'created_at' => now(),
+                    'updated_at' => now(),
+                ]),
+            ], ['date', 'content_type', 'content_id'], [
+                'views',
+                'unique_visitors',
+                'guest_views',
+                'user_views',
+                'subscriber_views',
+                'engaged_views',
+                'scroll_50',
+                'scroll_75',
+                'scroll_100',
+                'likes',
+                'saves',
+                'prompt_copies',
+                'negative_prompt_copies',
+                'starts',
+                'completions',
+                'upgrade_clicks',
+                'premium_preview_views',
+                'search_impressions',
+                'search_clicks',
+                'bounce_count',
+                'avg_engaged_seconds',
+                'popularity_score',
+                'conversion_score',
+                'updated_at',
+            ]);
+        }
+    }
+
+    /**
+     * @param  array<string, array<string, mixed>>  $metrics
+     */
+    private function ensureMetric(array &$metrics, string $contentType, ?int $contentId, string $key): void
+    {
+        if (isset($metrics[$key])) {
+            return;
+        }
+
+        $metrics[$key] = [
+            'content_type' => $contentType,
+            'content_id' => $contentId,
+            'views' => 0,
+            'unique_visitors' => 0,
+            'guest_views' => 0,
+            'user_views' => 0,
+            'subscriber_views' => 0,
+            'engaged_views' => 0,
+            'scroll_50' => 0,
+            'scroll_75' => 0,
+            'scroll_100' => 0,
+            'likes' => 0,
+            'saves' => 0,
+            'prompt_copies' => 0,
+            'negative_prompt_copies' => 0,
+            'starts' => 0,
+            'completions' => 0,
+            'upgrade_clicks' => 0,
+            'premium_preview_views' => 0,
+            'search_impressions' => 0,
+            'search_clicks' => 0,
+            'bounce_count' => 0,
+            'avg_engaged_seconds' => null,
+            'popularity_score' => 0,
+            'conversion_score' => 0,
+        ];
+    }
+
+    private function metricKey(string $contentType, ?int $contentId): string
+    {
+        return sprintf('%s:%s', $contentType, $contentId ?? 'none');
+    }
+
+    /**
+     * @return array{0: Carbon, 1: Carbon}
+     */
+    private function resolveRange(): array
+    {
+        $date = $this->option('date');
+        $from = $this->option('from');
+        $to = $this->option('to');
+
+        if (is_string($date) && trim($date) !== '') {
+            $resolved = Carbon::parse($date)->startOfDay();
+
+            return [$resolved, $resolved->copy()];
+        }
+
+        $resolvedFrom = is_string($from) && trim($from) !== ''
+            ? Carbon::parse($from)->startOfDay()
+            : now()->subDay()->startOfDay();
+        $resolvedTo = is_string($to) && trim($to) !== ''
+            ? Carbon::parse($to)->startOfDay()
+            : $resolvedFrom->copy();
+
+        return [$resolvedFrom, $resolvedTo];
+    }
+}

app/Console/Commands/AcademyBillingHealthCommand.php

@@ -0,0 +1,288 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Services\Academy\AcademyBillingPlanService;
+use Illuminate\Console\Command;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\Facades\Schema;
+
+final class AcademyBillingHealthCommand extends Command
+{
+    protected $signature = 'academy:billing-health
+        {--json : Output machine-readable JSON}
+        {--strict : Exit non-zero when blocking issues are found}';
+
+    protected $description = 'Inspect Academy Stripe billing deployment readiness, config completeness, and Cashier route wiring';
+
+    public function __construct(
+        private readonly AcademyBillingPlanService $plans,
+    ) {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $report = $this->buildReport();
+
+        if ((bool) $this->option('json')) {
+            $this->line((string) json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+
+            return $this->exitCodeFor($report);
+        }
+
+        $this->line('Academy Billing Health Check');
+        $this->line('============================');
+        $this->newLine();
+        $this->line(sprintf('Environment: %s', $report['environment']));
+        $this->line(sprintf('App URL: %s', $report['app_url'] ?? 'unset'));
+        $this->line(sprintf('Academy enabled: %s', $report['academy_enabled'] ? 'yes' : 'no'));
+        $this->line(sprintf('Academy billing enabled: %s', $report['academy_billing_enabled'] ? 'yes' : 'no'));
+        $this->line(sprintf('Subscription name: %s', $report['subscription_name']));
+        $this->line(sprintf('Cashier path: %s', $report['cashier_path']));
+        $this->line(sprintf('Cashier webhook route: %s', $report['routes']['cashier_webhook']['present'] ? ($report['routes']['cashier_webhook']['url'] ?? 'present') : 'missing'));
+        $this->line(sprintf('Academy pricing route: %s', $report['routes']['academy_pricing']['present'] ? ($report['routes']['academy_pricing']['url'] ?? 'present') : 'missing'));
+        $this->line(sprintf('Academy billing account route: %s', $report['routes']['academy_billing_account']['present'] ? ($report['routes']['academy_billing_account']['url'] ?? 'present') : 'missing'));
+        $this->line(sprintf('Stripe key configured: %s', $report['stripe']['publishable_key_configured'] ? 'yes' : 'no'));
+        $this->line(sprintf('Stripe secret configured: %s', $report['stripe']['secret_key_configured'] ? 'yes' : 'no'));
+        $this->line(sprintf('Webhook secret configured: %s', $report['stripe']['webhook_secret_configured'] ? 'yes' : 'no'));
+        $this->line(sprintf('Cashier currency: %s', $report['stripe']['currency'] ?: 'unset'));
+        $this->line(sprintf('Cashier locale: %s', $report['stripe']['currency_locale'] ?: 'unset'));
+        $this->line(sprintf('Configured plans: %d', $report['configured_plan_count']));
+        $this->line(sprintf('Plans missing Stripe price IDs: %d', count($report['missing_plan_keys'])));
+        $this->line(sprintf('Billing tables present: %s', $report['tables']['subscriptions'] && $report['tables']['subscription_items'] && $report['tables']['academy_billing_events'] ? 'yes' : 'no'));
+        $this->line(sprintf('User billing columns present: %s', $report['users_billing_columns_present'] ? 'yes' : 'no'));
+        $this->newLine();
+
+        foreach ($report['blockers'] as $blocker) {
+            $this->error(sprintf('BLOCKER: %s', $blocker));
+        }
+
+        foreach ($report['warnings'] as $warning) {
+            $this->warn(sprintf('WARNING: %s', $warning));
+        }
+
+        if ($report['plan_summaries'] !== []) {
+            $this->newLine();
+            $this->line('Plans');
+            $this->line('-----');
+
+            foreach ($report['plan_summaries'] as $plan) {
+                $this->line(sprintf(
+                    '%s: tier=%s interval=%s price_id=%s',
+                    $plan['key'],
+                    $plan['tier'],
+                    $plan['interval'],
+                    $plan['configured'] ? 'configured' : 'missing'
+                ));
+            }
+        }
+
+        $this->newLine();
+        $this->info(sprintf('Status: %s', $report['status']));
+
+        return $this->exitCodeFor($report);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function buildReport(): array
+    {
+        $stripeKey = (string) config('cashier.key', '');
+        $stripeSecret = (string) config('cashier.secret', env('STRIPE_SECRET', ''));
+        $webhookSecret = (string) config('cashier.webhook.secret', env('STRIPE_WEBHOOK_SECRET', ''));
+        $currency = trim((string) config('cashier.currency', env('CASHIER_CURRENCY', '')));
+        $currencyLocale = trim((string) config('cashier.currency_locale', env('CASHIER_CURRENCY_LOCALE', '')));
+        $academyEnabled = (bool) config('academy.enabled', true);
+        $billingEnabled = $this->plans->enabled();
+        $missingPlanKeys = $this->plans->missingPriceIds();
+        $routes = [
+            'cashier_webhook' => $this->routeStatus('cashier.webhook'),
+            'academy_pricing' => $this->routeStatus('academy.pricing'),
+            'academy_billing_account' => $this->routeStatus('academy.billing.account'),
+            'academy_billing_portal' => $this->routeStatus('academy.billing.portal'),
+            'admin_academy_billing' => $this->routeStatus('admin.academy.billing'),
+        ];
+        $tables = [
+            'users' => Schema::hasTable('users'),
+            'subscriptions' => Schema::hasTable('subscriptions'),
+            'subscription_items' => Schema::hasTable('subscription_items'),
+            'academy_billing_events' => Schema::hasTable('academy_billing_events'),
+        ];
+        $userBillingColumns = [
+            'stripe_id' => $tables['users'] && Schema::hasColumn('users', 'stripe_id'),
+            'pm_type' => $tables['users'] && Schema::hasColumn('users', 'pm_type'),
+            'pm_last_four' => $tables['users'] && Schema::hasColumn('users', 'pm_last_four'),
+            'trial_ends_at' => $tables['users'] && Schema::hasColumn('users', 'trial_ends_at'),
+        ];
+        $planSummaries = collect(array_keys($this->plans->plans()))
+            ->map(function (string $key): array {
+                $plan = $this->plans->plan($key);
+
+                return [
+                    'key' => $key,
+                    'tier' => (string) ($plan['tier'] ?? 'free'),
+                    'interval' => (string) ($plan['interval'] ?? 'monthly'),
+                    'configured' => (bool) ($plan['configured'] ?? false),
+                ];
+            })
+            ->values()
+            ->all();
+
+        $blockers = [];
+        $warnings = [];
+
+        if (! $academyEnabled) {
+            $warnings[] = 'SKINBASE_ACADEMY_ENABLED is disabled, so billing cannot be reached by users.';
+        }
+
+        if (! $billingEnabled) {
+            $warnings[] = 'ACADEMY_BILLING_ENABLED is disabled. Checkout routes will stay unavailable until rollout is enabled.';
+        }
+
+        if (! $this->isConfiguredSecret($stripeKey, 'pk_')) {
+            $blockers[] = 'STRIPE_KEY is missing or still using a placeholder value.';
+        }
+
+        if (! $this->isConfiguredSecret($stripeSecret, 'sk_')) {
+            $blockers[] = 'STRIPE_SECRET is missing or still using a placeholder value.';
+        }
+
+        if (! $this->isConfiguredSecret($webhookSecret, 'whsec_')) {
+            $blockers[] = 'STRIPE_WEBHOOK_SECRET is missing or still using a placeholder value.';
+        }
+
+        if ($currency === '') {
+            $blockers[] = 'CASHIER_CURRENCY is not configured.';
+        }
+
+        if ($currencyLocale === '') {
+            $warnings[] = 'CASHIER_CURRENCY_LOCALE is not configured.';
+        }
+
+        if ($missingPlanKeys !== []) {
+            $blockers[] = 'Stripe price IDs are missing for: '.implode(', ', $missingPlanKeys).'.';
+        }
+
+        if (! $routes['cashier_webhook']['present']) {
+            $blockers[] = 'Cashier webhook route is missing; Stripe cannot sync subscriptions.';
+        }
+
+        if (! $routes['academy_pricing']['present']) {
+            $blockers[] = 'Academy pricing route is missing.';
+        }
+
+        if (! $routes['academy_billing_account']['present']) {
+            $blockers[] = 'Academy billing account route is missing.';
+        }
+
+        foreach ($tables as $table => $present) {
+            if (! $present) {
+                $blockers[] = sprintf('Required billing table %s is missing.', $table);
+            }
+        }
+
+        foreach ($userBillingColumns as $column => $present) {
+            if (! $present) {
+                $blockers[] = sprintf('Required users.%s billing column is missing.', $column);
+            }
+        }
+
+        if (! $routes['admin_academy_billing']['present']) {
+            $warnings[] = 'Moderation Academy billing overview route is missing.';
+        }
+
+        if (Arr::where($planSummaries, fn (array $plan): bool => $plan['configured'] === false) === []) {
+            $warnings[] = 'All configured Academy plans have Stripe price IDs. Verify they are live-mode IDs before production rollout.';
+        }
+
+        $invalidPlanKeys = collect(array_keys($this->plans->plans()))
+            ->filter(function (string $key): bool {
+                $plan = $this->plans->plan($key);
+
+                return $plan !== null && ($plan['configured'] ?? false) && ! ($plan['price_id_valid'] ?? false);
+            })
+            ->values()
+            ->all();
+
+        if ($invalidPlanKeys !== []) {
+            $blockers[] = 'Stripe price IDs are malformed for: '.implode(', ', $invalidPlanKeys).'. Use real price object IDs that start with price_.';
+        }
+
+        $status = $blockers !== []
+            ? 'BLOCKED'
+            : ($warnings !== [] ? 'WARNING' : 'OK');
+
+        return [
+            'environment' => app()->environment(),
+            'app_url' => config('app.url'),
+            'academy_enabled' => $academyEnabled,
+            'academy_billing_enabled' => $billingEnabled,
+            'subscription_name' => $this->plans->subscriptionName(),
+            'cashier_path' => (string) config('cashier.path', 'stripe'),
+            'stripe' => [
+                'publishable_key_configured' => $this->isConfiguredSecret($stripeKey, 'pk_'),
+                'secret_key_configured' => $this->isConfiguredSecret($stripeSecret, 'sk_'),
+                'webhook_secret_configured' => $this->isConfiguredSecret($webhookSecret, 'whsec_'),
+                'currency' => $currency,
+                'currency_locale' => $currencyLocale,
+            ],
+            'configured_plan_count' => count($planSummaries),
+            'missing_plan_keys' => $missingPlanKeys,
+            'invalid_plan_keys' => $invalidPlanKeys,
+            'plan_summaries' => $planSummaries,
+            'routes' => $routes,
+            'tables' => $tables,
+            'user_billing_columns' => $userBillingColumns,
+            'users_billing_columns_present' => ! in_array(false, $userBillingColumns, true),
+            'blockers' => array_values(array_unique($blockers)),
+            'warnings' => array_values(array_unique($warnings)),
+            'status' => $status,
+        ];
+    }
+
+    /**
+     * @return array{present: bool, url: string|null}
+     */
+    private function routeStatus(string $name): array
+    {
+        if (! Route::has($name)) {
+            return [
+                'present' => false,
+                'url' => null,
+            ];
+        }
+
+        return [
+            'present' => true,
+            'url' => route($name),
+        ];
+    }
+
+    private function isConfiguredSecret(string $value, string $expectedPrefix): bool
+    {
+        $value = trim($value);
+
+        if ($value === '' || ! str_starts_with($value, $expectedPrefix)) {
+            return false;
+        }
+
+        return ! str_contains(strtolower($value), 'xxx');
+    }
+
+    /**
+     * @param array<string, mixed> $report
+     */
+    private function exitCodeFor(array $report): int
+    {
+        if ((bool) $this->option('strict') && $report['status'] === 'BLOCKED') {
+            return self::FAILURE;
+        }
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/BuildWorldWebStoryAssetsCommand.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\WorldWebStory;
+use App\Services\WebStories\WorldWebStoryAssetService;
+use Illuminate\Console\Command;
+
+final class BuildWorldWebStoryAssetsCommand extends Command
+{
+    protected $signature = 'skinbase:webstories:build-assets
+        {story? : Story ID or slug}
+        {--published : Limit batch mode to published stories}
+        {--visible : Limit batch mode to stories currently visible on the public site}
+        {--limit=100 : Maximum stories to process in batch mode}
+        {--force : Rebuild already populated asset paths}
+        {--dry-run : Report changes without saving them}';
+
+    protected $description = 'Backfill poster, logo, and page background assets for World Web Stories';
+
+    public function handle(WorldWebStoryAssetService $assets): int
+    {
+        $storyKey = $this->argument('story');
+        $force = (bool) $this->option('force');
+        $dryRun = (bool) $this->option('dry-run');
+
+        if ($storyKey !== null && trim((string) $storyKey) !== '') {
+            $story = $this->resolveStory((string) $storyKey);
+
+            if (! $story instanceof WorldWebStory) {
+                $this->error(sprintf('Web story [%s] was not found.', (string) $storyKey));
+
+                return self::FAILURE;
+            }
+
+            return $this->buildOne($assets, $story, $force, $dryRun);
+        }
+
+        return $this->buildBatch($assets, $force, $dryRun, max(1, (int) $this->option('limit')));
+    }
+
+    private function buildOne(WorldWebStoryAssetService $assets, WorldWebStory $story, bool $force, bool $dryRun): int
+    {
+        $result = $assets->buildAssets($story, force: $force, dryRun: $dryRun);
+
+        $this->line(sprintf('Story [%d] %s', (int) $story->id, (string) $story->slug));
+        $this->line($result['updated'] ? 'Assets updated.' : 'No asset changes needed.');
+
+        foreach ((array) $result['story'] as $field => $value) {
+            $this->line(sprintf(' - story.%s = %s', (string) $field, (string) $value));
+        }
+
+        foreach ((array) $result['pages'] as $pageId => $changes) {
+            foreach ((array) $changes as $field => $value) {
+                $this->line(sprintf(' - page.%d.%s = %s', (int) $pageId, (string) $field, (string) $value));
+            }
+        }
+
+        return self::SUCCESS;
+    }
+
+    private function buildBatch(WorldWebStoryAssetService $assets, bool $force, bool $dryRun, int $limit): int
+    {
+        $processed = 0;
+        $updated = 0;
+
+        $this->storyQuery()
+            ->limit($limit)
+            ->get()
+            ->each(function (WorldWebStory $story) use ($assets, $force, $dryRun, &$processed, &$updated): void {
+                $processed++;
+                $result = $assets->buildAssets($story, force: $force, dryRun: $dryRun);
+
+                if ($result['updated']) {
+                    $updated++;
+                }
+
+                $this->line(sprintf('[%d] %s -> %s', (int) $story->id, (string) $story->slug, $result['updated'] ? 'updated' : 'unchanged'));
+            });
+
+        $this->info(sprintf('Done. processed=%d updated=%d', $processed, $updated));
+
+        return self::SUCCESS;
+    }
+
+    private function storyQuery()
+    {
+        return WorldWebStory::query()
+            ->when((bool) $this->option('published'), fn ($query) => $query->published())
+            ->when((bool) $this->option('visible'), fn ($query) => $query->visible())
+            ->orderByDesc('published_at')
+            ->orderByDesc('id');
+    }
+
+    private function resolveStory(string $value): ?WorldWebStory
+    {
+        return WorldWebStory::query()
+            ->when(is_numeric($value), fn ($query) => $query->where('id', (int) $value), fn ($query) => $query->where('slug', $value))
+            ->first();
+    }
+}

app/Console/Commands/GenerateAcademyPromptThumbnailsCommand.php

@@ -0,0 +1,390 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\AcademyPromptTemplate;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Storage;
+use RuntimeException;
+use Throwable;
+
+final class GenerateAcademyPromptThumbnailsCommand extends Command
+{
+    private const PROMPT_PREVIEW_PREFIX = 'academy-prompts/previews';
+
+    /**
+     * @var array<string, int>
+     */
+    private const VARIANT_WIDTHS = [
+        'thumb' => 480,
+        'md' => 960,
+    ];
+
+    private const PREVIEW_WEBP_QUALITY = 84;
+
+    private const LESSON_MEDIA_WEBP_QUALITY = 85;
+
+    protected $signature = 'academy:prompts:generate-missing-thumbnails
+        {--id=* : Restrict to one or more prompt IDs}
+        {--slug=* : Restrict to one or more prompt slugs}
+        {--limit= : Stop after processing this many prompts}
+        {--force : Regenerate variants even when they already exist}
+        {--dry-run : Report planned thumbnail work without writing files or saving prompt JSON}';
+
+    protected $description = 'Generate missing prompt preview and comparison thumbnails for existing Academy prompts';
+
+    public function handle(): int
+    {
+        if (! function_exists('imagecreatefromstring') || ! function_exists('imagewebp')) {
+            $this->error('GD WebP support is required to generate prompt thumbnails.');
+
+            return self::FAILURE;
+        }
+
+        $ids = collect((array) $this->option('id'))
+            ->map(static fn (mixed $id): int => (int) $id)
+            ->filter(static fn (int $id): bool => $id > 0)
+            ->values()
+            ->all();
+
+        $slugs = collect((array) $this->option('slug'))
+            ->map(static fn (mixed $slug): string => trim((string) $slug))
+            ->filter(static fn (string $slug): bool => $slug !== '')
+            ->values()
+            ->all();
+
+        $limit = $this->option('limit') !== null ? max(1, (int) $this->option('limit')) : null;
+        $force = (bool) $this->option('force');
+        $dryRun = (bool) $this->option('dry-run');
+
+        $query = AcademyPromptTemplate::query()
+            ->select(['id', 'slug', 'title', 'preview_image', 'tool_notes'])
+            ->orderBy('id');
+
+        if ($ids !== []) {
+            $query->whereIn('id', $ids);
+        }
+
+        if ($slugs !== []) {
+            $query->whereIn('slug', $slugs);
+        }
+
+        $processed = 0;
+        $changed = 0;
+        $generatedVariants = 0;
+        $plannedVariants = 0;
+        $skipped = 0;
+        $failed = 0;
+
+        $query->chunkById(100, function ($prompts) use ($limit, $force, $dryRun, &$processed, &$changed, &$generatedVariants, &$plannedVariants, &$skipped, &$failed) {
+            foreach ($prompts as $prompt) {
+                if ($limit !== null && $processed >= $limit) {
+                    return false;
+                }
+
+                try {
+                    $result = $this->backfillPrompt($prompt, $force, $dryRun);
+
+                    $generatedVariants += (int) ($result['generated_variants'] ?? 0);
+                    $plannedVariants += (int) ($result['planned_variants'] ?? 0);
+
+                    if (($result['changed'] ?? false) === true) {
+                        $changed++;
+                    } else {
+                        $skipped++;
+                    }
+                } catch (Throwable $e) {
+                    $failed++;
+                    $this->warn(sprintf('Prompt %d (%s) failed: %s', (int) $prompt->id, (string) $prompt->slug, $e->getMessage()));
+                }
+
+                $processed++;
+            }
+
+            return true;
+        });
+
+        $this->info(sprintf(
+            'Prompt thumbnail backfill complete. processed=%d changed=%d generated_variants=%d planned_variants=%d skipped=%d failed=%d',
+            $processed,
+            $changed,
+            $generatedVariants,
+            $plannedVariants,
+            $skipped,
+            $failed,
+        ));
+
+        return $failed > 0 ? self::FAILURE : self::SUCCESS;
+    }
+
+    /**
+     * @return array{changed:bool,generated_variants:int,planned_variants:int}
+     */
+    private function backfillPrompt(AcademyPromptTemplate $prompt, bool $force, bool $dryRun): array
+    {
+        $generatedVariants = 0;
+        $plannedVariants = 0;
+        $changed = false;
+
+        $previewResult = $this->ensureManagedImageVariants((string) ($prompt->preview_image ?? ''), $force, $dryRun);
+        $generatedVariants += $previewResult['generated_variants'];
+        $plannedVariants += $previewResult['planned_variants'];
+        $changed = $changed || $previewResult['changed'];
+
+        $notes = is_array($prompt->tool_notes) ? $prompt->tool_notes : [];
+        $nextNotes = [];
+
+        foreach ($notes as $note) {
+            if (! is_array($note)) {
+                $nextNotes[] = $note;
+                continue;
+            }
+
+            $noteResult = $this->ensurePromptComparisonNoteVariants($note, $force, $dryRun);
+            $generatedVariants += $noteResult['generated_variants'];
+            $plannedVariants += $noteResult['planned_variants'];
+            $changed = $changed || $noteResult['changed'];
+            $nextNotes[] = $noteResult['note'];
+        }
+
+        if ($changed && ! $dryRun && $nextNotes !== $notes) {
+            $prompt->forceFill([
+                'tool_notes' => $nextNotes,
+            ])->save();
+        }
+
+        return [
+            'changed' => $changed,
+            'generated_variants' => $generatedVariants,
+            'planned_variants' => $plannedVariants,
+        ];
+    }
+
+    /**
+     * @param  array<string, mixed>  $note
+     * @return array{note:array<string, mixed>,changed:bool,generated_variants:int,planned_variants:int}
+     */
+    private function ensurePromptComparisonNoteVariants(array $note, bool $force, bool $dryRun): array
+    {
+        $imagePath = trim((string) ($note['image_path'] ?? ''));
+
+        if (! $this->isManagedLessonMediaPath($imagePath)) {
+            return [
+                'note' => $note,
+                'changed' => false,
+                'generated_variants' => 0,
+                'planned_variants' => 0,
+            ];
+        }
+
+        $variants = $this->ensureManagedImageVariants($imagePath, $force, $dryRun);
+        $thumbPath = $variants['thumb_path'] ?? '';
+
+        if ($thumbPath === '') {
+            $thumbPath = $imagePath;
+        }
+
+        $nextNote = $note;
+        $currentThumbPath = trim((string) ($note['thumb_path'] ?? ''));
+
+        if ($currentThumbPath !== $thumbPath) {
+            $nextNote['thumb_path'] = $thumbPath;
+            $variants['changed'] = true;
+        }
+
+        return [
+            'note' => $nextNote,
+            'changed' => (bool) $variants['changed'],
+            'generated_variants' => (int) $variants['generated_variants'],
+            'planned_variants' => (int) $variants['planned_variants'],
+        ];
+    }
+
+    /**
+     * @return array{thumb_path:string,changed:bool,generated_variants:int,planned_variants:int}
+     */
+    private function ensureManagedImageVariants(string $path, bool $force, bool $dryRun): array
+    {
+        $path = trim($path);
+
+        if (! $this->isManagedPromptPreviewPath($path) && ! $this->isManagedLessonMediaPath($path)) {
+            return [
+                'thumb_path' => '',
+                'changed' => false,
+                'generated_variants' => 0,
+                'planned_variants' => 0,
+            ];
+        }
+
+        $source = $this->openManagedImage($path);
+
+        try {
+            $generatedVariants = 0;
+            $plannedVariants = 0;
+            $changed = false;
+            $thumbPath = $path;
+
+            foreach (self::VARIANT_WIDTHS as $variant => $targetWidth) {
+                $status = $this->ensureVariantForWidth(
+                    $source['image'],
+                    $source['width'],
+                    $source['height'],
+                    $path,
+                    $variant,
+                    $targetWidth,
+                    $force,
+                    $dryRun,
+                );
+
+                if ($variant === 'thumb' && $source['width'] > $targetWidth) {
+                    $thumbPath = $this->variantPath($path, 'thumb');
+                }
+
+                if ($status === 'generated') {
+                    $generatedVariants++;
+                    $changed = true;
+                }
+
+                if ($status === 'planned') {
+                    $plannedVariants++;
+                    $changed = true;
+                }
+            }
+
+            return [
+                'thumb_path' => $thumbPath,
+                'changed' => $changed,
+                'generated_variants' => $generatedVariants,
+                'planned_variants' => $plannedVariants,
+            ];
+        } finally {
+            imagedestroy($source['image']);
+        }
+    }
+
+    /**
+     * @return array{image:\GdImage,width:int,height:int}
+     */
+    private function openManagedImage(string $path): array
+    {
+        $disk = Storage::disk($this->storageDisk());
+
+        if (! $disk->exists($path)) {
+            throw new RuntimeException(sprintf('Source image is missing: %s', $path));
+        }
+
+        $binary = $disk->get($path);
+
+        if (! is_string($binary) || $binary === '') {
+            throw new RuntimeException(sprintf('Source image could not be read: %s', $path));
+        }
+
+        $image = @imagecreatefromstring($binary);
+
+        if (! $image instanceof \GdImage) {
+            throw new RuntimeException(sprintf('Source image is not a supported raster image: %s', $path));
+        }
+
+        if (! imageistruecolor($image)) {
+            imagepalettetotruecolor($image);
+        }
+
+        imagealphablending($image, true);
+        imagesavealpha($image, true);
+
+        return [
+            'image' => $image,
+            'width' => imagesx($image),
+            'height' => imagesy($image),
+        ];
+    }
+
+    private function ensureVariantForWidth(\GdImage $source, int $sourceWidth, int $sourceHeight, string $sourcePath, string $variant, int $targetWidth, bool $force, bool $dryRun): string
+    {
+        if ($sourceWidth <= $targetWidth || $sourceWidth < 1 || $sourceHeight < 1) {
+            return 'skipped';
+        }
+
+        $variantPath = $this->variantPath($sourcePath, $variant);
+        $disk = Storage::disk($this->storageDisk());
+
+        if (! $force && $disk->exists($variantPath)) {
+            return 'skipped';
+        }
+
+        if ($dryRun) {
+            return 'planned';
+        }
+
+        $targetHeight = max(1, (int) round(($sourceHeight / $sourceWidth) * $targetWidth));
+        $canvas = imagecreatetruecolor($targetWidth, $targetHeight);
+
+        if (! $canvas instanceof \GdImage) {
+            throw new RuntimeException(sprintf('Could not allocate variant canvas for %s', $sourcePath));
+        }
+
+        imagealphablending($canvas, false);
+        imagesavealpha($canvas, true);
+        $transparent = imagecolorallocatealpha($canvas, 0, 0, 0, 127);
+        imagefilledrectangle($canvas, 0, 0, $targetWidth, $targetHeight, $transparent);
+        imagecopyresampled($canvas, $source, 0, 0, 0, 0, $targetWidth, $targetHeight, $sourceWidth, $sourceHeight);
+
+        try {
+            ob_start();
+            $converted = imagewebp($canvas, null, $this->qualityForPath($sourcePath));
+            $webpBinary = ob_get_clean();
+
+            if (! $converted || ! is_string($webpBinary) || $webpBinary === '') {
+                throw new RuntimeException(sprintf('Could not encode %s variant for %s', $variant, $sourcePath));
+            }
+
+            $disk->put($variantPath, $webpBinary, ['visibility' => 'public']);
+        } finally {
+            imagedestroy($canvas);
+        }
+
+        return 'generated';
+    }
+
+    private function variantPath(string $path, string $variant): string
+    {
+        $directory = pathinfo($path, PATHINFO_DIRNAME);
+        $filename = pathinfo($path, PATHINFO_FILENAME);
+        $baseFilename = preg_replace('/-(thumb|md)$/', '', $filename) ?? $filename;
+
+        return sprintf('%s/%s-%s.webp', $directory, $baseFilename, $variant);
+    }
+
+    private function isManagedPromptPreviewPath(string $path): bool
+    {
+        return $this->isLocalPath($path) && str_starts_with($path, self::PROMPT_PREVIEW_PREFIX . '/');
+    }
+
+    private function isManagedLessonMediaPath(string $path): bool
+    {
+        return $this->isLocalPath($path)
+            && (str_starts_with($path, 'academy/lessons/body/') || str_starts_with($path, 'academy/lessons/covers/'));
+    }
+
+    private function isLocalPath(string $path): bool
+    {
+        return $path !== ''
+            && ! str_starts_with($path, 'http://')
+            && ! str_starts_with($path, 'https://')
+            && ! str_starts_with($path, '/');
+    }
+
+    private function storageDisk(): string
+    {
+        return (string) config('uploads.object_storage.disk', 's3');
+    }
+
+    private function qualityForPath(string $path): int
+    {
+        return $this->isManagedPromptPreviewPath($path)
+            ? self::PREVIEW_WEBP_QUALITY
+            : self::LESSON_MEDIA_WEBP_QUALITY;
+    }
+}

app/Console/Commands/GenerateWorldWebStoriesCommand.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\World;
+use App\Services\WebStories\WorldWebStoryGenerator;
+use Illuminate\Console\Command;
+use Illuminate\Validation\ValidationException;
+
+final class GenerateWorldWebStoriesCommand extends Command
+{
+    protected $signature = 'skinbase:webstories:generate
+        {world? : World ID or slug}
+        {--all : Generate stories in batch mode}
+        {--pages=7 : Number of pages to generate (5-10)}
+        {--limit=25 : Maximum worlds to process in batch mode}
+        {--force : Rebuild an existing story for the target world}
+        {--publish : Publish immediately after generation if validation passes}
+        {--dry-run : Preview generation without saving anything}';
+
+    protected $description = 'Generate standalone AMP Web Stories from Skinbase Worlds';
+
+    public function handle(WorldWebStoryGenerator $generator): int
+    {
+        $worldKey = $this->argument('world');
+        $force = (bool) $this->option('force');
+        $publish = (bool) $this->option('publish');
+        $dryRun = (bool) $this->option('dry-run');
+        $pages = max(5, min(10, (int) $this->option('pages')));
+
+        if ($worldKey !== null && trim((string) $worldKey) !== '') {
+            $world = $this->resolveWorld((string) $worldKey);
+
+            if (! $world instanceof World) {
+                $this->error(sprintf('World [%s] was not found.', (string) $worldKey));
+
+                return self::FAILURE;
+            }
+
+            return $this->generateOne($generator, $world, $pages, $force, $publish, $dryRun);
+        }
+
+        if (! (bool) $this->option('all')) {
+            $this->error('Provide a world ID/slug or pass --all for batch generation.');
+
+            return self::INVALID;
+        }
+
+        return $this->generateBatch($generator, $pages, $force, $publish, $dryRun, max(1, (int) $this->option('limit')));
+    }
+
+    private function generateOne(WorldWebStoryGenerator $generator, World $world, int $pages, bool $force, bool $publish, bool $dryRun): int
+    {
+        try {
+            $result = $generator->generateFromWorld($world, null, $pages, $force, $publish, $dryRun);
+        } catch (ValidationException $exception) {
+            foreach ($exception->errors() as $messages) {
+                foreach ($messages as $message) {
+                    $this->error((string) $message);
+                }
+            }
+
+            return self::FAILURE;
+        }
+
+        $story = $result['story'];
+        $validation = $result['validation'];
+
+        $this->info(sprintf(
+            '%s story for world [%s] -> /web-stories/%s (%d pages)',
+            $result['created'] ? 'Created' : 'Updated',
+            (string) $world->slug,
+            (string) $story->slug,
+            (int) $validation['page_count'],
+        ));
+
+        foreach ((array) $validation['warnings'] as $warning) {
+            $this->warn(' - ' . $warning);
+        }
+
+        foreach ((array) $validation['errors'] as $error) {
+            $this->error(' - ' . $error);
+        }
+
+        return $validation['valid'] || ! $publish ? self::SUCCESS : self::FAILURE;
+    }
+
+    private function generateBatch(WorldWebStoryGenerator $generator, int $pages, bool $force, bool $publish, bool $dryRun, int $limit): int
+    {
+        $processed = 0;
+        $created = 0;
+        $updated = 0;
+        $failed = 0;
+
+        $query = World::query()
+            ->published()
+            ->orderByDesc('published_at')
+            ->orderByDesc('id');
+
+        if (! $force) {
+            $query->whereDoesntHave('webStories');
+        }
+
+        $query->limit($limit)->get()->each(function (World $world) use ($generator, $pages, $force, $publish, $dryRun, &$processed, &$created, &$updated, &$failed): void {
+            $processed++;
+
+            try {
+                $result = $generator->generateFromWorld($world, null, $pages, $force, $publish, $dryRun);
+                $result['created'] ? $created++ : $updated++;
+                $this->line(sprintf('[%d] %s -> %s', (int) $world->id, (string) $world->slug, (string) $result['story']->slug));
+            } catch (ValidationException $exception) {
+                $failed++;
+                $first = collect($exception->errors())->flatten()->first();
+                $this->error(sprintf('[%d] %s failed: %s', (int) $world->id, (string) $world->slug, (string) $first));
+            }
+        });
+
+        $this->info(sprintf('Done. processed=%d created=%d updated=%d failed=%d', $processed, $created, $updated, $failed));
+
+        return $failed === 0 ? self::SUCCESS : self::FAILURE;
+    }
+
+    private function resolveWorld(string $value): ?World
+    {
+        return World::query()
+            ->when(is_numeric($value), fn ($query) => $query->where('id', (int) $value), fn ($query) => $query->where('slug', $value))
+            ->first();
+    }
+}

app/Console/Commands/HealthCheckCommand.php

@@ -5,8 +5,10 @@ declare(strict_types=1);
 namespace App\Console\Commands;
 
 use App\Models\Artwork;
+use App\Services\Sitemaps\SitemapReleaseManager;
 use App\Services\Vision\ArtworkVisionImageUrl;
 use Illuminate\Console\Command;
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Redis;
@@ -25,10 +27,10 @@ use Throwable;
 class HealthCheckCommand extends Command
 {
     protected $signature = 'health:check
-        {--only= : Run only a named check (mysql|redis|cache|meilisearch|qdrant|reverb|vision|horizon|webserver|phpfpm|paths|ram|disk|load|s3|failed_jobs|queue_backlog|ssl|scheduler|log_errors|app)}
+        {--only= : Run only a named check (mysql|redis|cache|meilisearch|qdrant|reverb|vision|horizon|webserver|phpfpm|paths|ram|disk|load|s3|failed_jobs|queue_backlog|ssl|scheduler|sitemap|log_errors|app)}
         {--json  : Output results as JSON}';
 
-    protected $description = 'Check health of all critical services (MySQL, Redis, Cache, Meilisearch, Qdrant, Reverb, Vision, Horizon, Nginx, PHP-FPM, writable paths, RAM, disk, load, S3/Contabo, failed jobs, queue backlog, SSL, scheduler, log errors, App).';
+    protected $description = 'Check health of all critical services (MySQL, Redis, Cache, Meilisearch, Qdrant, Reverb, Vision, Horizon, Nginx, PHP-FPM, writable paths, RAM, disk, load, S3/Contabo, failed jobs, queue backlog, SSL, scheduler, sitemap, log errors, App).';
 
     /** Collected results: [name => [status, message, details]] */
     private array $results = [];
@@ -57,6 +59,7 @@ class HealthCheckCommand extends Command
             'queue_backlog' => fn () => $this->checkQueueBacklog(),
             'ssl'         => fn () => $this->checkSsl(),
             'scheduler'   => fn () => $this->checkScheduler(),
+            'sitemap'     => fn () => $this->checkSitemap(),
             'log_errors'  => fn () => $this->checkLogErrors(),
             'app'         => fn () => $this->checkApp(),
         ];
@@ -1041,6 +1044,51 @@ class HealthCheckCommand extends Command
         }
     }
 
+    private function checkSitemap(): void
+    {
+        try {
+            $releases = app(SitemapReleaseManager::class)->listReleases();
+
+            if ($releases === []) {
+                $this->failCheck('sitemap', 'No sitemap releases found. Run `php artisan skinbase:sitemaps:publish` to build one.');
+                return;
+            }
+
+            $latest = $releases[0];
+            $releaseId = (string) ($latest['release_id'] ?? 'unknown');
+            $builtAtRaw = (string) ($latest['built_at'] ?? $latest['published_at'] ?? '');
+
+            if ($builtAtRaw === '') {
+                $this->warn_check('sitemap', "Latest sitemap release [{$releaseId}] is missing a build timestamp.", [
+                    'release_id' => $releaseId,
+                    'status' => (string) ($latest['status'] ?? 'unknown'),
+                ]);
+                return;
+            }
+
+            $builtAt = Carbon::parse($builtAtRaw);
+            $ageSeconds = max(0, $builtAt->diffInSeconds(now()));
+            $builtAtLabel = $builtAt->toAtomString();
+            $details = [
+                'release_id' => $releaseId,
+                'built_at' => $builtAtLabel,
+                'age_seconds' => $ageSeconds,
+                'status' => (string) ($latest['status'] ?? 'unknown'),
+            ];
+            $message = "Latest sitemap release [{$releaseId}] built at {$builtAtLabel} ({$ageSeconds}s ago).";
+
+            if ($ageSeconds > 72 * 3600) {
+                $this->failCheck('sitemap', 'Sitemap build is stale — ' . $message, $details);
+            } elseif ($ageSeconds > 36 * 3600) {
+                $this->warn_check('sitemap', 'Sitemap build is getting old — ' . $message, $details);
+            } else {
+                $this->pass('sitemap', $message, $details);
+            }
+        } catch (Throwable $e) {
+            $this->warn_check('sitemap', 'Could not inspect sitemap releases: ' . $e->getMessage());
+        }
+    }
+
     private function checkLogErrors(): void
     {
         $logFile = storage_path('logs/laravel.log');

app/Console/Commands/ValidateWorldWebStoriesCommand.php

@@ -0,0 +1,163 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Models\WorldWebStory;
+use App\Services\WebStories\WorldWebStoryValidationService;
+use Illuminate\Console\Command;
+use Symfony\Component\Process\Process;
+
+final class ValidateWorldWebStoriesCommand extends Command
+{
+    protected $signature = 'skinbase:webstories:validate
+        {story? : Story ID or slug}
+        {--published : Limit batch mode to published stories}
+        {--visible : Limit batch mode to publicly visible stories}
+        {--limit=100 : Maximum stories to validate in batch mode}
+        {--amp : Also run amphtml-validator against the public story URL}
+        {--fail-warnings : Treat validation warnings as failures}';
+
+    protected $description = 'Validate World Web Stories for publish safety and optional AMP validity';
+
+    public function handle(WorldWebStoryValidationService $validation): int
+    {
+        $storyKey = $this->argument('story');
+
+        if ($storyKey !== null && trim((string) $storyKey) !== '') {
+            $story = $this->resolveStory((string) $storyKey);
+
+            if (! $story instanceof WorldWebStory) {
+                $this->error(sprintf('Web story [%s] was not found.', (string) $storyKey));
+
+                return self::FAILURE;
+            }
+
+            return $this->validateOne($validation, $story);
+        }
+
+        return $this->validateBatch($validation, max(1, (int) $this->option('limit')));
+    }
+
+    private function validateOne(WorldWebStoryValidationService $validation, WorldWebStory $story): int
+    {
+        $result = $validation->validate($story);
+        $ampErrors = $this->ampErrors($story);
+
+        $this->line(sprintf('Story [%d] %s', (int) $story->id, (string) $story->slug));
+
+        foreach ((array) $result['warnings'] as $warning) {
+            $this->warn(' - ' . $warning);
+        }
+
+        foreach ((array) $result['errors'] as $error) {
+            $this->error(' - ' . $error);
+        }
+
+        foreach ($ampErrors as $ampError) {
+            $this->error(' - AMP: ' . $ampError);
+        }
+
+        if ($result['valid'] && $ampErrors === []) {
+            $this->info('Validation passed.');
+
+            return self::SUCCESS;
+        }
+
+        return self::FAILURE;
+    }
+
+    private function validateBatch(WorldWebStoryValidationService $validation, int $limit): int
+    {
+        $processed = 0;
+        $failed = 0;
+
+        $this->storyQuery()
+            ->limit($limit)
+            ->get()
+            ->each(function (WorldWebStory $story) use ($validation, &$processed, &$failed): void {
+                $processed++;
+                $result = $validation->validate($story);
+                $ampErrors = $this->ampErrors($story);
+                $warningsFail = (bool) $this->option('fail-warnings') && count((array) $result['warnings']) > 0;
+                $hasFailure = ! $result['valid'] || $warningsFail || $ampErrors !== [];
+
+                if ($hasFailure) {
+                    $failed++;
+                }
+
+                $this->line(sprintf('[%d] %s -> %s', (int) $story->id, (string) $story->slug, $hasFailure ? 'invalid' : 'valid'));
+
+                foreach ((array) $result['warnings'] as $warning) {
+                    $this->warn(' - ' . $warning);
+                }
+
+                foreach ((array) $result['errors'] as $error) {
+                    $this->error(' - ' . $error);
+                }
+
+                foreach ($ampErrors as $ampError) {
+                    $this->error(' - AMP: ' . $ampError);
+                }
+            });
+
+        $this->info(sprintf('Done. processed=%d failed=%d', $processed, $failed));
+
+        return $failed === 0 ? self::SUCCESS : self::FAILURE;
+    }
+
+    private function storyQuery()
+    {
+        return WorldWebStory::query()
+            ->when((bool) $this->option('published'), fn ($query) => $query->published())
+            ->when((bool) $this->option('visible'), fn ($query) => $query->visible())
+            ->orderByDesc('published_at')
+            ->orderByDesc('id');
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function ampErrors(WorldWebStory $story): array
+    {
+        if (! (bool) $this->option('amp')) {
+            return [];
+        }
+
+        if (! $story->exists || ! $story->publicUrl()) {
+            return ['Story has no public URL to validate.'];
+        }
+
+        $probe = new Process(['npx', 'amphtml-validator', '--version'], base_path(), null, null, 60);
+        $probe->run();
+
+        if (! $probe->isSuccessful()) {
+            return ['amphtml-validator is not available via npx.'];
+        }
+
+        $process = new Process(['npx', 'amphtml-validator', $story->publicUrl()], base_path(), null, null, 120);
+        $process->run();
+
+        if ($process->isSuccessful()) {
+            return [];
+        }
+
+        $output = trim($process->getErrorOutput() ?: $process->getOutput());
+
+        if ($output === '') {
+            return ['AMP validator failed without output.'];
+        }
+
+        $lines = preg_split('/\r\n|\r|\n/', $output);
+
+        return $lines === false || $lines === [] ? ['AMP validator failed.'] : $lines;
+    }
+
+    private function resolveStory(string $value): ?WorldWebStory
+    {
+        return WorldWebStory::query()
+            ->when(is_numeric($value), fn ($query) => $query->where('id', (int) $value), fn ($query) => $query->where('slug', $value))
+            ->first();
+    }
+}

app/Console/Kernel.php

@@ -31,10 +31,13 @@ use App\Console\Commands\PublishScheduledArtworksCommand;
 use App\Console\Commands\PublishScheduledNewsCommand;
 use App\Console\Commands\PublishScheduledNovaCardsCommand;
 use App\Console\Commands\BuildSitemapsCommand;
+use App\Console\Commands\BuildWorldWebStoryAssetsCommand;
 use App\Console\Commands\ListSitemapReleasesCommand;
+use App\Console\Commands\GenerateWorldWebStoriesCommand;
 use App\Console\Commands\PublishSitemapsCommand;
 use App\Console\Commands\RollbackSitemapReleaseCommand;
 use App\Console\Commands\SyncCollectionLifecycleCommand;
+use App\Console\Commands\ValidateWorldWebStoriesCommand;
 use App\Console\Commands\ValidateSitemapsCommand;
 use App\Console\Commands\AuditArtworkDownloadFilesCommand;
 use App\Console\Commands\InspectArtworkOriginalCommand;
@@ -58,6 +61,9 @@ class Kernel extends ConsoleKernel
         \App\Console\Commands\ResetAllUserPasswords::class,
         CleanupUploadsCommand::class,
         BuildSitemapsCommand::class,
+        GenerateWorldWebStoriesCommand::class,
+        BuildWorldWebStoryAssetsCommand::class,
+        ValidateWorldWebStoriesCommand::class,
         PublishSitemapsCommand::class,
         ListSitemapReleasesCommand::class,
         RollbackSitemapReleaseCommand::class,