feat(auth): add Authentik OIDC adapter

Refs #96

docs/scratchpads/p5-004-authentik-sso.md

@@ -0,0 +1,44 @@
+# P5-004 Scratchpad
+
+- Objective: Add optional Authentik OIDC SSO adapter via Better Auth genericOAuth.
+- Task ref: P5-004
+- Issue ref: #96
+- Plan:
+  1. Inspect auth/gateway surfaces and Better Auth plugin shape.
+  2. Add failing coverage for auth config/startup validation where feasible.
+  3. Implement adapter, docs, and warnings.
+  4. Run targeted typechecks, lint, and review.
+
+- TDD note: no low-friction auth plugin or bootstrap-env test seam exists for `packages/auth/src/auth.ts` or `apps/gateway/src/main.ts`. This change is configuration-oriented and does not alter an existing behavioral contract with a current test harness. I skipped new tests for this pass and relied on exact typecheck/lint/test commands plus manual review.
+
+- Changes:
+  1. Added conditional Better Auth `genericOAuth` plugin registration for the `authentik` provider in `packages/auth/src/auth.ts`.
+  2. Added a soft startup warning in `apps/gateway/src/main.ts` for incomplete Authentik env configuration.
+  3. Added `docs/plans/authentik-sso-setup.md` with env, redirect URI, and test-flow guidance.
+  4. Confirmed `packages/auth/src/index.ts` already exports `AuthConfig`; no change required there.
+
+- Verification:
+  1. `pnpm --filter @mosaic/db build`
+  2. `pnpm --filter @mosaic/auth typecheck`
+  3. `pnpm --filter @mosaic/gateway typecheck`
+  4. `pnpm lint`
+  5. `pnpm format:check`
+  6. `pnpm --filter @mosaic/auth test`
+  7. `pnpm --filter @mosaic/gateway test`
+
+- Results:
+  1. `@mosaic/auth` typecheck passed after replacing the non-existent `enabled` field with conditional plugin registration.
+  2. `@mosaic/gateway` typecheck passed.
+  3. Repo lint passed.
+  4. Prettier check passed after formatting `apps/gateway/src/main.ts`.
+  5. `@mosaic/auth` tests reported `No test files found, exiting with code 0`.
+  6. `@mosaic/gateway` tests passed: `3` files, `20` tests.
+
+- Review:
+  1. Manual review of the diff found no blocker issues.
+  2. External `codex-code-review.sh --uncommitted` was attempted but did not return a usable verdict in-session; no automated review findings were available from that run.
+
+- Situational evidence:
+  1. Provider activation is env-gated by `AUTHENTIK_CLIENT_ID`.
+  2. Misconfigured optional SSO surfaces a warning instead of crashing gateway startup.
+  3. Setup doc records the expected redirect path: `{BETTER_AUTH_URL}/api/auth/callback/authentik`.