feat(observability): Sentry monitoring API + Web (ADR-024)

Intégration Sentry SaaS pour error monitoring + replay sur les 2 apps.

API (apps/api) :
- start/sentry.ts : init au plus tôt dans bin/server.ts (avant Ignitor)
  pour capturer les erreurs de bootstrap. No-op si SENTRY_DSN_API absent.
- app/exceptions/handler.ts:report : captureException sur les 5xx avec
  tags { url, method, status } et user.id (PII minimisée). 4xx filtrés
  par beforeSend dans start/sentry.ts (validation, auth invalide = bruit).
- start/env.ts : SENTRY_DSN_API + APP_VERSION optionnels.
- bin/server.ts : import #start/sentry en 1er.
- @sentry/node + @sentry/profiling-node ajoutés au package.json.

Web (apps/web) :
- src/lib/sentry.ts : init au plus tôt dans main.tsx, BrowserTracing +
  Replay (0% session, 100% sur erreur — économie quota free tier).
  maskAllText + blockAllMedia pour privacy par défaut.
- src/lib/auth.ts : Sentry.setUser({ id }) au login, setUser(null) au
  logout (corrélation cross-stack des erreurs front avec un user).
- src/main.tsx : ErrorBoundary autour de l'app avec FallbackError UX.
- vite.config.ts : @sentry/vite-plugin uploads les sourcemaps + les
  SUPPRIME du dist/ final (filesToDeleteAfterUpload) pour ne pas leak
  le code source via nginx en prod. Helper resolveAppVersion() pour
  injecter le sha git en dev (le shell n'étant pas évaluable dans .env).
- src/lib/env.ts : VITE_SENTRY_DSN_WEB + VITE_APP_VERSION optionnels.
- .env.development : VITE_SENTRY_DSN_WEB (préfixé correctement pour
  être exposé par Vite — l'ancienne SENTRY_DSN ne marchait pas).
- @sentry/react + @sentry/vite-plugin ajoutés au package.json.

CI Gitea :
- deploy-api.yml : kubectl set env APP_VERSION=${{ github.sha }}
  runtime → release Sentry trackable au commit pour l'API.
- deploy-web.yml : build-args VITE_SENTRY_DSN_WEB, VITE_APP_VERSION,
  SENTRY_AUTH_TOKEN, SENTRY_ORG injectés depuis les secrets Gitea.
- Dockerfile.web : ARG correspondants + propagation au stage build.

Privacy / sécurité (cf. ADR-024) :
- captureException tags : ctx.route?.pattern (pas l'URL réelle) →
  les codes OAuth (?code=...) et tokens de check-in n'apparaissent
  jamais dans les tags Sentry indexés.
- Sentry user context = user.id UUID seulement, pas d'email/nom.
- Sourcemaps en prod : uploadées à Sentry, supprimées du bundle.
- 4xx filtrées en amont (beforeSend) ET en aval (handler.ts:report).
- DSN public (by-design) commit-able, AUTH_TOKEN secret CI uniquement.

Sample rates (free tier 5K events / 50 replays par mois) :
- traces : 10% prod, 100% dev
- profiles : 100% (sampled par traces)
- replay session : 0% (économie quota)
- replay sur erreur : 100% (debug post-mortem)

Pré-requis runtime à configurer hors-repo :
- Secret K3s rubis-app-secrets : SENTRY_DSN_API
- Secrets Gitea Actions : SENTRY_DSN_WEB, SENTRY_AUTH_TOKEN, SENTRY_ORG

ADR-024 logué dans docs/decisions.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitea/workflows/deploy-api.yml

@@ -82,4 +82,9 @@ jobs:
             --type='json' \
             -p="[{\"op\":\"replace\",\"path\":\"/spec/template/spec/initContainers/0/image\",\"value\":\"$REGISTRY/$IMAGE:${{ github.sha }}\"}]"
 
+          # APP_VERSION runtime — utilisé par Sentry comme nom de release pour
+          # corréler les erreurs API avec un sha git précis (cf. start/sentry.ts).
+          kubectl -n $NAMESPACE set env deployment/$DEPLOYMENT \
+            APP_VERSION=${{ github.sha }}
+
           kubectl -n $NAMESPACE rollout status deployment/$DEPLOYMENT --timeout=300s

.gitea/workflows/deploy-web.yml

@@ -51,10 +51,17 @@ jobs:
           cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE }}:cache,mode=max
           # Vars Vite injectées dans le bundle au build time. Pour staging,
           # créer un workflow séparé avec d'autres VITE_API_URL.
+          # Les VITE_SENTRY_* + SENTRY_* viennent des secrets CI Gitea
+          # (cf. README.md déploiement). Si SENTRY_AUTH_TOKEN est vide,
+          # le plugin Vite est skip et les sourcemaps ne sont pas uploadées.
           build-args: |
             VITE_API_URL=https://app.rubis.pro
             VITE_PUBLIC_LANDING_URL=https://rubis.pro
             VITE_USE_MOCKS=false
+            VITE_SENTRY_DSN_WEB=${{ secrets.SENTRY_DSN_WEB }}
+            VITE_APP_VERSION=${{ github.sha }}
+            SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }}
+            SENTRY_ORG=${{ secrets.SENTRY_ORG }}
 
       - name: Install kubectl
         run: |

