fix(observability): make Sentry route errors, releases and environments usable

Route crashes were all reported as one synthetic error with the boundary's
stack, so Sentry grouped every crash into a single issue. They now keep the
original error type and code-location frames while the message, which can
carry user text, is still replaced.

Sentry events now carry the commit SHA as release and VERCEL_ENV as
environment, so release health works and previews stop reporting as
production. Hidden source maps are uploaded and deleted when
SENTRY_AUTH_TOKEN, SENTRY_ORG and SENTRY_PROJECT are set.

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

Author: Programcode

docs/architecture.md

@@ -105,7 +105,7 @@ Historical provider pricing evidence is retained under [`docs/pricing-snapshots/
 
 ## Observability
 
-Client startup loads Sentry and PostHog asynchronously when configured. Product events and exceptions use the privacy-filtering facade in [`src/lib/observability.ts`](../src/lib/observability.ts), so SDK loading or failure cannot block rendering. Vercel Analytics and Speed Insights run only in the web build and load outside the application render boundary.
+Client startup loads Sentry and PostHog asynchronously when configured. Product events and exceptions use the privacy-filtering facade in [`src/lib/observability.ts`](../src/lib/observability.ts), so SDK loading or failure cannot block rendering. Sentry events carry the build's commit SHA as the release and the Vercel environment name. Route crashes keep the original error type and stack frames but replace the message, which can carry user text. Vercel Analytics and Speed Insights run only in the web build and load outside the application render boundary.
 
 CI and staging must not upload authenticated browser captures. Logging must not expose tokens, provider keys, user content, or protected staging values.
 

docs/development.md

@@ -57,6 +57,8 @@ The checked-in [`.env.example`](../.env.example) contains optional client observ
 - `VITE_POSTHOG_KEY`
 - `VITE_POSTHOG_HOST`
 
+Production builds also read the Sentry build variables `SENTRY_AUTH_TOKEN`, `SENTRY_ORG` and `SENTRY_PROJECT`. Local builds leave them unset and skip source map upload. See [operations.md](operations.md#secrets).
+
 The frontend Supabase environment is resolved by [`src/lib/supabase/env.ts`](../src/lib/supabase/env.ts), not by those variables. Public browser configuration is distinct from server secrets.
 
 Never put service-role keys, AI provider keys, Stripe secrets, webhook secrets, demo-code peppers, or integrity secrets in Vite variables. Any `VITE_*` value can reach the browser bundle.

docs/operations.md

@@ -115,6 +115,8 @@ Never place server secrets in `VITE_*`, screenshots, traces, logs, comments, com
 
 GitHub Actions secrets: `LIVE_OPENROUTER_API_KEY` and `LIVE_EXA_API_KEY` for live provider tests, and `PROD_CANARY_EMAIL` and `PROD_CANARY_PASSWORD` for the production canary account. The public anon key is the `PROD_SUPABASE_ANON_KEY` repository variable. To rotate the canary password, set it with the Supabase Auth admin API and pipe it into `gh secret set` over stdin.
 
+Vercel build variables for Sentry source maps: `SENTRY_AUTH_TOKEN` (an organization token with release and source map upload scope), `SENTRY_ORG` and `SENTRY_PROJECT` (slugs). When all three are set, [`vite.config.ts`](../vite.config.ts) builds hidden source maps, uploads them for the release, and deletes them from `dist/`. When any is missing, the build emits no source maps. A failed upload logs an error but does not fail the build. The release is `VERCEL_GIT_COMMIT_SHA` (then `GITHUB_SHA`, then `git rev-parse HEAD`), and the Sentry environment is `VERCEL_ENV`, so preview deployments report as `preview`. Both need Vercel's system environment variables enabled.
+
 ## Rollback
 
 Choose rollback before changing production: