chore: install laravel telescope as dev-only debugging dashboard

Installs laravel/telescope ^5.0 (v5.12.5) as a dev-dependency.
Three-layer production safety adapted to Laravel 11 layout (no
Kernel.php; routing/schedule in bootstrap/app.php +
routes/console.php):

  1. composer.json `extra.laravel.dont-discover` lists
     laravel/telescope. After editing, `php artisan package:discover`
     regenerates bootstrap/cache/packages.php — without this step
     the auto-discovery cache still registers the vendor provider.
  2. AppServiceProvider::register() gates registration to local +
     testing environments. Registers BOTH the vendor
     Laravel\Telescope\TelescopeServiceProvider (routes, migrations,
     publishing) AND the project's App\Providers\TelescopeService
     Provider (gate + filter) — they're sibling classes that extend
     ServiceProvider independently, not parent/child, so both must
     register for the dashboard to work. bootstrap/providers.php
     deliberately does NOT list either Telescope provider.
  3. .env TELESCOPE_ENABLED flag (false in .env.example). Runtime
     toggle that disables Telescope even when the providers are
     registered.

Production safety verified via simulated APP_ENV=production check:
confirms no Telescope-* providers are loaded.

Authorization: viewTelescope gate restricts dashboard to users
with the super_admin Spatie Permission role. Even in local
environments, only super_admin can view. Default was an email
allow-list stub — replaced with `$user->hasRole('super_admin')`.

Pruning: Schedule::command('telescope:prune --hours=48') added in
routes/console.php (Laravel 11's schedule location), environment-
gated to local + testing only.

Documentation: /dev-docs/TELESCOPE.md added; CLAUDE.md gets a
Development-tooling section. The doc explicitly calls out the
dual-provider registration (vendor + app) which differs from the
single-provider pattern in older Laravel versions.

Migrations applied: telescope_entries, telescope_entries_tags,
telescope_monitoring tables. Route registration verified in local
(42 telescope.* routes).

Tests: 1208/1208 passing — Telescope loads in the testing
environment as well, so the suite exercised it without issues.

Deployment note (flag for separate docs): a production operator
who runs `php artisan migrate` manually will still apply the
Telescope migrations — but because the providers never register
in production, the tables stay empty.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

api/app/Providers/AppServiceProvider.php

@@ -84,6 +84,19 @@ class AppServiceProvider extends ServiceProvider
         );
 
         $this->app->singleton(PurposeRegistry::class);
+
+        // Telescope is a dev-only debugging dashboard. Three-layer
+        // defense keeps it out of production: composer `dont-discover`
+        // suppresses auto-registration, this block gates manual
+        // registration to local/testing, and TELESCOPE_ENABLED in .env
+        // is the runtime toggle (see /dev-docs/TELESCOPE.md). The vendor
+        // service provider registers routes/migrations/publishing;
+        // App\Providers\TelescopeServiceProvider attaches the gate +
+        // filter. Both must register for the dashboard to work.
+        if ($this->app->environment('local', 'testing')) {
+            $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
+            $this->app->register(\App\Providers\TelescopeServiceProvider::class);
+        }
     }
 
     public function boot(): void

api/app/Providers/TelescopeServiceProvider.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Providers;
+
+use App\Models\User;
+use Illuminate\Support\Facades\Gate;
+use Laravel\Telescope\IncomingEntry;
+use Laravel\Telescope\Telescope;
+use Laravel\Telescope\TelescopeApplicationServiceProvider;
+
+class TelescopeServiceProvider extends TelescopeApplicationServiceProvider
+{
+    /**
+     * Register any application services.
+     */
+    public function register(): void
+    {
+        // Telescope::night();
+
+        $this->hideSensitiveRequestDetails();
+
+        $isLocal = $this->app->environment('local');
+
+        Telescope::filter(function (IncomingEntry $entry) use ($isLocal) {
+            return $isLocal ||
+                   $entry->isReportableException() ||
+                   $entry->isFailedRequest() ||
+                   $entry->isFailedJob() ||
+                   $entry->isScheduledTask() ||
+                   $entry->hasMonitoredTag();
+        });
+    }
+
+    /**
+     * Prevent sensitive request details from being logged by Telescope.
+     */
+    protected function hideSensitiveRequestDetails(): void
+    {
+        if ($this->app->environment('local')) {
+            return;
+        }
+
+        Telescope::hideRequestParameters(['_token']);
+
+        Telescope::hideRequestHeaders([
+            'cookie',
+            'x-csrf-token',
+            'x-xsrf-token',
+        ]);
+    }
+
+    /**
+     * Register the Telescope gate.
+     *
+     * This gate determines who can access Telescope in non-local environments.
+     */
+    protected function gate(): void
+    {
+        Gate::define('viewTelescope', function (?User $user) {
+            return $user !== null && $user->hasRole('super_admin');
+        });
+    }
+}