Dockerfile.web

@@ -17,6 +17,14 @@ ARG NGINX_VERSION=1.27-alpine
 ARG VITE_API_URL=https://app.rubis.pro
 ARG VITE_PUBLIC_LANDING_URL=https://rubis.pro
 ARG VITE_USE_MOCKS=false
+# Sentry — DSN baked dans le bundle pour init côté SPA (cf. lib/sentry.ts).
+# VITE_APP_VERSION = sha git pour identifier la release dans Sentry.
+ARG VITE_SENTRY_DSN_WEB=
+ARG VITE_APP_VERSION=
+# Sentry CI uniquement — utilisé par @sentry/vite-plugin pour upload des
+# sourcemaps (cf. vite.config.ts). Ne fuit pas en runtime (consommé au build).
+ARG SENTRY_AUTH_TOKEN=
+ARG SENTRY_ORG=rubis
 
 # -----------------------------------------------------------------------------
 # build — Vite produit dist/
@@ -47,13 +55,23 @@ COPY apps/web ./apps/web
 ARG VITE_API_URL
 ARG VITE_PUBLIC_LANDING_URL
 ARG VITE_USE_MOCKS
+ARG VITE_SENTRY_DSN_WEB
+ARG VITE_APP_VERSION
+ARG SENTRY_AUTH_TOKEN
+ARG SENTRY_ORG
 
 # vite build direct (le `tsc -b` du script build plante sans cache .tsbuildinfo
 # à cause de @tanstack/router-core ; le typecheck strict est en CI séparée).
 # Les VITE_* env vars sont lues par Vite à la compile via process.env.
+# SENTRY_AUTH_TOKEN active sentryVitePlugin (upload sourcemaps).
 RUN VITE_API_URL=$VITE_API_URL \
     VITE_PUBLIC_LANDING_URL=$VITE_PUBLIC_LANDING_URL \
     VITE_USE_MOCKS=$VITE_USE_MOCKS \
+    VITE_SENTRY_DSN_WEB=$VITE_SENTRY_DSN_WEB \
+    VITE_APP_VERSION=$VITE_APP_VERSION \
+    APP_VERSION=$VITE_APP_VERSION \
+    SENTRY_AUTH_TOKEN=$SENTRY_AUTH_TOKEN \
+    SENTRY_ORG=$SENTRY_ORG \
     pnpm --filter @rubis/web exec vite build
 
 # -----------------------------------------------------------------------------

apps/api/app/exceptions/handler.ts

@@ -1,5 +1,6 @@
 import app from '@adonisjs/core/services/app'
 import { type HttpContext, ExceptionHandler } from '@adonisjs/core/http'
+import * as Sentry from '@sentry/node'
 
 /**
  * Exception handler API JSON-only. Normalise toutes les erreurs vers la
@@ -87,6 +88,32 @@ export default class HttpExceptionHandler extends ExceptionHandler {
   }
 
   async report(error: unknown, ctx: HttpContext) {
+    // Capture seulement les vraies erreurs serveur (pas les 4xx attendues
+    // type validation, auth invalide, etc. — déjà filtrées par beforeSend
+    // dans start/sentry.ts mais on garde une 2ème ligne de défense ici).
+    if (error instanceof Error) {
+      const status = (error as { status?: number }).status
+      const isServerError = !status || status >= 500
+      if (isServerError) {
+        // SÉCURITÉ : on log le PATTERN de la route ("/api/v1/checkin/:token/paid")
+        // et pas l'URL réelle, sinon les codes OAuth (?code=...) et les
+        // tokens de check-in (dans le path) fuiteraient dans les tags
+        // Sentry, qui sont indexés et consultables par toute l'équipe.
+        // ctx.request.url(false) strip la query string en fallback.
+        const route = (ctx as unknown as { route?: { pattern?: string } }).route
+        const safeUrl = route?.pattern ?? ctx.request.url(false)
+        Sentry.captureException(error, {
+          tags: {
+            url: safeUrl,
+            method: ctx.request.method(),
+            status: status?.toString() ?? '500',
+          },
+          user: ctx.auth?.user
+            ? { id: String((ctx.auth.user as { id: unknown }).id) }
+            : undefined,
+        })
+      }
+    }
     return super.report(error, ctx)
   }
 }

apps/api/bin/server.ts

@@ -10,6 +10,11 @@
 */
 
 await import('reflect-metadata')
+
+// Sentry init AVANT toute autre logique applicative pour capturer même
+// les erreurs de bootstrap (cf. apps/api/start/sentry.ts).
+await import('#start/sentry')
+
 const { Ignitor, prettyPrintError } = await import('@adonisjs/core')
 
 /**

apps/api/package.json

@@ -78,6 +78,8 @@
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^2.0.8",
     "@react-pdf/renderer": "^4.5.1",
+    "@sentry/node": "^10.52.0",
+    "@sentry/profiling-node": "^10.52.0",
     "@tuyau/core": "^1.2.2",
     "@vinejs/vine": "^4.3.1",
     "better-sqlite3": "^12.9.0",

apps/api/start/env.ts

@@ -93,5 +93,14 @@ export default await Env.create(new URL('../', import.meta.url), {
   | Variables for configuring the limiter package
   |----------------------------------------------------------
   */
-  LIMITER_STORE: Env.schema.enum(['redis', 'memory'] as const)
+  LIMITER_STORE: Env.schema.enum(['redis', 'memory'] as const),
+
+  /*
+  |----------------------------------------------------------
+  | Sentry — error monitoring (cf. apps/api/start/sentry.ts)
+  |----------------------------------------------------------
+  | Optionnels en dev local. Si non définis, Sentry est no-op.
+  */
+  SENTRY_DSN_API: Env.schema.string.optional(),
+  APP_VERSION: Env.schema.string.optional(),
 })

apps/api/start/sentry.ts

@@ -0,0 +1,44 @@
+/*
+|--------------------------------------------------------------------------
+| Sentry — error monitoring & performance
+|--------------------------------------------------------------------------
+|
+| Init au plus tôt dans le boot (avant Ignitor) pour capturer aussi les
+| erreurs de bootstrap. Lit `process.env` directement car le service Env
+| d'Adonis n'est pas encore chargé à ce stade.
+|
+| Si SENTRY_DSN_API n'est pas défini (dev local typique), Sentry est
+| simplement no-op — aucun appel réseau.
+|
+| Cf. ADR-024 — choix Sentry SaaS, free tier, 2 projects
+| (rubis-api / rubis-web).
+*/
+
+import * as Sentry from '@sentry/node'
+import { nodeProfilingIntegration } from '@sentry/profiling-node'
+
+const dsn = process.env.SENTRY_DSN_API
+const environment = process.env.NODE_ENV ?? 'development'
+const release = process.env.APP_VERSION ?? 'dev'
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    environment,
+    release,
+    // 10% en prod, 100% en dev pour debug
+    tracesSampleRate: environment === 'production' ? 0.1 : 1.0,
+    profilesSampleRate: 1.0,
+    integrations: [nodeProfilingIntegration()],
+    // Filtre les erreurs 4xx attendues, garde les 5xx
+    beforeSend(event, hint) {
+      const error = hint.originalException as { status?: number } | undefined
+      if (error?.status && error.status >= 400 && error.status < 500) {
+        return null
+      }
+      return event
+    },
+  })
+}
+
+export { Sentry }

apps/web/.env.development

@@ -1,3 +1,7 @@
 VITE_API_URL=http://localhost:3333
 VITE_PUBLIC_LANDING_URL=http://localhost:8080
 VITE_USE_MOCKS=false
+# Sentry — DSN PUBLIC (peut être commit, c'est by-design dans @sentry/react)
+VITE_SENTRY_DSN_WEB=https://2e62d7ef1a5aad166d6e0ec9a6e31580@o4511353951354880.ingest.de.sentry.io/4511353959874640
+# VITE_APP_VERSION : injecté par le CI (sha git court) ou via vite.config.ts
+# en dev. Pas de $(...) ici — Vite n'évalue pas le shell dans .env.

apps/web/package.json

@@ -27,6 +27,7 @@
     "@radix-ui/react-slot": "^1.1.2",
     "@radix-ui/react-tooltip": "^1.1.8",
     "@rubis/shared": "workspace:*",
+    "@sentry/react": "^10.52.0",
     "@tanstack/react-form": "^1.0.0",
     "@tanstack/react-query": "^5.66.0",
     "@tanstack/react-query-devtools": "^5.66.0",
@@ -47,6 +48,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@resvg/resvg-js": "^2.6.2",
+    "@sentry/vite-plugin": "^5.2.1",
     "@tailwindcss/vite": "^4.1.0",
     "@tanstack/router-cli": "^1.114.3",
     "@tanstack/router-plugin": "^1.114.3",

apps/web/src/lib/auth.ts

@@ -1,10 +1,16 @@
 import { useSyncExternalStore } from "react";
+import * as Sentry from "@sentry/react";
 import type { User } from "@rubis/shared";
 
 /**
  * Auth store — token en mémoire seulement (pas localStorage).
  * Le refresh token vit en cookie httpOnly côté API, invisible ici.
  * Cf. ADR-017 et /docs/tech/frontend.md §7.
+ *
+ * Sentry user context : on attache `user.id` (pas l'email, pas le nom
+ * — minimisation PII) sur les events Sentry au login, et on clear au
+ * logout. Permet de corréler une stack trace à un user spécifique sans
+ * leak d'info personnelle.
  */
 
 type AuthState = {
@@ -32,11 +38,13 @@ class AuthStore {
 
   setSession(accessToken: string, user: User): void {
     this.state = { accessToken, user };
+    Sentry.setUser({ id: user.id });
     this.notify();
   }
 
   clear(): void {
     this.state = { accessToken: null, user: null };
+    Sentry.setUser(null);
     this.notify();
   }
 

apps/web/src/lib/env.ts

@@ -11,6 +11,9 @@ const envSchema = z.object({
     .enum(["true", "false"])
     .default("false")
     .transform((v) => v === "true"),
+  // Sentry — optionnel en dev local, recommandé en prod (cf. lib/sentry.ts)
+  VITE_SENTRY_DSN_WEB: z.string().url().optional(),
+  VITE_APP_VERSION: z.string().optional(),
 });
 
 const parsed = envSchema.safeParse(import.meta.env);

apps/web/src/lib/sentry.ts

@@ -0,0 +1,42 @@
+/**
+ * Sentry — error monitoring + replay côté SPA.
+ *
+ * Init au plus tôt dans main.tsx (avant tout autre import non-essentiel)
+ * pour capturer même les erreurs de bootstrap (incluant les validations
+ * d'env qui throw dans lib/env.ts).
+ *
+ * Lit `import.meta.env` directement plutôt que via lib/env.ts pour ne pas
+ * dépendre de la validation Zod qui peut elle-même throw.
+ *
+ * Si VITE_SENTRY_DSN_WEB n'est pas défini, Sentry est no-op.
+ *
+ * Cf. ADR-024 — choix Sentry SaaS, free tier, project rubis-web.
+ */
+
+import * as Sentry from "@sentry/react";
+
+const dsn = import.meta.env.VITE_SENTRY_DSN_WEB as string | undefined;
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    environment: import.meta.env.MODE,
+    release: (import.meta.env.VITE_APP_VERSION as string | undefined) ?? "dev",
+    // 10% en prod, 100% en dev pour debug
+    tracesSampleRate: import.meta.env.PROD ? 0.1 : 1.0,
+    // Pas de replay sur sessions sans erreur (économie de quota free tier)
+    replaysSessionSampleRate: 0,
+    // Replay systématique quand une erreur se produit — capture les 30s
+    // précédant le crash pour debug post-mortem
+    replaysOnErrorSampleRate: 1.0,
+    integrations: [
+      Sentry.browserTracingIntegration(),
+      Sentry.replayIntegration({
+        maskAllText: true,
+        blockAllMedia: true,
+      }),
+    ],
+  });
+}
+
+export { Sentry };

apps/web/src/main.tsx

@@ -1,7 +1,12 @@
+// Sentry init AVANT tout autre import non-essentiel pour capturer même
+// les erreurs de bootstrap (cf. apps/web/src/lib/sentry.ts).
+import "./lib/sentry";
+
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { RouterProvider, createRouter } from "@tanstack/react-router";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import * as Sentry from "@sentry/react";
 
 import { routeTree } from "./routeTree.gen";
 import { env } from "./lib/env";
@@ -79,14 +84,35 @@ async function bootstrapSession(): Promise<void> {
   }
 }
 
+function FallbackError() {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-cream px-6">
+      <div className="text-center max-w-md">
+        <h1 className="font-display text-3xl mb-3 text-ink">Quelque chose a coincé.</h1>
+        <p className="text-ink-2 mb-6">
+          On a noté, on regarde. Rechargez la page pour réessayer.
+        </p>
+        <button
+          onClick={() => location.reload()}
+          className="bg-rubis hover:bg-rubis-deep text-white px-5 py-2.5 rounded-md font-medium transition-colors"
+        >
+          Recharger
+        </button>
+      </div>
+    </div>
+  );
+}
+
 function render(): void {
   const rootEl = document.getElementById("root");
   if (!rootEl) throw new Error("#root introuvable dans index.html");
   createRoot(rootEl).render(
     <StrictMode>
-      <QueryClientProvider client={queryClient}>
-        <RouterProvider router={router} />
-      </QueryClientProvider>
+      <Sentry.ErrorBoundary fallback={<FallbackError />}>
+        <QueryClientProvider client={queryClient}>
+          <RouterProvider router={router} />
+        </QueryClientProvider>
+      </Sentry.ErrorBoundary>
     </StrictMode>,
   );
 }

apps/web/vite.config.ts

@@ -1,11 +1,53 @@
 import path from "node:path";
+import { execSync } from "node:child_process";
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 import { TanStackRouterVite } from "@tanstack/router-plugin/vite";
+import { sentryVitePlugin } from "@sentry/vite-plugin";
+
+// Git sha local — utilisé en dev quand on n'a pas APP_VERSION du CI.
+// En prod c'est le CI qui passe APP_VERSION=${{ github.sha }} en build-arg.
+function resolveAppVersion(): string {
+  if (process.env.APP_VERSION) return process.env.APP_VERSION;
+  try {
+    return execSync("git rev-parse --short HEAD").toString().trim();
+  } catch {
+    return "dev";
+  }
+}
+
+// Sentry source map upload — actif uniquement si SENTRY_AUTH_TOKEN est défini
+// (typiquement injecté par le CI Gitea, pas en local). Sans ça, les stack
+// traces dans Sentry seraient illisibles (JS minifié).
+//
+// `filesToDeleteAfterUpload` est CRITIQUE : sans ça les .map sont copiés
+// dans le dist/ → COPY-és dans l'image Docker → servis par nginx → leak
+// du code source du SPA en prod. Avec ça, Sentry a les sourcemaps pour
+// désobfusquer les stack traces, et nginx ne sert plus que les .js minifiés.
+const sentryPlugin = process.env.SENTRY_AUTH_TOKEN
+  ? sentryVitePlugin({
+      org: process.env.SENTRY_ORG ?? "rubis",
+      project: "rubis-web",
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+      sourcemaps: {
+        assets: ["./dist/**"],
+        filesToDeleteAfterUpload: ["./dist/**/*.map"],
+      },
+      release: { name: process.env.APP_VERSION ?? "dev" },
+    })
+  : null;
+
+const APP_VERSION = resolveAppVersion();
 
 // https://vite.dev/config/
 export default defineConfig({
+  // Injecte VITE_APP_VERSION dans `import.meta.env` au build/dev sans avoir
+  // à l'écrire dans .env (où on ne peut pas évaluer du shell). En CI, le
+  // build-arg APP_VERSION est passé via process.env et override.
+  define: {
+    "import.meta.env.VITE_APP_VERSION": JSON.stringify(APP_VERSION),
+  },
   plugins: [
     // Doit être déclaré AVANT react() (cf. doc TanStack Router).
     TanStackRouterVite({
@@ -15,6 +57,8 @@ export default defineConfig({
     }),
     react(),
     tailwindcss(),
+    // Sentry doit être en dernier pour ne uploader que les artefacts finaux.
+    ...(sentryPlugin ? [sentryPlugin] : []),
   ],
   resolve: {
     alias: {
@@ -25,4 +69,10 @@ export default defineConfig({
     port: 5173,
     strictPort: true,
   },
+  build: {
+    // Source maps requises pour que Sentry désobfusque les stack traces.
+    // En prod, le sentryPlugin les supprime du dist/ après upload pour
+    // qu'elles ne soient pas servies publiquement par nginx.
+    sourcemap: true,
+  },
 });

docs/decisions.md

@@ -307,6 +307,39 @@
 
 ---
 
+## ADR-024 · Error monitoring : Sentry SaaS (free tier)
+
+- **Date** : 2026-05-08
+- **Statut** : ✅ Validée
+- **Décision** : utiliser **Sentry SaaS** (free tier) pour le monitoring d'erreurs et le replay session, avec 2 projets distincts `rubis-api` (Node) et `rubis-web` (React).
+- **Rationale** :
+  - Free tier suffisant pour V1 (5 K events/mois, 50 replays/mois) — on calibre les sample rates pour rester dedans.
+  - Stack standard, vaste écosystème d'intégrations (AdonisJS, React, Vite plugin).
+  - **Source maps uploadées au build** par `@sentry/vite-plugin` puis SUPPRIMÉES du `dist/` final (`filesToDeleteAfterUpload`) → stack traces désobfusquées dans Sentry, mais pas exposées publiquement par nginx.
+  - **Releases trackées au sha git** : `APP_VERSION=${{ github.sha }}` injecté en build-arg (web) et runtime env (api). Une régression ↔ un commit, sans ambiguïté.
+- **Sample rates** :
+  - traces : 10 % prod, 100 % dev (debug)
+  - profiles : 100 % (sampled par traces)
+  - replay session : **0 %** (pas de replay sans erreur — économie quota)
+  - replay sur erreur : **100 %** (capture les 30 s précédant le crash, debug post-mortem)
+- **Privacy / PII** :
+  - User context Sentry : **`user.id` UUID seulement**, pas d'email ni nom (minimisation PII).
+  - Replay : `maskAllText: true` + `blockAllMedia: true` (sécurité par défaut, on relâche après si besoin).
+  - Tags Sentry : on log le **pattern de route** (`/api/v1/checkin/:token/paid`) pas l'URL réelle, sinon les codes OAuth (`?code=...`) et les tokens de check-in fuiteraient dans des champs indexés.
+  - 4xx attendues filtrées dans `beforeSend` côté API (validation, auth invalide → bruit, pas une erreur).
+- **Implémentation** :
+  - API : `apps/api/start/sentry.ts` chargé en 1er dans `bin/server.ts`, `Sentry.captureException` dans `app/exceptions/handler.ts:report` pour les 5xx.
+  - Web : `apps/web/src/lib/sentry.ts` chargé en 1er dans `main.tsx`, `Sentry.ErrorBoundary` autour de l'app, `Sentry.setUser` dans `authStore.setSession/clear`.
+  - DSN web : variable `VITE_SENTRY_DSN_WEB` (publique by-design — bake-able dans le bundle).
+  - DSN api : variable `SENTRY_DSN_API` (env runtime K3s).
+  - Auth token CI : `SENTRY_AUTH_TOKEN` secret Gitea, lu uniquement au build pour upload des sourcemaps. Jamais en runtime.
+- **Alternatives écartées** :
+  - **Self-hosted Sentry** : opérationnellement coûteux pour V1 solo founder. À reconsidérer si quota free tier explosé.
+  - **Datadog / New Relic / Bugsnag** : cher au-delà du free tier, overkill pour la taille V1.
+  - **Pas de monitoring** : insoutenable en prod B2B SaaS — un bug silencieux peut perdre un client en 24h.
+
+---
+
 ## Décisions à venir (en attente)
 
 | # | Sujet | Pourquoi en attente |