diff --git a/agent-system/README.md b/agent-system/README.md
new file mode 100644
index 0000000..7ad0985
--- /dev/null
+++ b/agent-system/README.md
@@ -0,0 +1,14 @@
+# Agent System
+
+This folder contains the technical assets for the multi-role workflow.
+
+Structure:
+- `contracts/`: JSON schemas for role outputs
+- `templates/`: starter JSON payloads
+- `prompts/`: role-specific prompt baselines
+- `checks/`: guard catalog, quality gates, and review checklists
+- `runs/`: optional runtime artifacts (can stay untracked)
+
+References:
+- Planner standard: `tools/codex-skills/starterkit-planner/SKILL.md`
+- Guardrails: `tools/codex-skills/core-guardrails/SKILL.md`
diff --git a/agent-system/checks/acceptance-checklist.md b/agent-system/checks/acceptance-checklist.md
new file mode 100644
index 0000000..3dc64a7
--- /dev/null
+++ b/agent-system/checks/acceptance-checklist.md
@@ -0,0 +1,25 @@
+# Acceptance Checklist
+
+Use this checklist for the acceptance reviewer.
+
+## Scope
+- all in-scope items from `plan.json` are implemented
+- out-of-scope items are not silently introduced
+
+## Behavior
+- each `SC-*` success criterion from `plan.json` is verifiably met
+- negative and edge paths behave as defined
+
+## Regressions
+- existing flows still work after change
+- no critical UX break on key user paths
+
+## Tests
+- every test listed in `plan.json tests[]` is implemented and passes (QG-001 green)
+- new Service/Gateway logic has at least one test covering the happy path and one failure/edge case (GR-TEST-001)
+- no new untestable code patterns introduced (GR-TEST-002)
+
+## Evidence
+- each criterion has explicit pass/fail evidence
+- each criterion check references the exact `SC-*` ID
+- fail findings include exact missing behavior
diff --git a/agent-system/checks/guard-catalog.json b/agent-system/checks/guard-catalog.json
new file mode 100644
index 0000000..24d99d3
--- /dev/null
+++ b/agent-system/checks/guard-catalog.json
@@ -0,0 +1,272 @@
+{
+  "version": "1.0.0",
+  "source_skill": "tools/codex-skills/core-guardrails/SKILL.md",
+  "guards": [
+    {
+      "id": "GR-CORE-001",
+      "area": "core",
+      "title": "Layering boundaries",
+      "requirement": "MUST keep pages orchestration-only and business logic in services.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-002",
+      "area": "core",
+      "title": "No direct service instantiation in pages",
+      "requirement": "MUST NOT instantiate Service, Gateway or Repository directly in pages.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-003",
+      "area": "core",
+      "title": "Request input contract",
+      "requirement": "MUST read input via requestInput in pages and avoid superglobals for request data.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-004",
+      "area": "core",
+      "title": "API json body contract",
+      "requirement": "MUST NOT use ApiResponse::readJsonBody in pages/api/v1.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-005",
+      "area": "security",
+      "title": "Server-side authz",
+      "requirement": "MUST enforce authorization server-side.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-006",
+      "area": "security",
+      "title": "Server-side tenant scope",
+      "requirement": "MUST enforce tenant scope server-side.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-007",
+      "area": "api",
+      "title": "OpenAPI sync",
+      "requirement": "MUST update OpenAPI in same merge when API changes.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-UI-001",
+      "area": "ui",
+      "title": "List initialization standard",
+      "requirement": "MUST initialize lists via initStandardListPage.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-002",
+      "area": "ui",
+      "title": "No legacy filter toggle markup",
+      "requirement": "MUST NOT introduce legacy filter toggle attributes.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-003",
+      "area": "ui",
+      "title": "Row interaction standard",
+      "requirement": "MUST preserve row action column plus enter and dblclick fallback behavior.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-004",
+      "area": "ui",
+      "title": "Page size standard",
+      "requirement": "MUST preserve page size options and URL/localStorage/default precedence.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-005",
+      "area": "ui",
+      "title": "Detail page standard",
+      "requirement": "MUST use standard detail page contracts for dirty-state and actions.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-006",
+      "area": "ui",
+      "title": "No inline confirm",
+      "requirement": "MUST NOT use inline confirm handlers on standardized detail flows.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-007",
+      "area": "ui",
+      "title": "Shared partial usage",
+      "requirement": "MUST use shared list and detail partials for standardized UI blocks.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-016",
+      "area": "ui",
+      "title": "Template structure discipline for new features",
+      "requirement": "New pages MUST use the established layout system (templates/default.phtml or a named layout variant). UI blocks that appear in two or more pages MUST be extracted as a partial under templates/partials/ rather than duplicated inline. New partials MUST follow the naming convention app-{context}-{purpose}.phtml. Page-specific rendering belongs in pages/*.phtml, not in templates/. MUST NOT create ad-hoc layout HTML inside pages that bypasses the layout system.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-008",
+      "area": "ui",
+      "title": "Template RBAC contract",
+      "requirement": "MUST use viewAuth in templates and avoid can calls.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-009",
+      "area": "ui",
+      "title": "No a11y regression",
+      "requirement": "MUST NOT introduce regressions in accessibility basics (labels, roles, keyboard focus) on touched flows.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-CORE-008",
+      "area": "core",
+      "title": "No direct superglobal access in pages",
+      "requirement": "MUST NOT use $_SESSION, $_SERVER, $_COOKIE, $_ENV directly in pages; use framework abstractions (app(SessionStoreInterface::class), RequestContext, requestInput()) instead.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-SEC-001",
+      "area": "security",
+      "title": "CSRF verification on POST endpoints",
+      "requirement": "MUST verify CSRF token on every POST endpoint in pages before processing the request body.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-SEC-002",
+      "area": "security",
+      "title": "No unredacted PII or secrets in logs and audit metadata",
+      "requirement": "MUST NOT write PII (email, names, UUIDs) or secrets (tokens, passwords) to logs or audit metadata without prior redaction.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-SEC-003",
+      "area": "security",
+      "title": "SQL via Repository with prepared statements only",
+      "requirement": "MUST NOT build SQL strings with user-controlled input; all queries MUST go through Repository classes using prepared statements.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-LANG-001",
+      "area": "lang",
+      "title": "PSR-4 namespace alignment",
+      "requirement": "MUST align PHP namespace with directory path (MintyPHP\\ → lib/, MintyPHP\\Tests\\ → tests/); violations are caught by QG-003.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-LANG-002",
+      "area": "lang",
+      "title": "PHP style compliance",
+      "requirement": "MUST pass composer cs:check without diff (php-cs-fixer dry-run); fix with composer cs:fix before merge.",
+      "source": "tools/codex-skills/starterkit-php-style-ci/SKILL.md"
+    },
+    {
+      "id": "GR-TEST-001",
+      "area": "test",
+      "title": "Tests ship with new logic",
+      "requirement": "New or changed business logic in lib/Service/ MUST be accompanied by PHPUnit tests in the same merge covering the happy path and at least one failure or edge case. No new public method in a Service or Gateway without a test.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-TEST-002",
+      "area": "test",
+      "title": "Code must be unit-testable",
+      "requirement": "New code MUST use constructor injection for all dependencies. MUST NOT introduce static side-effects in constructors, hidden global state, or direct DB/HTTP calls outside Repository/Gateway abstractions — patterns that make unit testing without mocks impossible.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-010",
+      "area": "core",
+      "title": "DB schema changes for existing installs must be idempotent SQL scripts in db/updates/",
+      "requirement": "Any schema or data change for existing installations MUST be shipped as an idempotent SQL script in db/updates/ (e.g. using IF NOT EXISTS, ON DUPLICATE KEY, or guarded ALTER TABLE). MUST NOT modify db/init/init.sql only — existing containers will not re-run init.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-011",
+      "area": "core",
+      "title": "New settings belong in the DB settings table, not in config files",
+      "requirement": "New application settings MUST be stored in the settings DB table as the single source of truth. config/settings.php is a partial hot-path cache only and MUST NOT be used as primary storage for new settings. Security, integration, and feature-flag settings MUST go through the settings gateway layer.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-012",
+      "area": "core",
+      "title": "POST-Redirect-GET after successful mutating actions",
+      "requirement": "Actions that successfully mutate state (create, update, delete) MUST respond with a redirect (PRG pattern) rather than rendering a response directly. This prevents double-submit on browser reload. Flash messages MUST be set before the redirect via Flash::set().",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-CORE-009",
+      "area": "core",
+      "title": "Repository list queries must use RepoQuery::sanitizeLimitOffset",
+      "requirement": "New Repository methods that return lists MUST use RepoQuery::sanitizeLimitOffset() to enforce LIMIT and OFFSET. Unbounded SELECT queries without LIMIT on potentially large tables are forbidden. The default maxLimit of 100 MUST NOT be raised without explicit justification reviewed and approved.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-SEC-006",
+      "area": "security",
+      "title": "User-uploaded files stored in storage/, never in web/",
+      "requirement": "Files uploaded by users MUST be stored under storage/ (e.g. storage/users/{uuid}/, storage/tenants/{uuid}/, storage/imports/) and MUST NOT be written to web/ or any other publicly served directory. Storage paths MUST use non-guessable identifiers (UUID v4 or equivalent) to prevent enumeration. Files MUST be served through a PHP controller that enforces authorization, not directly by the web server. MUST validate file type (MIME + extension allowlist) before storing.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-SEC-005",
+      "area": "security",
+      "title": "Encryption only via lib/Support/Crypto.php",
+      "requirement": "Any encryption or decryption of sensitive data MUST use the Crypto class (lib/Support/Crypto.php) which provides AES-256-GCM via APP_CRYPTO_KEY. MUST NOT use raw openssl_encrypt/openssl_decrypt, base64 encoding as a substitute for encryption, or any other hand-rolled crypto primitives.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-core.md"
+    },
+    {
+      "id": "GR-SEC-004",
+      "area": "security",
+      "title": "No external CDN or remote asset loading",
+      "requirement": "MUST NOT load JS, CSS, fonts, or any other assets from external CDNs (Cloudflare, jsDelivr, unpkg, Google Fonts, etc.) or remote URLs in templates, pages, or layout files. If a third-party library is required it MUST be vendored locally in the repository (e.g. web/js/vendor/ or web/css/vendor/) and served via assetVersion(). No <script src='https://...'>, <link href='https://...'>, @import url('https://...'), or fetch() calls to external asset hosts.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-014",
+      "area": "ui",
+      "title": "UI state completeness for new views and components",
+      "requirement": "New user-facing views or components that display data or trigger actions MUST handle all four states: loading (progress indicator while data is fetched), empty (explicit message when no data exists), error (user-visible error feedback when an action or data load fails), and success (confirmation after a completed action). All four states MUST be defined in the plan before implementation starts. Applies to new views and components; not required for small, isolated fixes to existing UI.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-013",
+      "area": "ui",
+      "title": "A11y by design: new interactive components built accessible from the start",
+      "requirement": "New interactive UI components (buttons, links, forms, modals, dropdowns, custom controls) MUST use semantic HTML elements. MUST be fully keyboard-operable (Tab order, Enter/Space to activate, Escape to close overlays, no keyboard trap). MUST use ARIA attributes only where semantic HTML is insufficient — no ARIA-spam. MUST meet WCAG 2.1 AA color contrast for any newly introduced text or icon elements. These requirements apply at creation time, not as a post-hoc retrofit.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-015",
+      "area": "ui",
+      "title": "i18n key completeness: all language files updated in the same merge",
+      "requirement": "Every new translation key added via t('key') MUST be present in ALL language files (i18n/default_de.json and i18n/default_en.json) in the same merge. A key present in one file but missing in another causes visible fallback output. MUST NOT leave placeholder or empty string values without a TODO comment.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-010",
+      "area": "ui",
+      "title": "i18n: all visible text must use t()",
+      "requirement": "MUST wrap all user-visible strings in phtml views with t('key'). MUST NOT hardcode display strings in templates or partials.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-011",
+      "area": "ui",
+      "title": "JS reuse-first: prefer existing exports over new functions",
+      "requirement": "MUST check web/js/core/ and web/js/components/ for existing exported functions before adding a new one. A new export is only justified when no existing function covers the use-case after review. MUST NOT duplicate logic already present in app-dom.js, app-grid-factory.js, app-detail-page-factory.js, or other core modules.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    },
+    {
+      "id": "GR-UI-012",
+      "area": "ui",
+      "title": "CSS reuse-first: prefer existing classes over new rules",
+      "requirement": "MUST check existing CSS layers (base, components, layout, pages) for suitable classes before writing new rules. MUST use existing app-* component classes as the basis and only add additive overrides. MUST NOT duplicate declarations already defined in shared component or layout files.",
+      "source": "tools/codex-skills/core-guardrails/references/boundaries-ui.md"
+    }
+  ]
+}
diff --git a/agent-system/checks/guard-checklist.md b/agent-system/checks/guard-checklist.md
new file mode 100644
index 0000000..54e2a65
--- /dev/null
+++ b/agent-system/checks/guard-checklist.md
@@ -0,0 +1,65 @@
+# Guard Checklist
+
+Use this checklist for the guard reviewer.
+Canonical guard IDs live in `agent-system/checks/guard-catalog.json`.
+
+## Architecture
+- `GR-CORE-001` no boundary violations against project layering
+- `GR-CORE-002` no direct bypass of shared factories/services where prohibited
+- `GR-CORE-003` request input contract is respected (requestInput(), no $_POST/$_GET/$_FILES/REQUEST_METHOD)
+- `GR-CORE-004` API json body contract is respected
+- `GR-CORE-008` no direct superglobal access in pages ($_SESSION, $_SERVER, $_COOKIE, $_ENV)
+- `GR-CORE-009` new Repository list methods use RepoQuery::sanitizeLimitOffset(); no unbounded SELECTs on large tables; maxLimit 100 not raised without justification
+- `GR-CORE-010` DB schema changes for existing installs shipped as idempotent SQL scripts in db/updates/; db/init/init.sql alone is not sufficient
+- `GR-CORE-011` new settings stored in DB settings table via settings gateway; config/settings.php is hot-path cache only, not primary storage
+- `GR-CORE-012` successful mutating POSTs respond with redirect (PRG); flash messages set before redirect via Flash::set()
+
+## Security
+- `GR-CORE-005` auth and permission checks stay intact
+- `GR-CORE-006` tenant-scope checks stay intact
+- `GR-SEC-001` CSRF token verified on every POST endpoint before request body processing
+- `GR-SEC-002` no unredacted PII or secrets in logs and audit metadata
+- `GR-SEC-003` all SQL goes through Repository with prepared statements; no string-interpolated queries
+- `GR-SEC-004` no external CDN or remote asset loading; all JS/CSS/fonts must be vendored locally and served via assetVersion()
+- `GR-SEC-005` encryption only via lib/Support/Crypto.php (AES-256-GCM); no raw openssl_encrypt, no base64-as-encryption, no hand-rolled crypto
+- `GR-SEC-006` user-uploaded files stored under storage/{type}/{uuid}/ only; never written to web/; served via PHP controller with authz check; MIME + extension validated before storage
+
+## Frontend and UX
+- `GR-UI-001` list initialization standard is preserved
+- `GR-UI-002` no legacy filter toggle markup introduced
+- `GR-UI-003` row interaction standard is preserved where applicable
+- `GR-UI-004` page size standard is preserved where applicable
+- `GR-UI-005` detail page standard is preserved where applicable
+- `GR-UI-006` no inline confirm hacks
+- `GR-UI-007` shared partial usage remains consistent (existing partials reused where applicable)
+- `GR-UI-016` template structure discipline: new pages use established layout system; blocks reused in ≥2 pages extracted as partial in templates/partials/ with naming app-{context}-{purpose}.phtml; no ad-hoc layout HTML in pages that bypasses the layout system
+- `GR-UI-008` template RBAC contract remains consistent
+- `GR-UI-009` no regression in a11y basics (labels, roles, keyboard focus) for touched flows
+- `GR-UI-013` a11y by design: new interactive components use semantic HTML, are keyboard-operable (Tab/Enter/Escape), use ARIA only where necessary, meet WCAG 2.1 AA contrast
+- `GR-UI-014` UI state completeness: new views/components define and implement loading, empty, error, and success states before implementation starts
+- `GR-UI-010` all user-visible strings in phtml views wrapped in t(); no hardcoded display strings
+- `GR-UI-015` new t() keys present in all language files (de + en) in the same merge; no key missing in any language file
+- `GR-UI-011` JS reuse-first: existing exports in web/js/core/ and web/js/components/ checked before adding a new function; no logic duplication from core modules
+- `GR-UI-012` CSS reuse-first: existing app-* classes and layer rules checked before writing new declarations; only additive overrides on top of shared components
+
+## Testing
+- `GR-TEST-001` new or changed Service/Gateway logic has accompanying PHPUnit tests (happy path + at least one failure/edge case) in the same merge
+- `GR-TEST-002` new code uses constructor injection; no static side-effects, hidden global state, or untestable DB/HTTP calls outside Repository/Gateway abstractions
+
+## Language and Style
+- `GR-LANG-001` PSR-4 namespace/directory alignment is intact (verified by QG-003)
+- `GR-LANG-002` PHP style passes composer cs:check without diff for touched files
+
+## Quality Gates
+- `QG-001` to `QG-003` are run unless explicitly out of scope
+- `QG-004` fast structural checks reported when relevant
+- `QG-005` JS smoke performed for JS-touching changes; no new unhandled runtime errors
+- `QG-006` PHP style check run for any PHP-touching changes
+- `QG-007` composer-unused run periodically; any newly unused package flagged to reviewer
+
+References:
+- `tools/codex-skills/core-guardrails/references/boundaries-core.md`
+- `tools/codex-skills/core-guardrails/references/boundaries-ui.md`
+- `tools/codex-skills/core-guardrails/references/quality-gates.md`
+- `tools/codex-skills/starterkit-grid-standards/SKILL.md`
+- `tools/codex-skills/starterkit-php-style-ci/SKILL.md`
diff --git a/agent-system/checks/quality-gates.json b/agent-system/checks/quality-gates.json
new file mode 100644
index 0000000..cc984e8
--- /dev/null
+++ b/agent-system/checks/quality-gates.json
@@ -0,0 +1,49 @@
+{
+  "version": "1.0.0",
+  "source": "tools/codex-skills/core-guardrails/references/quality-gates.md",
+  "gates": [
+    {
+      "id": "QG-001",
+      "type": "mandatory",
+      "name": "PHPUnit Full",
+      "command": "docker compose exec php vendor/bin/phpunit"
+    },
+    {
+      "id": "QG-002",
+      "type": "mandatory",
+      "name": "PHPStan",
+      "command": "docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress"
+    },
+    {
+      "id": "QG-003",
+      "type": "mandatory",
+      "name": "Architecture Core Contract",
+      "command": "docker compose exec php vendor/bin/phpunit tests/Architecture/CoreStarterkitContractTest.php"
+    },
+    {
+      "id": "QG-004",
+      "type": "fast",
+      "name": "Structural rg checks",
+      "command": "(rg 'new\\s+[^\\s(]+Factory\\(' lib/Service || true) | wc -l\n(rg --glob '!**/*Factory.php' 'new\\s+[^\\s(]+(Service|Gateway|Repository)\\(' lib/Service || true) | wc -l\n(rg \"\\b(accessServicesFactory|directoryServicesFactory|userServicesFactory|authServicesFactory|tenantServicesFactory|settingServicesFactory|userRepositoryFactory|authRepositoryFactory|authGatewayFactory)\\(\" pages lib templates web || true) | wc -l\n(rg -n 'new\\s+[^\\s(]+(Service|Gateway|Repository)\\(' pages -g '*.php' || true) | wc -l\n(rg -n '\\bDB::' pages -g '*.php' || true) | wc -l\n(rg -n 'app\\([^\\n]*Factory::class\\)->create' pages/admin -g '*.php' || true) | wc -l\n(rg -n 'Factory::class' pages/admin -g '*.php' || true) | wc -l\n(rg -n 'ApiResponse::readJsonBody\\(' pages/api/v1 -g '*.php' || true) | wc -l"
+    },
+    {
+      "id": "QG-005",
+      "type": "manual",
+      "name": "JS smoke",
+      "command": "Browser smoke test with DevTools console; expect no new JS errors."
+    },
+    {
+      "id": "QG-006",
+      "type": "fast",
+      "name": "PHP Style Check",
+      "command": "docker compose exec php composer cs:check"
+    },
+    {
+      "id": "QG-007",
+      "type": "periodic",
+      "name": "Unused Composer packages",
+      "command": "docker compose exec php vendor/bin/composer-unused",
+      "note": "Run periodically (not per-merge). Flag any newly unused package to the reviewer."
+    }
+  ]
+}
diff --git a/agent-system/contracts/executor.schema.json b/agent-system/contracts/executor.schema.json
new file mode 100644
index 0000000..2513a27
--- /dev/null
+++ b/agent-system/contracts/executor.schema.json
@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Executor Output",
+  "type": "object",
+  "required": [
+    "task_id",
+    "plan_ref",
+    "status",
+    "changed_files",
+    "guard_evidence",
+    "commands",
+    "quality_gate_results",
+    "test_results",
+    "open_items"
+  ],
+  "properties": {
+    "task_id": { "type": "string", "minLength": 1 },
+    "plan_ref": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "enum": ["done", "blocked"] },
+    "changed_files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "summary"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "summary": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "guard_evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["guard_id", "status", "evidence"],
+        "properties": {
+          "guard_id": {
+            "type": "string",
+            "pattern": "^GR-[A-Z]+-[0-9]{3}$"
+          },
+          "status": { "type": "string", "enum": ["pass", "fail", "n/a"] },
+          "evidence": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "commands": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["cmd", "result"],
+        "properties": {
+          "cmd": { "type": "string", "minLength": 1 },
+          "result": { "type": "string", "enum": ["pass", "fail", "skipped"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "quality_gate_results": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["gate_id", "result"],
+        "properties": {
+          "gate_id": {
+            "type": "string",
+            "pattern": "^QG-[0-9]{3}$"
+          },
+          "result": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "test_results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "result"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "result": { "type": "string", "enum": ["pass", "fail", "skipped"] },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "open_items": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/agent-system/contracts/finalizer.schema.json b/agent-system/contracts/finalizer.schema.json
new file mode 100644
index 0000000..379e4a3
--- /dev/null
+++ b/agent-system/contracts/finalizer.schema.json
@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Finalizer Output",
+  "type": "object",
+  "required": [
+    "task_id",
+    "ready_to_finalize",
+    "guard_review",
+    "acceptance_review",
+    "ci_status",
+    "final_action"
+  ],
+  "properties": {
+    "task_id": { "type": "string", "minLength": 1 },
+    "ready_to_finalize": { "type": "boolean" },
+    "guard_review": { "type": "string", "enum": ["pass", "fail"] },
+    "acceptance_review": { "type": "string", "enum": ["pass", "fail"] },
+    "ci_status": { "type": "string", "enum": ["pass", "fail", "unknown"] },
+    "final_action": { "type": "string", "enum": ["commit", "merge", "hold"] },
+    "hold_reason": { "type": "string", "minLength": 1 },
+    "commit_message": { "type": "string" },
+    "notes": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "final_action": { "const": "hold" } },
+        "required": ["final_action"]
+      },
+      "then": {
+        "required": ["hold_reason"]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "final_action": { "enum": ["commit", "merge"] }
+        },
+        "required": ["final_action"]
+      },
+      "then": {
+        "properties": {
+          "ready_to_finalize": { "const": true },
+          "guard_review": { "const": "pass" },
+          "acceptance_review": { "const": "pass" },
+          "ci_status": { "const": "pass" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "ci_status": { "const": "fail" } },
+        "required": ["ci_status"]
+      },
+      "then": {
+        "properties": { "final_action": { "enum": ["hold"] } }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "guard_review": { "const": "fail" }
+        },
+        "required": ["guard_review"]
+      },
+      "then": {
+        "properties": { "final_action": { "enum": ["hold"] } }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "acceptance_review": { "const": "fail" }
+        },
+        "required": ["acceptance_review"]
+      },
+      "then": {
+        "properties": { "final_action": { "enum": ["hold"] } }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "ci_status": { "const": "unknown" }
+        },
+        "required": ["ci_status"]
+      },
+      "then": {
+        "properties": { "final_action": { "enum": ["hold"] } }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "ready_to_finalize": { "const": false }
+        },
+        "required": ["ready_to_finalize"]
+      },
+      "then": {
+        "properties": { "final_action": { "enum": ["hold"] } }
+      }
+    }
+  ],
+  "additionalProperties": false
+}
diff --git a/agent-system/contracts/planner.schema.json b/agent-system/contracts/planner.schema.json
new file mode 100644
index 0000000..bbd0290
--- /dev/null
+++ b/agent-system/contracts/planner.schema.json
@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Planner Output",
+  "type": "object",
+  "required": [
+    "task_id",
+    "summary",
+    "scope",
+    "guardrails",
+    "success_criteria",
+    "implementation_steps",
+    "tests",
+    "acceptance_checks",
+    "risks"
+  ],
+  "properties": {
+    "task_id": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "scope": {
+      "type": "object",
+      "required": ["in", "out"],
+      "properties": {
+        "in": { "type": "array", "items": { "type": "string" } },
+        "out": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "guardrails": {
+      "type": "object",
+      "required": ["required_guard_ids", "required_quality_gate_ids"],
+      "properties": {
+        "required_guard_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^GR-[A-Z]+-[0-9]{3}$"
+          }
+        },
+        "required_quality_gate_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^QG-[0-9]{3}$"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "success_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "criterion"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^SC-[0-9]{3}$"
+          },
+          "criterion": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "implementation_steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "description", "guard_refs"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "title": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "guard_refs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^GR-[A-Z]+-[0-9]{3}$"
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "tests": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "acceptance_checks": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "ux_notes": {
+      "type": "object",
+      "description": "Required for tasks touching UI (templates, phtml pages, web/js, web/css). Leave fields as empty arrays if not applicable.",
+      "properties": {
+        "affected_patterns": {
+          "type": "array",
+          "description": "Existing UI patterns or partials touched by this task.",
+          "items": { "type": "string" }
+        },
+        "ui_states_required": {
+          "type": "array",
+          "description": "UI states the new view/component must handle: loading, empty, error, success.",
+          "items": {
+            "type": "string",
+            "enum": ["loading", "empty", "error", "success"]
+          }
+        },
+        "a11y_touchpoints": {
+          "type": "array",
+          "description": "New interactive elements that must be keyboard-operable and use semantic HTML.",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "risks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["risk", "mitigation"],
+        "properties": {
+          "risk": { "type": "string", "minLength": 1 },
+          "mitigation": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/agent-system/contracts/reviewer-acceptance.schema.json b/agent-system/contracts/reviewer-acceptance.schema.json
new file mode 100644
index 0000000..cc4248d
--- /dev/null
+++ b/agent-system/contracts/reviewer-acceptance.schema.json
@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Acceptance Reviewer Output",
+  "type": "object",
+  "required": ["task_id", "verdict", "checked_criterion_ids", "checks"],
+  "properties": {
+    "task_id": { "type": "string", "minLength": 1 },
+    "verdict": { "type": "string", "enum": ["pass", "fail"] },
+    "checked_criterion_ids": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^SC-[0-9]{3}$"
+      }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["criterion_id", "criterion", "result", "evidence"],
+        "properties": {
+          "criterion_id": {
+            "type": "string",
+            "pattern": "^SC-[0-9]{3}$"
+          },
+          "criterion": { "type": "string", "minLength": 1 },
+          "result": { "type": "string", "enum": ["pass", "fail"] },
+          "evidence": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "missing_or_wrong": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "verdict": { "const": "pass" } },
+        "required": ["verdict"]
+      },
+      "then": {
+        "properties": {
+          "checks": {
+            "not": {
+              "contains": {
+                "type": "object",
+                "properties": { "result": { "const": "fail" } },
+                "required": ["result"]
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "verdict": { "const": "fail" } },
+        "required": ["verdict"]
+      },
+      "then": {
+        "required": ["missing_or_wrong"],
+        "properties": {
+          "missing_or_wrong": { "type": "array", "minItems": 1 },
+          "checks": {
+            "contains": {
+              "type": "object",
+              "properties": { "result": { "const": "fail" } },
+              "required": ["result"]
+            }
+          }
+        }
+      }
+    }
+  ],
+  "additionalProperties": false
+}
diff --git a/agent-system/contracts/reviewer-guards.schema.json b/agent-system/contracts/reviewer-guards.schema.json
new file mode 100644
index 0000000..2d8abfc
--- /dev/null
+++ b/agent-system/contracts/reviewer-guards.schema.json
@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Guard Reviewer Output",
+  "type": "object",
+  "required": ["task_id", "verdict", "checked_guard_ids", "checked_quality_gate_ids", "findings"],
+  "properties": {
+    "task_id": { "type": "string", "minLength": 1 },
+    "verdict": { "type": "string", "enum": ["pass", "fail"] },
+    "checked_guard_ids": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^GR-[A-Z]+-[0-9]{3}$"
+      }
+    },
+    "checked_quality_gate_ids": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^QG-[0-9]{3}$"
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "rule_ref", "summary", "file"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+          "rule_ref": {
+            "type": "string",
+            "pattern": "^(GR-[A-Z]+-[0-9]{3}|QG-[0-9]{3})$"
+          },
+          "summary": { "type": "string", "minLength": 1 },
+          "file": { "type": "string", "minLength": 1 },
+          "fix_required": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/agent-system/prompts/executor.md b/agent-system/prompts/executor.md
new file mode 100644
index 0000000..f459306
--- /dev/null
+++ b/agent-system/prompts/executor.md
@@ -0,0 +1,25 @@
+# Executor Prompt Baseline
+
+Goal:
+- implement the approved plan with minimal scope drift
+
+Required references:
+- `tools/codex-skills/core-guardrails/SKILL.md`
+- `tools/codex-skills/starterkit-grid-standards/SKILL.md` (for UI/list tasks)
+- `tools/codex-skills/starterkit-php-style-ci/SKILL.md` (for PHP style checks)
+- `agent-system/checks/guard-catalog.json`
+- `agent-system/checks/quality-gates.json`
+
+Input:
+- `plan.json`
+
+Output:
+- valid JSON by `agent-system/contracts/executor.schema.json`
+
+Rules:
+- only implement items in plan scope
+- run relevant checks and include command results
+- provide guard evidence for each required guard ID
+- report quality gate results by gate ID
+- list each changed file with a short reason
+- if blocked, set status to `blocked` and list exact blockers
diff --git a/agent-system/prompts/finalizer.md b/agent-system/prompts/finalizer.md
new file mode 100644
index 0000000..1c9bd64
--- /dev/null
+++ b/agent-system/prompts/finalizer.md
@@ -0,0 +1,18 @@
+# Finalizer Prompt Baseline
+
+Goal:
+- finalize only when both reviews are pass and checks are green
+
+Input:
+- `execution-report.json`
+- `review-guards.json`
+- `review-acceptance.json`
+
+Output:
+- valid JSON by `agent-system/contracts/finalizer.schema.json`
+
+Rules:
+- do not finalize if any reviewer verdict is `fail`
+- do not finalize unless `guard_review=pass`, `acceptance_review=pass`, and `ci_status=pass`
+- set `final_action` to `hold` and populate `hold_reason` (non-empty string) whenever action is `hold`
+- `hold_reason` is required by schema when `final_action` is `hold`
diff --git a/agent-system/prompts/planner.md b/agent-system/prompts/planner.md
new file mode 100644
index 0000000..9750ea3
--- /dev/null
+++ b/agent-system/prompts/planner.md
@@ -0,0 +1,28 @@
+# Planner Prompt Baseline
+
+Goal:
+- transform issue input into a decision-complete plan
+
+Required references:
+- `tools/codex-skills/starterkit-planner/SKILL.md`
+- `tools/codex-skills/core-guardrails/SKILL.md`
+- `tools/codex-skills/starterkit-grid-standards/SKILL.md` (for UI/list tasks)
+- `agent-system/checks/guard-catalog.json`
+- `agent-system/checks/quality-gates.json`
+
+Output:
+- valid JSON by `agent-system/contracts/planner.schema.json`
+
+Rules:
+- define explicit in-scope and out-of-scope
+- define measurable success criteria with stable IDs (`SC-001`, `SC-002`, ...)
+- select required guard IDs from guard catalog
+- select required quality gate IDs from quality gates list
+- include at least one risk with mitigation
+- keep implementation steps actionable and ordered
+
+UI task rules (apply when the task touches templates, pages/*.phtml, or web/js|css):
+- populate `ux_notes.affected_patterns`: list every existing UI pattern or partial being touched (e.g. "app-details-titlebar", "initStandardListPage")
+- populate `ux_notes.ui_states_required`: declare all four states that the new view/component must handle — loading, empty, error, success (GR-UI-014); omit only with explicit justification
+- populate `ux_notes.a11y_touchpoints`: list every new interactive element and confirm it will be keyboard-operable and use semantic HTML (GR-UI-013)
+- if any item in `ux_notes` is not applicable, set it to an empty array `[]` — do not omit the field
diff --git a/agent-system/prompts/reviewer-acceptance.md b/agent-system/prompts/reviewer-acceptance.md
new file mode 100644
index 0000000..decfc2d
--- /dev/null
+++ b/agent-system/prompts/reviewer-acceptance.md
@@ -0,0 +1,17 @@
+# Reviewer Acceptance Prompt Baseline
+
+Goal:
+- verify the feature or issue is implemented exactly as requested
+
+Required references:
+- `plan.json`
+- `agent-system/checks/acceptance-checklist.md`
+
+Output:
+- valid JSON by `agent-system/contracts/reviewer-acceptance.schema.json`
+
+Rules:
+- evaluate each `plan.json` success criterion by its `SC-*` ID
+- include evidence for pass/fail checks
+- return `checked_criterion_ids` and per-check `criterion_id` values that match the plan
+- list missing behavior explicitly when verdict is `fail`
diff --git a/agent-system/prompts/reviewer-guards.md b/agent-system/prompts/reviewer-guards.md
new file mode 100644
index 0000000..99c359b
--- /dev/null
+++ b/agent-system/prompts/reviewer-guards.md
@@ -0,0 +1,20 @@
+# Reviewer Guards Prompt Baseline
+
+Goal:
+- verify compliance with guardrails, architecture, and security expectations
+
+Required references:
+- `tools/codex-skills/core-guardrails/SKILL.md`
+- `tools/codex-skills/starterkit-grid-standards/SKILL.md` (for UI/list tasks)
+- `tools/codex-skills/starterkit-php-style-ci/SKILL.md` (for PHP style checks)
+- `agent-system/checks/guard-checklist.md`
+- `agent-system/checks/guard-catalog.json`
+- `agent-system/checks/quality-gates.json`
+
+Output:
+- valid JSON by `agent-system/contracts/reviewer-guards.schema.json`
+
+Rules:
+- findings must reference a concrete guard or gate ID
+- findings must include file path
+- use `fail` only when changes are required before finalize
diff --git a/agent-system/runs/.gitkeep b/agent-system/runs/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/agent-system/runs/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/agent-system/templates/execution-report.template.json b/agent-system/templates/execution-report.template.json
new file mode 100644
index 0000000..b9b84a2
--- /dev/null
+++ b/agent-system/templates/execution-report.template.json
@@ -0,0 +1,39 @@
+{
+  "task_id": "TASK-0001",
+  "plan_ref": "workflows/TASK-0001/plan.json",
+  "status": "done",
+  "changed_files": [
+    {
+      "path": "path/to/file",
+      "summary": "What changed"
+    }
+  ],
+  "guard_evidence": [
+    {
+      "guard_id": "GR-CORE-001",
+      "status": "pass",
+      "evidence": "Short evidence with file or test reference."
+    }
+  ],
+  "commands": [
+    {
+      "cmd": "example command",
+      "result": "pass"
+    }
+  ],
+  "quality_gate_results": [
+    {
+      "gate_id": "QG-001",
+      "result": "pass",
+      "notes": ""
+    }
+  ],
+  "test_results": [
+    {
+      "name": "test name",
+      "result": "pass",
+      "notes": ""
+    }
+  ],
+  "open_items": []
+}
diff --git a/agent-system/templates/finalize.template.json b/agent-system/templates/finalize.template.json
new file mode 100644
index 0000000..c58e2e6
--- /dev/null
+++ b/agent-system/templates/finalize.template.json
@@ -0,0 +1,11 @@
+{
+  "task_id": "TASK-0001",
+  "ready_to_finalize": false,
+  "guard_review": "pass",
+  "acceptance_review": "pass",
+  "ci_status": "unknown",
+  "final_action": "hold",
+  "hold_reason": "Waiting for mandatory quality gates and review pass signals.",
+  "commit_message": "",
+  "notes": ""
+}
diff --git a/agent-system/templates/plan.template.json b/agent-system/templates/plan.template.json
new file mode 100644
index 0000000..b9b42ac
--- /dev/null
+++ b/agent-system/templates/plan.template.json
@@ -0,0 +1,49 @@
+{
+  "task_id": "TASK-0001",
+  "summary": "Short summary of issue or feature",
+  "assumptions": [],
+  "scope": {
+    "in": [],
+    "out": []
+  },
+  "guardrails": {
+    "required_guard_ids": [
+      "GR-CORE-001",
+      "GR-CORE-003",
+      "GR-CORE-005"
+    ],
+    "required_quality_gate_ids": [
+      "QG-001",
+      "QG-002",
+      "QG-003"
+    ]
+  },
+  "success_criteria": [
+    {
+      "id": "SC-001",
+      "criterion": "Measurable acceptance criterion."
+    }
+  ],
+  "implementation_steps": [
+    {
+      "id": "S1",
+      "title": "Step title",
+      "description": "Step detail",
+      "guard_refs": [
+        "GR-CORE-001"
+      ]
+    }
+  ],
+  "tests": [
+    "Test name or PHPUnit class that proves the feature works"
+  ],
+  "acceptance_checks": [
+    "SC-001: Verifiable acceptance step for criterion SC-001"
+  ],
+  "risks": [
+    {
+      "risk": "Risk description",
+      "mitigation": "Mitigation description"
+    }
+  ]
+}
diff --git a/agent-system/templates/review-acceptance.template.json b/agent-system/templates/review-acceptance.template.json
new file mode 100644
index 0000000..f5c4d75
--- /dev/null
+++ b/agent-system/templates/review-acceptance.template.json
@@ -0,0 +1,16 @@
+{
+  "task_id": "TASK-0001",
+  "verdict": "pass",
+  "checked_criterion_ids": [
+    "SC-001"
+  ],
+  "checks": [
+    {
+      "criterion_id": "SC-001",
+      "criterion": "criterion text",
+      "result": "pass",
+      "evidence": "Reference to proof (test, file, manual smoke step)."
+    }
+  ],
+  "missing_or_wrong": []
+}
diff --git a/agent-system/templates/review-guards.template.json b/agent-system/templates/review-guards.template.json
new file mode 100644
index 0000000..f20e29b
--- /dev/null
+++ b/agent-system/templates/review-guards.template.json
@@ -0,0 +1,15 @@
+{
+  "task_id": "TASK-0001",
+  "verdict": "pass",
+  "checked_guard_ids": [
+    "GR-CORE-001",
+    "GR-CORE-003",
+    "GR-CORE-005"
+  ],
+  "checked_quality_gate_ids": [
+    "QG-001",
+    "QG-002",
+    "QG-003"
+  ],
+  "findings": []
+}
diff --git a/config/assets.php b/config/assets.php
index 3dcf5d0..10809ac 100644
--- a/config/assets.php
+++ b/config/assets.php
@@ -35,6 +35,7 @@ return [
                 'css/components/app-list-toolbar.css',
                 'css/components/app-filter-drawer.css',
                 'css/components/app-active-filter-chips.css',
+                'css/components/app-confirm-dialog.css',
                 'css/components/app-breadcrumb.css',
                 'css/components/app-tile.css',
                 'css/components/app-tooltips.css',
diff --git a/config/settings.php b/config/settings.php
index dfb5d85..b891d0a 100644
--- a/config/settings.php
+++ b/config/settings.php
@@ -11,4 +11,7 @@ return [
     'api_token_max_ttl_days' => '365',
     'api_cors_allowed_origins' => 'http://localhost:8080
 http://127.0.0.1:8080',
+    'frontend_telemetry_enabled' => '1',
+    'frontend_telemetry_sample_rate' => '0.2',
+    'frontend_telemetry_allowed_events' => 'warn_once,ajax_error',
 ];
diff --git a/db/init/init.sql b/db/init/init.sql
index 46c88cd..6f4b4ce 100644
--- a/db/init/init.sql
+++ b/db/init/init.sql
@@ -892,7 +892,9 @@ ON DUPLICATE KEY UPDATE role_id = role_id;
 INSERT INTO `settings` (`key`, `value`, `description`)
 VALUES
   ('system_audit_enabled', '1', 'setting.system_audit_enabled'),
-  ('system_audit_retention_days', '365', 'setting.system_audit_retention_days')
+  ('system_audit_retention_days', '365', 'setting.system_audit_retention_days'),
+  ('frontend_telemetry_enabled', '0', 'setting.frontend_telemetry_enabled'),
+  ('frontend_telemetry_sample_rate', '0.2', 'setting.frontend_telemetry_sample_rate'),
+  ('frontend_telemetry_allowed_events', 'warn_once,ajax_error', 'setting.frontend_telemetry_allowed_events')
 ON DUPLICATE KEY UPDATE
-  `value` = VALUES(`value`),
-  `description` = VALUES(`description`);
+  `key` = `key`;
diff --git a/db/updates/2026-03-05-frontend-telemetry-settings.sql b/db/updates/2026-03-05-frontend-telemetry-settings.sql
new file mode 100644
index 0000000..52a5f16
--- /dev/null
+++ b/db/updates/2026-03-05-frontend-telemetry-settings.sql
@@ -0,0 +1,9 @@
+-- Idempotent update: add frontend telemetry settings defaults.
+
+INSERT INTO `settings` (`key`, `value`, `description`)
+VALUES
+  ('frontend_telemetry_enabled', '0', 'setting.frontend_telemetry_enabled'),
+  ('frontend_telemetry_sample_rate', '0.2', 'setting.frontend_telemetry_sample_rate'),
+  ('frontend_telemetry_allowed_events', 'warn_once,ajax_error', 'setting.frontend_telemetry_allowed_events')
+ON DUPLICATE KEY UPDATE
+  `key` = `key`;
diff --git a/docs/agents/flow.md b/docs/agents/flow.md
new file mode 100644
index 0000000..46e4d65
--- /dev/null
+++ b/docs/agents/flow.md
@@ -0,0 +1,40 @@
+# Agent Workflow
+
+## State Machine
+- `planned`
+- `executing`
+- `review_guard`
+- `review_acceptance`
+- `finalize`
+- `done`
+
+If a reviewer returns `FAIL`, state goes back to `executing` with explicit findings.
+
+## Minimum Handover Artifacts
+- Planner: `plan.json`
+- Executor: `execution-report.json`
+- Reviewer Guards: `review-guards.json`
+- Reviewer Acceptance: `review-acceptance.json`
+- Finalizer: `finalize.json`
+
+## Guard and Gate Binding
+- Planner selects required guard IDs from `agent-system/checks/guard-catalog.json`.
+- Planner selects required quality gate IDs from `agent-system/checks/quality-gates.json`.
+- Planner assigns stable success criteria IDs (`SC-*`) in `plan.json`.
+- Executor must provide guard evidence and gate results by ID.
+- Guard reviewer verifies and reports verdict against the same IDs.
+- Acceptance reviewer verifies and reports verdict against the same `SC-*` IDs.
+
+## Fail Loop Rule
+- No free-text "please improve".
+- Every fail must include:
+  - `id`
+  - `severity`
+  - `file`
+  - expected fix
+
+## Practical Rollout
+- Start with one small issue.
+- Run workflow manually with templates.
+- Stabilize contracts first.
+- Add automation only after 3 to 5 successful runs.
diff --git a/docs/agents/overview.md b/docs/agents/overview.md
new file mode 100644
index 0000000..2a09276
--- /dev/null
+++ b/docs/agents/overview.md
@@ -0,0 +1,27 @@
+# Agent Workflow Overview
+
+This project uses a multi-role workflow for issue and feature delivery.
+
+Roles:
+- Planner
+- Executor
+- Reviewer (guards and best practices)
+- Reviewer (feature acceptance)
+- Finalizer
+
+Primary goals:
+- predictable handovers
+- strict quality gates
+- fast retry loop from reviewers back to executor
+- explicit guard and gate IDs (`GR-*`, `QG-*`) across all roles
+
+Source of truth:
+- guardrails and planning standards in `tools/codex-skills/`
+- contracts and templates in `agent-system/`
+- guard catalog: `agent-system/checks/guard-catalog.json`
+- quality gates: `agent-system/checks/quality-gates.json`
+
+Entry points:
+- roles: `docs/agents/roles.md`
+- workflow: `docs/agents/flow.md`
+- schemas and prompts: `agent-system/`
diff --git a/docs/agents/roles.md b/docs/agents/roles.md
new file mode 100644
index 0000000..7475bfb
--- /dev/null
+++ b/docs/agents/roles.md
@@ -0,0 +1,47 @@
+# Agent Roles
+
+## Planner
+- Input: issue or feature request
+- Output: `plan.json` (see `agent-system/contracts/planner.schema.json`)
+- Must define:
+  - scope in and out
+  - required guard IDs (`GR-*`)
+  - required quality gate IDs (`QG-*`)
+  - success criteria with stable IDs (`SC-*`)
+  - implementation steps
+  - test and acceptance checks
+  - risks and mitigations
+
+## Executor
+- Input: approved `plan.json`
+- Output: `execution-report.json`
+- Must:
+  - implement the plan
+  - run relevant checks
+  - document changed files and commands
+
+## Reviewer Guards
+- Input: code diff and `execution-report.json`
+- Output: `review-guards.json`
+- Focus:
+  - architecture boundaries
+  - security
+  - coding standards
+  - guardrail compliance
+  - explicit validation against required `GR-*` and `QG-*` IDs
+
+## Reviewer Acceptance
+- Input: code diff and plan success criteria
+- Output: `review-acceptance.json`
+- Focus:
+  - feature correctness
+  - edge cases
+  - acceptance criteria coverage
+  - explicit check mapping by `SC-*` criterion IDs from `plan.json`
+
+## Finalizer
+- Input: both review files with PASS verdict
+- Output: `finalize.json`
+- Must:
+  - verify gates are green
+  - prepare merge and commit metadata
diff --git a/docs/frontend-javascript.md b/docs/frontend-javascript.md
index 3295168..8acdf6b 100644
--- a/docs/frontend-javascript.md
+++ b/docs/frontend-javascript.md
@@ -1,6 +1,6 @@
 # Frontend JavaScript
 
-Letzte Aktualisierung: 2026-03-04
+Letzte Aktualisierung: 2026-03-05
 
 ## Ordnerstruktur
 
@@ -283,9 +283,24 @@ Für standardisierte Detailseiten gilt zusätzlich:
 Für allgemeine Form-/Button-Confirms außerhalb der Detail-Policy gilt:
 
 - zentral über `web/js/components/app-confirm-actions.js`
-- Confirm-Text über `data-confirm-message`
+- Dialog-Engine zentral über `web/js/core/app-confirm-dialog.js` (`confirmDialog.confirm(...)`)
+- Confirm-Text über `data-confirm-message` bzw. auf Detail-Aktionen `data-detail-confirm-message`
+- optionale Dialog-Meta über
+  - `data-confirm-title`, `data-confirm-confirm-label`, `data-confirm-cancel-label`, `data-confirm-variant`, `data-confirm-focus`
+  - analog für Detail-Aktionen: `data-detail-confirm-*`
+- kein direktes `window.confirm(...)` in App-JS
 - keine inline `onclick="return confirm(...)"` / `onsubmit="return confirm(...)"` verwenden
 
+### Frontend Telemetry Standard
+
+Für UX-/Fehler-Telemetrie im Frontend gilt:
+
+- zentral über `web/js/core/app-telemetry.js` (`telemetry.capture(...)`)
+- `warnOnce(...)` sendet standardisiert `frontend.warn_once`
+- AJAX-/Fetch-Fehler laufen zentral über den globalen Fetch-Hook als `frontend.ajax_error`
+- keine neuen Console-only-Warnpfade für relevante UX-Probleme ohne Telemetrie
+- Payloads nur mit Whitelist-Feldern und ohne sensitive Rohdaten (keine Tokens/Query-Parameter/Stacktraces)
+
 ### Detail Validation Summary Standard
 
 Für serverseitige Formularfehler in Create/Edit-Templates gilt:
diff --git a/docs/index.md b/docs/index.md
index ad38ec8..c8731b6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -91,3 +91,14 @@ Diese Dokumentation folgt einem klaren Lernpfad (einfach -> fortgeschritten) und
   - Standard-Prompts für Skill-basierte Planung und Implementierung.
 - `/docs/dokumentation-erweitern.md`
   - Regeln für konsistente, wachsende Doku.
+
+## Agent Workflow
+
+- `/docs/agents/overview.md`
+  - Einstieg in das Rollenmodell und die Artefakte.
+- `/docs/agents/roles.md`
+  - Klare Verantwortung je Rolle (Planner, Executor, Reviewer, Finalizer).
+- `/docs/agents/flow.md`
+  - State-Flow mit Fail-Loop zur Executor-Iteration.
+- `/agent-system/README.md`
+  - Technische Basis mit Contracts, Templates, Prompts und Checks.
diff --git a/i18n/default_de.json b/i18n/default_de.json
index 2b4236a..fb2d651 100644
--- a/i18n/default_de.json
+++ b/i18n/default_de.json
@@ -190,6 +190,10 @@
   "Save": "Speichern",
   "Save & close": "Speichern & schließen",
   "Cancel": "Abbrechen",
+  "Close": "Schließen",
+  "Confirm": "Bestätigen",
+  "Please confirm": "Bitte bestätigen",
+  "This action cannot be undone.": "Diese Aktion kann nicht rückgängig gemacht werden.",
   "Active": "Aktiv",
   "Actions": "Aktionen",
   "ID": "ID",
@@ -342,6 +346,7 @@
   "New folder": "Neuer Ordner",
   "Toggle navigation": "Navigation umschalten",
   "Primary navigation": "Hauptnavigation",
+  "Footer navigation": "Fußzeilen-Navigation",
   "Language switcher": "Sprachauswahl",
   "Sort column ascending": "Spalte aufsteigend sortieren",
   "Sort column descending": "Spalte absteigend sortieren",
@@ -683,9 +688,9 @@
   "Keyboard shortcuts": "Tastenkürzel",
   "Open search": "Suche öffnen",
   "Save in edit pages": "Auf Bearbeitungsseiten speichern",
-  "Unsaved changes": "Ungespeicherte Änderungen",
-  "Unsaved change (%d field)": "Ungespeicherte Änderung (%d geändertes Feld)",
-  "Unsaved changes (%d fields)": "Ungespeicherte Änderungen (%d geänderte Felder)",
+  "Unsaved changes": "Ungespeichert",
+  "Unsaved change (%d field)": "Ungespeichert (%d Feld)",
+  "Unsaved changes (%d fields)": "Ungespeichert (%d Felder)",
   "Please review the following errors": "Bitte prüfen Sie die folgenden Fehler",
   "You have unsaved changes. Leave without saving?": "Sie haben ungespeicherte Änderungen. Seite ohne Speichern verlassen?",
   "Switch sidebar section": "Sidebar-Bereich wechseln",
@@ -1155,8 +1160,26 @@
   "User #%d": "Benutzer #%d",
   "User #%d (deleted)": "Benutzer #%d (gelöscht)",
   "Retention (days)": "Aufbewahrung (Tage)",
+  "Frontend telemetry": "Frontend-Telemetrie",
+  "Enable frontend telemetry": "Frontend-Telemetrie aktivieren",
+  "Sampling rate": "Sampling-Rate",
+  "Sampling rate (0-1)": "Sampling-Rate (0-1)",
+  "Allowed telemetry events": "Erlaubte Telemetrie-Ereignisse",
+  "warnOnce warnings": "warnOnce-Warnungen",
+  "AJAX errors": "AJAX-Fehler",
+  "Telemetry": "Telemetrie",
+  "Telemetry helps us find UI problems faster.": "Telemetrie hilft uns, UI-Probleme schneller zu finden.",
+  "No sensitive data is stored.": "Es werden keine sensiblen Daten gespeichert.",
+  "Sampling rate defines how many events are saved.": "Die Sampling-Rate bestimmt, wie viele Ereignisse gespeichert werden.",
+  "The percentage of users who will have telemetry enabled.": "Der Anteil der Nutzer, für die Telemetrie aktiv ist.",
+  "Example: 0.2 means about 2 of 10 events.": "Beispiel: 0,2 bedeutet etwa 2 von 10 Ereignissen.",
+  "Advanced telemetry options": "Erweiterte Telemetrie-Optionen",
+  "Only change these options if needed.": "Diese Optionen nur bei Bedarf anpassen.",
   "setting.system_audit_enabled": "System-Protokolle aktivieren/deaktivieren",
   "setting.system_audit_retention_days": "Aufbewahrungsdauer in Tagen für System-Protokoll-Einträge",
+  "setting.frontend_telemetry_enabled": "Sichere Frontend-UX- und Fehler-Telemetrie aktivieren/deaktivieren",
+  "setting.frontend_telemetry_sample_rate": "Sampling-Rate zwischen 0 und 1 für akzeptierte Frontend-Telemetrie-Ereignisse",
+  "setting.frontend_telemetry_allowed_events": "Erlaubte Frontend-Telemetrie-Ereignisgruppen (warn_once, ajax_error)",
   "System audit events (24h)": "System-Protokoll-Ereignisse (24h)",
   "System audit risks (24h)": "System-Protokoll-Risiken (24h)",
   "Failed outcomes (24h)": "Fehlgeschlagene Ergebnisse (24h)",
diff --git a/i18n/default_en.json b/i18n/default_en.json
index 4431429..85e1db4 100644
--- a/i18n/default_en.json
+++ b/i18n/default_en.json
@@ -190,6 +190,10 @@
   "Save": "Save",
   "Save & close": "Save & close",
   "Cancel": "Cancel",
+  "Close": "Close",
+  "Confirm": "Confirm",
+  "Please confirm": "Please confirm",
+  "This action cannot be undone.": "This action cannot be undone.",
   "Active": "Active",
   "Actions": "Actions",
   "ID": "ID",
@@ -342,6 +346,7 @@
   "New folder": "New folder",
   "Toggle navigation": "Toggle navigation",
   "Primary navigation": "Primary navigation",
+  "Footer navigation": "Footer navigation",
   "Language switcher": "Language switcher",
   "Sort column ascending": "Sort column ascending",
   "Sort column descending": "Sort column descending",
@@ -1155,8 +1160,26 @@
   "User #%d": "User #%d",
   "User #%d (deleted)": "User #%d (deleted)",
   "Retention (days)": "Retention (days)",
+  "Frontend telemetry": "Frontend telemetry",
+  "Enable frontend telemetry": "Enable frontend telemetry",
+  "Sampling rate": "Sampling rate",
+  "Sampling rate (0-1)": "Sampling rate (0-1)",
+  "Allowed telemetry events": "Allowed telemetry events",
+  "warnOnce warnings": "warnOnce warnings",
+  "AJAX errors": "AJAX errors",
+  "Telemetry": "Telemetry",
+  "Telemetry helps us find UI problems faster.": "Telemetry helps us find UI problems faster.",
+  "No sensitive data is stored.": "No sensitive data is stored.",
+  "Sampling rate defines how many events are saved.": "Sampling rate defines how many events are saved.",
+  "The percentage of users who will have telemetry enabled.": "The percentage of users who will have telemetry enabled.",
+  "Example: 0.2 means about 2 of 10 events.": "Example: 0.2 means about 2 of 10 events.",
+  "Advanced telemetry options": "Advanced telemetry options",
+  "Only change these options if needed.": "Only change these options if needed.",
   "setting.system_audit_enabled": "Enable/disable system audit logging",
   "setting.system_audit_retention_days": "Retention in days for system audit entries",
+  "setting.frontend_telemetry_enabled": "Enable/disable secure frontend UX and error telemetry",
+  "setting.frontend_telemetry_sample_rate": "Sampling rate between 0 and 1 for accepted frontend telemetry events",
+  "setting.frontend_telemetry_allowed_events": "Allowed frontend telemetry event groups (warn_once, ajax_error)",
   "System audit events (24h)": "System audit events (24h)",
   "System audit risks (24h)": "System audit risks (24h)",
   "Failed outcomes (24h)": "Failed outcomes (24h)",
diff --git a/lib/App/AppContainer.php b/lib/App/AppContainer.php
index dfc5bf7..b62c11c 100644
--- a/lib/App/AppContainer.php
+++ b/lib/App/AppContainer.php
@@ -4,6 +4,8 @@ namespace MintyPHP\App;
 
 use RuntimeException;
 
+// Minimal DI container: factories are registered with set() and resolved lazily on first get().
+// Each service is instantiated at most once — get() returns the same instance on every call.
 final class AppContainer
 {
     /** @var array<string, callable(self): mixed> */
@@ -32,6 +34,7 @@ final class AppContainer
             throw new RuntimeException('Service not bound: ' . $id);
         }
 
+        // Resolve, cache, and return — factory receives the container for its own dependencies.
         $this->instances[$id] = ($this->bindings[$id])($this);
         return $this->instances[$id];
     }
diff --git a/lib/App/Bootstrap/EnvValidator.php b/lib/App/Bootstrap/EnvValidator.php
index 2391ace..2b0323d 100644
--- a/lib/App/Bootstrap/EnvValidator.php
+++ b/lib/App/Bootstrap/EnvValidator.php
@@ -52,6 +52,7 @@ final class EnvValidator
         );
     }
 
+    // Validation is on by default; set APP_CONFIG_VALIDATE=false to skip (e.g. in CI without full env).
     public static function isValidationEnabled(): bool
     {
         $raw = getenv('APP_CONFIG_VALIDATE');
@@ -188,6 +189,7 @@ final class EnvValidator
             }
         }
 
+        // Production-only hard requirements: HTTPS, real hostname, crypto key, debug off, strict tenant scope.
         if ($appEnv === 'prod') {
             if ($appUrl !== '' && $appUrlIsValid) {
                 $appUrlScheme = strtolower((string) parse_url($appUrl, PHP_URL_SCHEME));
@@ -270,6 +272,7 @@ final class EnvValidator
         return array_values(array_filter(array_map('trim', explode(',', $value))));
     }
 
+    // Accepts either 64-char hex (32 bytes) or base64-encoded 32 bytes — both produce a 256-bit key.
     private static function isValidCryptoKey(string $value): bool
     {
         if (preg_match('/^[a-f0-9]{64}$/i', $value) === 1) {
diff --git a/lib/App/Container/Registrars/AccessRegistrar.php b/lib/App/Container/Registrars/AccessRegistrar.php
index 428e2ef..24c8cc2 100644
--- a/lib/App/Container/Registrars/AccessRegistrar.php
+++ b/lib/App/Container/Registrars/AccessRegistrar.php
@@ -25,6 +25,8 @@ final class AccessRegistrar implements ContainerRegistrar
             $c->get(AuthorizationService::class)
         ));
         $container->set(PermissionService::class, static fn (AppContainer $c): PermissionService => $c->get(AccessServicesFactory::class)->createPermissionService());
+        // RoleService lives in DirectoryServicesFactory (not AccessServicesFactory) because
+        // role management involves directory-level concerns (departments, tenant structure).
         $container->set(RoleService::class, static fn (AppContainer $c): RoleService => $c->get(DirectoryServicesFactory::class)->createRoleService());
         $container->set(PermissionRepository::class, static fn (AppContainer $c): PermissionRepository => $c->get(AccessServicesFactory::class)->createPermissionRepository());
         $container->set(RolePermissionRepository::class, static fn (AppContainer $c): RolePermissionRepository => $c->get(AccessServicesFactory::class)->createRolePermissionRepository());
diff --git a/lib/App/Container/Registrars/AppServicesRegistrar.php b/lib/App/Container/Registrars/AppServicesRegistrar.php
index b3087bb..adc1ed5 100644
--- a/lib/App/Container/Registrars/AppServicesRegistrar.php
+++ b/lib/App/Container/Registrars/AppServicesRegistrar.php
@@ -5,7 +5,13 @@ namespace MintyPHP\App\Container\Registrars;
 use MintyPHP\App\AppContainer;
 use MintyPHP\App\Container\ContainerRegistrar;
 use MintyPHP\Http\ApiSystemAuditReporter;
+use MintyPHP\Http\CookieStore;
+use MintyPHP\Http\CookieStoreInterface;
 use MintyPHP\Http\Input\RequestInputFactory;
+use MintyPHP\Http\RequestRuntime;
+use MintyPHP\Http\RequestRuntimeInterface;
+use MintyPHP\Http\SessionStore;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Search\SearchQueryRepository;
 use MintyPHP\Repository\Stats\AdminStatsRepository;
 use MintyPHP\Repository\Tenant\UserTenantRepository;
@@ -14,6 +20,7 @@ use MintyPHP\Service\AddressBook\AddressBookService;
 use MintyPHP\Service\AddressBook\AddressBookServicesFactory;
 use MintyPHP\Service\Audit\ApiAuditService;
 use MintyPHP\Service\Audit\AuditServicesFactory;
+use MintyPHP\Service\Audit\FrontendTelemetryIngestService;
 use MintyPHP\Service\Audit\ImportAuditService;
 use MintyPHP\Service\Audit\SystemAuditService;
 use MintyPHP\Service\Audit\UserLifecycleAuditService;
@@ -31,6 +38,7 @@ use MintyPHP\Service\Scheduler\SchedulerServicesFactory;
 use MintyPHP\Service\Search\SearchDataService;
 use MintyPHP\Service\Security\RateLimiterService;
 use MintyPHP\Service\Security\SecurityServicesFactory;
+use MintyPHP\Service\Settings\SettingsFrontendTelemetryGateway;
 use MintyPHP\Service\Stats\AdminStatsViewDataService;
 
 final class AppServicesRegistrar implements ContainerRegistrar
@@ -51,6 +59,12 @@ final class AppServicesRegistrar implements ContainerRegistrar
         $container->set(ApiAuditService::class, static fn (AppContainer $c): ApiAuditService => $c->get(AuditServicesFactory::class)->createApiAuditService());
         $container->set(UserLifecycleAuditService::class, static fn (AppContainer $c): UserLifecycleAuditService => $c->get(AuditServicesFactory::class)->createUserLifecycleAuditService());
         $container->set(SystemAuditService::class, static fn (AppContainer $c): SystemAuditService => $c->get(AuditServicesFactory::class)->createSystemAuditService());
+        $container->set(FrontendTelemetryIngestService::class, static fn (AppContainer $c): FrontendTelemetryIngestService => new FrontendTelemetryIngestService(
+            $c->get(SystemAuditService::class),
+            $c->get(SettingsFrontendTelemetryGateway::class),
+            $c->get(RateLimiterService::class),
+            $c->get(SessionStoreInterface::class)
+        ));
         $container->set(ApiSystemAuditReporter::class, static fn (AppContainer $c): ApiSystemAuditReporter => new ApiSystemAuditReporter(
             $c->get(SystemAuditService::class)
         ));
@@ -62,5 +76,11 @@ final class AppServicesRegistrar implements ContainerRegistrar
         $container->set(TenantCustomFieldService::class, static fn (AppContainer $c): TenantCustomFieldService => $c->get(CustomFieldServicesFactory::class)->createTenantCustomFieldService());
         $container->set(UserCustomFieldValueService::class, static fn (AppContainer $c): UserCustomFieldValueService => $c->get(CustomFieldServicesFactory::class)->createUserCustomFieldValueService());
         $container->set(RequestInputFactory::class, static fn (): RequestInputFactory => new RequestInputFactory());
+        $container->set(SessionStore::class, static fn (): SessionStore => new SessionStore());
+        $container->set(SessionStoreInterface::class, static fn (AppContainer $c): SessionStoreInterface => $c->get(SessionStore::class));
+        $container->set(CookieStore::class, static fn (): CookieStore => new CookieStore());
+        $container->set(CookieStoreInterface::class, static fn (AppContainer $c): CookieStoreInterface => $c->get(CookieStore::class));
+        $container->set(RequestRuntime::class, static fn (): RequestRuntime => new RequestRuntime());
+        $container->set(RequestRuntimeInterface::class, static fn (AppContainer $c): RequestRuntimeInterface => $c->get(RequestRuntime::class));
     }
 }
diff --git a/lib/App/Container/Registrars/RepositoryFactoryRegistrar.php b/lib/App/Container/Registrars/RepositoryFactoryRegistrar.php
index b5de229..7d5873f 100644
--- a/lib/App/Container/Registrars/RepositoryFactoryRegistrar.php
+++ b/lib/App/Container/Registrars/RepositoryFactoryRegistrar.php
@@ -34,6 +34,7 @@ final class RepositoryFactoryRegistrar implements ContainerRegistrar
         $container->set(AccessRepositoryFactory::class, static fn (): AccessRepositoryFactory => new AccessRepositoryFactory());
         $container->set(UserRepositoryFactory::class, static fn (): UserRepositoryFactory => new UserRepositoryFactory());
         $container->set(AuthRepositoryFactory::class, static fn (): AuthRepositoryFactory => new AuthRepositoryFactory());
+        // These repositories have no factory because they're standalone — no shared config or gateway needed.
         $container->set(AdminStatsRepository::class, static fn (): AdminStatsRepository => new AdminStatsRepository());
         $container->set(SearchQueryRepository::class, static fn (): SearchQueryRepository => new SearchQueryRepository());
         $container->set(DatabaseSessionRepository::class, static fn (): DatabaseSessionRepository => new DatabaseSessionRepository());
diff --git a/lib/App/Container/Registrars/ServiceFactoryRegistrar.php b/lib/App/Container/Registrars/ServiceFactoryRegistrar.php
index 1be29cf..003c09b 100644
--- a/lib/App/Container/Registrars/ServiceFactoryRegistrar.php
+++ b/lib/App/Container/Registrars/ServiceFactoryRegistrar.php
@@ -4,6 +4,9 @@ namespace MintyPHP\App\Container\Registrars;
 
 use MintyPHP\App\AppContainer;
 use MintyPHP\App\Container\ContainerRegistrar;
+use MintyPHP\Http\CookieStoreInterface;
+use MintyPHP\Http\RequestRuntimeInterface;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Support\DatabaseSessionRepository;
 use MintyPHP\Repository\Tenant\TenantRepository;
 use MintyPHP\Service\Access\AccessGatewayFactory;
@@ -31,7 +34,6 @@ use MintyPHP\Service\Scheduler\SchedulerRepositoryFactory;
 use MintyPHP\Service\Scheduler\SchedulerServicesFactory;
 use MintyPHP\Service\Security\SecurityRepositoryFactory;
 use MintyPHP\Service\Security\SecurityServicesFactory;
-use MintyPHP\Service\Settings\SettingGateway;
 use MintyPHP\Service\Settings\SettingRepositoryFactory;
 use MintyPHP\Service\Settings\SettingServicesFactory;
 use MintyPHP\Service\Tenant\TenantRepositoryFactory;
@@ -51,17 +53,19 @@ final class ServiceFactoryRegistrar implements ContainerRegistrar
         ));
         $container->set(AuditServicesFactory::class, static fn (AppContainer $c): AuditServicesFactory => new AuditServicesFactory(
             $c->get(AuditRepositoryFactory::class),
-            $c->get(SettingGateway::class)
+            $c->get(SettingServicesFactory::class)->createSettingsSystemAuditGateway(),
+            $c->get(RequestRuntimeInterface::class),
+            $c->get(SessionStoreInterface::class)
         ));
         $container->set(SecurityServicesFactory::class, static fn (AppContainer $c): SecurityServicesFactory => new SecurityServicesFactory(
             $c->get(SecurityRepositoryFactory::class)
         ));
         $container->set(MailServicesFactory::class, static fn (AppContainer $c): MailServicesFactory => new MailServicesFactory(
             $c->get(MailRepositoryFactory::class),
-            $c->get(SettingGateway::class)
+            $c->get(SettingServicesFactory::class)->createSettingsSmtpGateway()
         ));
         $container->set(BrandingServicesFactory::class, static fn (AppContainer $c): BrandingServicesFactory => new BrandingServicesFactory(
-            $c->get(SettingGateway::class)
+            $c->get(SettingServicesFactory::class)->createSettingsAppGateway()
         ));
         $container->set(CustomFieldServicesFactory::class, static fn (AppContainer $c): CustomFieldServicesFactory => new CustomFieldServicesFactory(
             $c->get(TenantRepository::class),
@@ -76,7 +80,8 @@ final class ServiceFactoryRegistrar implements ContainerRegistrar
             $c->get(AccessServicesFactory::class),
             $c->get(SettingServicesFactory::class),
             $c->get(DirectoryServicesFactory::class),
-            $c->get(ImportRepositoryFactory::class)
+            $c->get(ImportRepositoryFactory::class),
+            $c->get(SessionStoreInterface::class)
         ));
         $container->set(SchedulerServicesFactory::class, static fn (AppContainer $c): SchedulerServicesFactory => new SchedulerServicesFactory(
             $c->get(UserServicesFactory::class),
@@ -102,11 +107,14 @@ final class ServiceFactoryRegistrar implements ContainerRegistrar
         $container->set(AccessServicesFactory::class, static fn (AppContainer $c): AccessServicesFactory => new AccessServicesFactory(
             $c->get(AccessRepositoryFactory::class),
             $c->get(AccessGatewayFactory::class),
+            // Wrapped in a second closure to break the circular dependency:
+            // AccessServicesFactory <-> AccessPolicyFactory via PermissionGateway.
             static fn (): AccessPolicyFactory => $c->get(AccessPolicyFactory::class)
         ));
         $container->set(AccessGatewayFactory::class, static fn (AppContainer $c): AccessGatewayFactory => new AccessGatewayFactory(
             $c->get(AccessRepositoryFactory::class),
-            $c->get(AuditServicesFactory::class)
+            $c->get(AuditServicesFactory::class),
+            $c->get(SessionStoreInterface::class)
         ));
         $container->set(AccessPolicyFactory::class, static fn (AppContainer $c): AccessPolicyFactory => new AccessPolicyFactory(
             $c->get(PermissionGateway::class),
@@ -137,7 +145,10 @@ final class ServiceFactoryRegistrar implements ContainerRegistrar
             $c->get(MailServicesFactory::class),
             $c->get(AuthRepositoryFactory::class),
             $c->get(AuthGatewayFactory::class),
-            $c->get(DatabaseSessionRepository::class)
+            $c->get(DatabaseSessionRepository::class),
+            $c->get(SessionStoreInterface::class),
+            $c->get(CookieStoreInterface::class),
+            $c->get(RequestRuntimeInterface::class)
         ));
     }
 }
diff --git a/lib/App/Container/Registrars/SettingsRegistrar.php b/lib/App/Container/Registrars/SettingsRegistrar.php
index 5cdd182..206e5f9 100644
--- a/lib/App/Container/Registrars/SettingsRegistrar.php
+++ b/lib/App/Container/Registrars/SettingsRegistrar.php
@@ -14,9 +14,16 @@ use MintyPHP\Service\Branding\BrandingServicesFactory;
 use MintyPHP\Service\Org\DepartmentService;
 use MintyPHP\Service\Settings\AdminSettingsService;
 use MintyPHP\Service\Settings\SettingCacheService;
-use MintyPHP\Service\Settings\SettingGateway;
-use MintyPHP\Service\Settings\SettingService;
 use MintyPHP\Service\Settings\SettingServicesFactory;
+use MintyPHP\Service\Settings\SettingsApiPolicyGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsFrontendTelemetryGateway;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use MintyPHP\Service\Settings\SettingsMicrosoftGateway;
+use MintyPHP\Service\Settings\SettingsSmtpGateway;
+use MintyPHP\Service\Settings\SettingsSystemAuditGateway;
+use MintyPHP\Service\Settings\SettingsUserLifecycleGateway;
 use MintyPHP\Service\Settings\ThemeConfigService;
 use MintyPHP\Service\Tenant\TenantService;
 
@@ -24,11 +31,26 @@ final class SettingsRegistrar implements ContainerRegistrar
 {
     public function register(AppContainer $container): void
     {
-        $container->set(SettingService::class, static fn (AppContainer $c): SettingService => $c->get(SettingServicesFactory::class)->createSettingService());
-        $container->set(SettingGateway::class, static fn (AppContainer $c): SettingGateway => $c->get(SettingServicesFactory::class)->createSettingGateway());
+        $container->set(SettingsMetadataGateway::class, static fn (AppContainer $c): SettingsMetadataGateway => $c->get(SettingServicesFactory::class)->createSettingsMetadataGateway());
+        $container->set(SettingsDefaultsGateway::class, static fn (AppContainer $c): SettingsDefaultsGateway => $c->get(SettingServicesFactory::class)->createSettingsDefaultsGateway());
+        $container->set(SettingsAppGateway::class, static fn (AppContainer $c): SettingsAppGateway => $c->get(SettingServicesFactory::class)->createSettingsAppGateway());
+        $container->set(SettingsApiPolicyGateway::class, static fn (AppContainer $c): SettingsApiPolicyGateway => $c->get(SettingServicesFactory::class)->createSettingsApiPolicyGateway());
+        $container->set(SettingsUserLifecycleGateway::class, static fn (AppContainer $c): SettingsUserLifecycleGateway => $c->get(SettingServicesFactory::class)->createSettingsUserLifecycleGateway());
+        $container->set(SettingsSystemAuditGateway::class, static fn (AppContainer $c): SettingsSystemAuditGateway => $c->get(SettingServicesFactory::class)->createSettingsSystemAuditGateway());
+        $container->set(SettingsFrontendTelemetryGateway::class, static fn (AppContainer $c): SettingsFrontendTelemetryGateway => $c->get(SettingServicesFactory::class)->createSettingsFrontendTelemetryGateway());
+        $container->set(SettingsMicrosoftGateway::class, static fn (AppContainer $c): SettingsMicrosoftGateway => $c->get(SettingServicesFactory::class)->createSettingsMicrosoftGateway());
+        $container->set(SettingsSmtpGateway::class, static fn (AppContainer $c): SettingsSmtpGateway => $c->get(SettingServicesFactory::class)->createSettingsSmtpGateway());
         $container->set(SettingCacheService::class, static fn (AppContainer $c): SettingCacheService => $c->get(SettingServicesFactory::class)->createSettingCacheService());
         $container->set(AdminSettingsService::class, static fn (AppContainer $c): AdminSettingsService => new AdminSettingsService(
-            $c->get(SettingGateway::class),
+            $c->get(SettingsDefaultsGateway::class),
+            $c->get(SettingsAppGateway::class),
+            $c->get(SettingsApiPolicyGateway::class),
+            $c->get(SettingsUserLifecycleGateway::class),
+            $c->get(SettingsSystemAuditGateway::class),
+            $c->get(SettingsFrontendTelemetryGateway::class),
+            $c->get(SettingsMicrosoftGateway::class),
+            $c->get(SettingsSmtpGateway::class),
+            $c->get(SettingsMetadataGateway::class),
             $c->get(SettingCacheService::class),
             $c->get(TenantService::class),
             $c->get(RoleService::class),
@@ -38,6 +60,8 @@ final class SettingsRegistrar implements ContainerRegistrar
             $c->get(SystemAuditService::class)
         ));
         $container->set(ThemeConfigService::class, static fn (AppContainer $c): ThemeConfigService => $c->get(SettingServicesFactory::class)->createThemeConfigService());
+        // Branding services are registered here because they depend on settings gateways
+        // and are consumed alongside settings (e.g. in UserAccessPdfService and the admin UI).
         $container->set(BrandingLogoService::class, static fn (AppContainer $c): BrandingLogoService => $c->get(BrandingServicesFactory::class)->createBrandingLogoService());
         $container->set(BrandingFaviconService::class, static fn (AppContainer $c): BrandingFaviconService => $c->get(BrandingServicesFactory::class)->createBrandingFaviconService());
     }
diff --git a/lib/App/registerContainer.php b/lib/App/registerContainer.php
index 05f470e..c9c5d54 100644
--- a/lib/App/registerContainer.php
+++ b/lib/App/registerContainer.php
@@ -12,15 +12,17 @@ use MintyPHP\App\Container\Registrars\UserRegistrar;
 
 $container = new AppContainer();
 
+// Order matters: RepositoryFactoryRegistrar and ServiceFactoryRegistrar must run first
+// because later registrars pull concrete services from those factories.
 $registrars = [
-    new RepositoryFactoryRegistrar(),
-    new ServiceFactoryRegistrar(),
-    new AccessRegistrar(),
-    new AuthRegistrar(),
-    new DirectoryRegistrar(),
-    new UserRegistrar(),
-    new SettingsRegistrar(),
-    new AppServicesRegistrar(),
+    new RepositoryFactoryRegistrar(),   // raw repository factories (no deps)
+    new ServiceFactoryRegistrar(),      // service factories wired with their repo/gateway deps
+    new AccessRegistrar(),              // RBAC: permissions, roles, authorization
+    new AuthRegistrar(),               // authentication, SSO, tokens
+    new DirectoryRegistrar(),           // tenants, departments, scope
+    new UserRegistrar(),               // user services and repositories
+    new SettingsRegistrar(),           // settings, branding
+    new AppServicesRegistrar(),        // leaf services (stats, search, mail, scheduler, ...)
 ];
 
 foreach ($registrars as $registrar) {
diff --git a/lib/Http/ApiAuth.php b/lib/Http/ApiAuth.php
index 60bd78a..f371005 100644
--- a/lib/Http/ApiAuth.php
+++ b/lib/Http/ApiAuth.php
@@ -9,6 +9,8 @@ use MintyPHP\Service\Auth\ApiTokenService;
 use MintyPHP\Service\Auth\AuthScopeGateway;
 use MintyPHP\Service\User\UserTenantContextService;
 
+// Static facade for API authentication — state is set once per request during ApiBootstrap::init().
+// Dependencies are injected as lazy resolvers so services are only instantiated when actually needed.
 class ApiAuth
 {
     /** @var (callable(): AuthScopeGateway)|null */
@@ -58,6 +60,7 @@ class ApiAuth
     {
         $header = trim((string) ($_SERVER['HTTP_AUTHORIZATION'] ?? ''));
         if ($header === '') {
+            // Nginx with PHP-FPM may expose the header under this key instead
             $header = trim((string) ($_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? ''));
         }
         if ($header === '' || stripos($header, 'Bearer ') !== 0) {
@@ -100,9 +103,11 @@ class ApiAuth
         $roleIds = $userRoleRepository->listRoleIdsByUserId($userId);
         $permissions = $rolePermissionRepository->listPermissionKeysByRoleIds($roleIds);
 
-        // Resolve tenant context
+        // Resolve tenant context: a token may be scoped to a specific tenant,
+        // otherwise fall back to the user's active tenant context.
         $tokenTenantId = $result['tenant_id'];
         if ($tokenTenantId !== null) {
+            // Verify the token's tenant is still assigned to this user
             $userTenantIds = $scopeGateway->getUserTenantIds($userId);
             if (!in_array($tokenTenantId, $userTenantIds, true)) {
                 return false;
@@ -153,11 +158,14 @@ class ApiAuth
         return $decision->isAllowed();
     }
 
+    // Effective tenant for data filtering — may come from token scope or user session.
     public static function tenantId(): ?int
     {
         return self::$currentTenantId;
     }
 
+    // Non-null only when the token itself was issued for a specific tenant.
+    // Used to restrict access in token-scoped requests (e.g. tenant integrations).
     public static function scopedTenantId(): ?int
     {
         return self::$tokenTenantId;
@@ -204,6 +212,7 @@ class ApiAuth
 
         $scopeGateway = self::scopeGateway();
         if (!$scopeGateway->resourceBelongsToTenant($resource, $resourceId, $tenantId)) {
+            // 404 instead of 403 — don't reveal that the resource exists in another tenant
             ApiResponse::notFound();
         }
     }
diff --git a/lib/Http/ApiBootstrap.php b/lib/Http/ApiBootstrap.php
index 4237466..ed2b534 100644
--- a/lib/Http/ApiBootstrap.php
+++ b/lib/Http/ApiBootstrap.php
@@ -4,10 +4,13 @@ namespace MintyPHP\Http;
 
 use MintyPHP\Service\Audit\ApiAuditService;
 use MintyPHP\Service\Security\RateLimiterService;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsApiPolicyGateway;
 
+// Entry point bootstrapper called once at the top of every API action.
+// Handles: request context, CORS, audit start, rate limiting, and optional Bearer auth.
 class ApiBootstrap
 {
+    // Two separate rate-limit buckets: one per IP (broad), one per token+IP (fine-grained).
     private const API_RATE_SCOPE_TOKEN = 'api.token_ip';
     private const API_RATE_SCOPE_IP = 'api.ip';
     private const API_RATE_LIMIT_TOKEN = 300;
@@ -19,8 +22,8 @@ class ApiBootstrap
     private static bool $shutdownRegistered = false;
     /** @var (callable(): ApiAuditService)|null */
     private static $apiAuditServiceResolver = null;
-    /** @var (callable(): SettingGateway)|null */
-    private static $settingGatewayResolver = null;
+    /** @var (callable(): SettingsApiPolicyGateway)|null */
+    private static $settingsApiPolicyGatewayResolver = null;
     /** @var (callable(): RateLimiterService)|null */
     private static $rateLimiterServiceResolver = null;
     /** @var (callable(): ApiSystemAuditReporter)|null */
@@ -28,12 +31,12 @@ class ApiBootstrap
 
     public static function configure(
         callable $apiAuditServiceResolver,
-        callable $settingGatewayResolver,
+        callable $settingsApiPolicyGatewayResolver,
         callable $rateLimiterServiceResolver,
         callable $apiSystemAuditReporterResolver
     ): void {
         self::$apiAuditServiceResolver = $apiAuditServiceResolver;
-        self::$settingGatewayResolver = $settingGatewayResolver;
+        self::$settingsApiPolicyGatewayResolver = $settingsApiPolicyGatewayResolver;
         self::$rateLimiterServiceResolver = $rateLimiterServiceResolver;
         self::$apiSystemAuditReporterResolver = $apiSystemAuditReporterResolver;
     }
@@ -93,7 +96,7 @@ class ApiBootstrap
             return;
         }
 
-        $allowedOrigins = array_fill_keys(self::settings()->getApiCorsAllowedOrigins(), true);
+        $allowedOrigins = array_fill_keys(self::settingsApiPolicy()->getApiCorsAllowedOrigins(), true);
         if (!isset($allowedOrigins[$origin])) {
             return;
         }
@@ -105,6 +108,7 @@ class ApiBootstrap
         header('Access-Control-Max-Age: 86400');
     }
 
+    // Guarantees audit records are written even on uncaught fatal errors.
     private static function registerShutdownHandler(): void
     {
         if (self::$shutdownRegistered) {
@@ -216,6 +220,8 @@ class ApiBootstrap
         }
     }
 
+    // API tokens are formatted as "selector:verifier". The selector (24-char hex) is used
+    // as the rate-limit key so a single token can't bypass the per-IP bucket by rotating IPs.
     private static function extractBearerSelector(): string
     {
         $token = ApiAuth::extractBearerToken();
@@ -232,9 +238,13 @@ class ApiBootstrap
         return $selector;
     }
 
-    private static function settings(): SettingGateway
+    private static function settingsApiPolicy(): SettingsApiPolicyGateway
     {
-        return self::resolveDependency(self::$settingGatewayResolver, SettingGateway::class, 'ApiBootstrap');
+        return self::resolveDependency(
+            self::$settingsApiPolicyGatewayResolver,
+            SettingsApiPolicyGateway::class,
+            'ApiBootstrap'
+        );
     }
 
     private static function rateLimiter(): RateLimiterService
diff --git a/lib/Http/ApiResponse.php b/lib/Http/ApiResponse.php
index a4ed9c7..e23cba8 100644
--- a/lib/Http/ApiResponse.php
+++ b/lib/Http/ApiResponse.php
@@ -225,6 +225,7 @@ class ApiResponse
         ];
     }
 
+    // Empty details must be stdClass so json_encode produces {} instead of [].
     private static function normalizeDetails(array $details): array|\stdClass
     {
         if ($details === []) {
diff --git a/lib/Http/ApiSystemAuditReporter.php b/lib/Http/ApiSystemAuditReporter.php
index 6c7186b..de666d2 100644
--- a/lib/Http/ApiSystemAuditReporter.php
+++ b/lib/Http/ApiSystemAuditReporter.php
@@ -91,6 +91,8 @@ class ApiSystemAuditReporter
         );
     }
 
+    // Recording strategy: always log writes and server errors; for reads, only log
+    // failures on security-sensitive endpoints (auth, tokens) to keep volume manageable.
     private function shouldRecord(string $method, string $path, int $statusCode): bool
     {
         if ($method === 'OPTIONS') {
@@ -123,6 +125,8 @@ class ApiSystemAuditReporter
         return str_starts_with($path, '/api/v1/me/tokens');
     }
 
+    // Normalizes dynamic path segments (IDs, UUIDs, token selectors) so audit queries
+    // can group by endpoint pattern rather than individual resource IDs.
     private function endpointKey(string $path): string
     {
         $path = '/' . ltrim(trim($path), '/');
diff --git a/lib/Http/CookieStore.php b/lib/Http/CookieStore.php
new file mode 100644
index 0000000..aa76f2b
--- /dev/null
+++ b/lib/Http/CookieStore.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace MintyPHP\Http;
+
+class CookieStore implements CookieStoreInterface
+{
+    public function get(string $name): string
+    {
+        return (string) ($_COOKIE[$name] ?? '');
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function set(string $name, string $value, array $options = []): void
+    {
+        setcookie($name, $value, $options);
+        $_COOKIE[$name] = $value;
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function remove(string $name, array $options = []): void
+    {
+        $removeOptions = ['expires' => time() - 3600, 'path' => '/'];
+        foreach ($options as $key => $value) {
+            $removeOptions[$key] = $value;
+        }
+
+        setcookie($name, '', $removeOptions);
+        unset($_COOKIE[$name]);
+    }
+}
diff --git a/lib/Http/CookieStoreInterface.php b/lib/Http/CookieStoreInterface.php
new file mode 100644
index 0000000..938b564
--- /dev/null
+++ b/lib/Http/CookieStoreInterface.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace MintyPHP\Http;
+
+interface CookieStoreInterface
+{
+    public function get(string $name): string;
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function set(string $name, string $value, array $options = []): void;
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function remove(string $name, array $options = []): void;
+}
diff --git a/lib/Http/Input/RequestInputFactory.php b/lib/Http/Input/RequestInputFactory.php
index c7256c0..6a81cf2 100644
--- a/lib/Http/Input/RequestInputFactory.php
+++ b/lib/Http/Input/RequestInputFactory.php
@@ -17,6 +17,7 @@ final class RequestInputFactory
         $query = $_GET;
         $files = $_FILES;
 
+        // API requests carry a JSON body; web requests use $_POST form data.
         if (defined('MINTY_API_REQUEST')) {
             return new RequestInput($method, $query, $this->readApiBody(), $files);
         }
diff --git a/lib/Http/Request.php b/lib/Http/Request.php
index c51f737..a5a029e 100644
--- a/lib/Http/Request.php
+++ b/lib/Http/Request.php
@@ -30,6 +30,8 @@ class Request
         return self::stripBasePath($path);
     }
 
+    // Returns a safe redirect target after login — guards against open-redirect attacks
+    // by rejecting any value with a scheme or host (i.e. an absolute external URL).
     public static function safeReturnTarget(string $returnParam = ''): string
     {
         if ($returnParam !== '') {
diff --git a/lib/Http/RequestContext.php b/lib/Http/RequestContext.php
index 3629a07..ee0eaf3 100644
--- a/lib/Http/RequestContext.php
+++ b/lib/Http/RequestContext.php
@@ -4,6 +4,8 @@ namespace MintyPHP\Http;
 
 use MintyPHP\Repository\Support\RepoQuery;
 
+// Holds per-request metadata (id, channel, method, path, ip) as a static singleton.
+// Must be initialized once at the entry point (web, api, cli) via start().
 final class RequestContext
 {
     /** @var array<string, mixed>|null */
@@ -27,6 +29,7 @@ final class RequestContext
         self::$context = self::buildDefaultContext();
     }
 
+    // Returns the request ID, generating one if missing. Use this when you need a guaranteed value.
     public static function id(): string
     {
         self::ensureStarted();
@@ -38,6 +41,7 @@ final class RequestContext
         return $requestId;
     }
 
+    // Returns the ID only if already set — safe to call before start() (e.g. in error handlers).
     public static function currentId(): ?string
     {
         if (self::$context === null) {
@@ -80,6 +84,7 @@ final class RequestContext
         return self::id();
     }
 
+    // HMAC when a key is configured (e.g. hashing IPs for audit logs) — plain SHA256 as fallback.
     public static function hashValue(string $value): string
     {
         $secret = defined('APP_CRYPTO_KEY') ? trim((string) APP_CRYPTO_KEY) : '';
@@ -191,6 +196,8 @@ final class RequestContext
         return in_array($channel, ['web', 'api', 'scheduler', 'cli'], true) ? $channel : '';
     }
 
+    // Accept a caller-supplied request ID for cross-service trace correlation.
+    // Only trusted if it's a valid UUID format — arbitrary strings are ignored.
     private static function requestIdFromHeader(): ?string
     {
         $header = trim((string) ($_SERVER['HTTP_X_REQUEST_ID'] ?? ''));
diff --git a/lib/Http/RequestRuntime.php b/lib/Http/RequestRuntime.php
new file mode 100644
index 0000000..5b56ec0
--- /dev/null
+++ b/lib/Http/RequestRuntime.php
@@ -0,0 +1,66 @@
+<?php
+
+namespace MintyPHP\Http;
+
+class RequestRuntime implements RequestRuntimeInterface
+{
+    public function method(): string
+    {
+        $method = strtoupper(trim((string) ($this->context()['method'] ?? '')));
+        if ($method === '') {
+            return 'GET';
+        }
+
+        return substr($method, 0, 8);
+    }
+
+    public function path(): string
+    {
+        return trim((string) ($this->context()['path'] ?? ''));
+    }
+
+    public function ip(): string
+    {
+        return trim((string) ($this->context()['ip'] ?? ''));
+    }
+
+    public function userAgent(): string
+    {
+        return trim((string) ($this->context()['user_agent'] ?? ''));
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function queryParams(): array
+    {
+        /** @var array<string, mixed> $query */
+        $query = $_GET;
+        return $query;
+    }
+
+    public function isSecure(): bool
+    {
+        $https = strtolower(trim((string) ($_SERVER['HTTPS'] ?? '')));
+        if (in_array($https, ['on', '1', 'true'], true)) {
+            return true;
+        }
+
+        $forwarded = strtolower(trim((string) ($_SERVER['HTTP_X_FORWARDED_PROTO'] ?? '')));
+        if ($forwarded === '') {
+            return false;
+        }
+
+        $parts = explode(',', $forwarded);
+        return trim((string) ($parts[0] ?? '')) === 'https';
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function context(): array
+    {
+        RequestContext::ensureStarted();
+        return RequestContext::context();
+    }
+}
diff --git a/lib/Http/RequestRuntimeInterface.php b/lib/Http/RequestRuntimeInterface.php
new file mode 100644
index 0000000..493af5d
--- /dev/null
+++ b/lib/Http/RequestRuntimeInterface.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace MintyPHP\Http;
+
+interface RequestRuntimeInterface
+{
+    public function method(): string;
+
+    public function path(): string;
+
+    public function ip(): string;
+
+    public function userAgent(): string;
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function queryParams(): array;
+
+    public function isSecure(): bool;
+}
diff --git a/lib/Http/SessionStore.php b/lib/Http/SessionStore.php
new file mode 100644
index 0000000..e06ae51
--- /dev/null
+++ b/lib/Http/SessionStore.php
@@ -0,0 +1,50 @@
+<?php
+
+namespace MintyPHP\Http;
+
+class SessionStore implements SessionStoreInterface
+{
+    public function get(string $key, mixed $default = null): mixed
+    {
+        $session = $this->all();
+        if (!array_key_exists($key, $session)) {
+            return $default;
+        }
+
+        return $session[$key];
+    }
+
+    public function set(string $key, mixed $value): void
+    {
+        if (!is_array($_SESSION ?? null)) {
+            $_SESSION = [];
+        }
+
+        $_SESSION[$key] = $value;
+    }
+
+    public function has(string $key): bool
+    {
+        $session = $this->all();
+        return array_key_exists($key, $session);
+    }
+
+    public function remove(string $key): void
+    {
+        if (!is_array($_SESSION ?? null)) {
+            $_SESSION = [];
+        }
+
+        unset($_SESSION[$key]);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function all(): array
+    {
+        /** @var array<string, mixed> $session */
+        $session = $_SESSION;
+        return $session;
+    }
+}
diff --git a/lib/Http/SessionStoreInterface.php b/lib/Http/SessionStoreInterface.php
new file mode 100644
index 0000000..bb295a2
--- /dev/null
+++ b/lib/Http/SessionStoreInterface.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace MintyPHP\Http;
+
+interface SessionStoreInterface
+{
+    public function get(string $key, mixed $default = null): mixed;
+
+    public function set(string $key, mixed $value): void;
+
+    public function has(string $key): bool;
+
+    public function remove(string $key): void;
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function all(): array;
+}
diff --git a/lib/Service/Access/AccessGatewayFactory.php b/lib/Service/Access/AccessGatewayFactory.php
index e244832..865f2ec 100644
--- a/lib/Service/Access/AccessGatewayFactory.php
+++ b/lib/Service/Access/AccessGatewayFactory.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Service\Access;
 
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Service\Audit\AuditServicesFactory;
 
 class AccessGatewayFactory
@@ -11,7 +12,8 @@ class AccessGatewayFactory
 
     public function __construct(
         private readonly AccessRepositoryFactory $accessRepositoryFactory,
-        private readonly AuditServicesFactory $auditServicesFactory
+        private readonly AuditServicesFactory $auditServicesFactory,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -21,7 +23,8 @@ class AccessGatewayFactory
             $this->accessRepositoryFactory->createPermissionRepository(),
             $this->accessRepositoryFactory->createRolePermissionRepository(),
             $this->accessRepositoryFactory->createUserRoleRepository(),
-            $this->auditServicesFactory->createSystemAuditService()
+            $this->auditServicesFactory->createSystemAuditService(),
+            $this->sessionStore
         );
     }
 
diff --git a/lib/Service/Access/AccessPolicyFactory.php b/lib/Service/Access/AccessPolicyFactory.php
index 9d484fc..1a9ba41 100644
--- a/lib/Service/Access/AccessPolicyFactory.php
+++ b/lib/Service/Access/AccessPolicyFactory.php
@@ -65,6 +65,8 @@ class AccessPolicyFactory
         );
     }
 
+    // Assembles all policies into a single AuthorizationService.
+    // Policy order doesn't matter — each ability maps to exactly one policy via supports().
     public function createAuthorizationService(): AuthorizationService
     {
         return $this->authorizationService ??= new AuthorizationService([
diff --git a/lib/Service/Access/AuthorizationDecision.php b/lib/Service/Access/AuthorizationDecision.php
index 8b55e98..c178363 100644
--- a/lib/Service/Access/AuthorizationDecision.php
+++ b/lib/Service/Access/AuthorizationDecision.php
@@ -2,6 +2,9 @@
 
 namespace MintyPHP\Service\Access;
 
+// Immutable value object returned by every authorization policy.
+// The $attributes bag lets policies carry extra computed data to the caller
+// (e.g. the capabilities map built during the user-edit context check).
 class AuthorizationDecision
 {
     public function __construct(
diff --git a/lib/Service/Access/AuthorizationService.php b/lib/Service/Access/AuthorizationService.php
index 74978bc..e170f21 100644
--- a/lib/Service/Access/AuthorizationService.php
+++ b/lib/Service/Access/AuthorizationService.php
@@ -23,6 +23,7 @@ class AuthorizationService
 
     public function authorize(string $ability, array $context = []): AuthorizationDecision
     {
+        // First matching policy wins. No match → 500 (misconfiguration, not a user error).
         foreach ($this->policies as $policy) {
             if (!$policy->supports($ability)) {
                 continue;
diff --git a/lib/Service/Access/PermissionService.php b/lib/Service/Access/PermissionService.php
index a1cbc4b..a330298 100644
--- a/lib/Service/Access/PermissionService.php
+++ b/lib/Service/Access/PermissionService.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Service\Access;
 
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Access\PermissionRepositoryInterface;
 use MintyPHP\Repository\Access\RolePermissionRepositoryInterface;
 use MintyPHP\Repository\Access\UserRoleRepositoryInterface;
@@ -15,7 +16,8 @@ class PermissionService
         private readonly PermissionRepositoryInterface $permissionRepository,
         private readonly RolePermissionRepositoryInterface $rolePermissionRepository,
         private readonly UserRoleRepositoryInterface $userRoleRepository,
-        private readonly SystemAuditService $systemAuditService
+        private readonly SystemAuditService $systemAuditService,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -86,6 +88,8 @@ class PermissionService
             return [];
         }
 
+        // Two-tier cache: API requests (stateless) use an in-memory array per-request;
+        // web requests use the session store so permissions survive across the page lifecycle.
         if ($this->isApiRequest()) {
             if (!$refresh && isset($this->apiPermissionCache[$userId])) {
                 return $this->apiPermissionCache[$userId];
@@ -97,7 +101,7 @@ class PermissionService
             return $keys;
         }
 
-        $cache = $_SESSION['permissions'] ?? null;
+        $cache = $this->sessionStore->get('permissions');
         if ($refresh) {
             $cache = null;
         }
@@ -109,10 +113,10 @@ class PermissionService
         }
         $roleIds = $this->userRoleRepository->listRoleIdsByUserId($userId);
         $keys = $this->rolePermissionRepository->listPermissionKeysByRoleIds($roleIds);
-        $_SESSION['permissions'] = [
+        $this->sessionStore->set('permissions', [
             'user_id' => $userId,
             'keys' => $keys,
-        ];
+        ]);
         return $keys;
     }
 
@@ -126,7 +130,7 @@ class PermissionService
             return $this->apiPermissionCache[$userId] ?? [];
         }
 
-        $cache = $_SESSION['permissions'] ?? null;
+        $cache = $this->sessionStore->get('permissions');
         if (is_array($cache) && (int) ($cache['user_id'] ?? 0) === $userId) {
             $keys = $cache['keys'] ?? [];
             return is_array($keys) ? $keys : [];
@@ -141,12 +145,13 @@ class PermissionService
             return;
         }
 
-        $cache = $_SESSION['permissions'] ?? null;
+        $cache = $this->sessionStore->get('permissions');
         if (is_array($cache) && (int) ($cache['user_id'] ?? 0) === $userId) {
-            unset($_SESSION['permissions']);
+            $this->sessionStore->remove('permissions');
         }
     }
 
+    // MINTY_API_REQUEST is defined in the API entry point to distinguish context at runtime.
     private function isApiRequest(): bool
     {
         return defined('MINTY_API_REQUEST');
diff --git a/lib/Service/Access/UiAccessService.php b/lib/Service/Access/UiAccessService.php
index 756fd2f..479f881 100644
--- a/lib/Service/Access/UiAccessService.php
+++ b/lib/Service/Access/UiAccessService.php
@@ -19,6 +19,7 @@ final class UiAccessService
             return false;
         }
 
+        // Cache key hashes a sorted context so order-independent inputs produce the same key.
         $normalizedContext = $this->normalizeContext($context);
         $cacheKey = $actorUserId . '|' . $ability . '|' . sha1(json_encode($normalizedContext, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) ?: '');
         if (array_key_exists($cacheKey, $this->decisionCache)) {
diff --git a/lib/Service/Access/UserAuthorizationPolicy.php b/lib/Service/Access/UserAuthorizationPolicy.php
index 521f837..6977f92 100644
--- a/lib/Service/Access/UserAuthorizationPolicy.php
+++ b/lib/Service/Access/UserAuthorizationPolicy.php
@@ -99,6 +99,7 @@ class UserAuthorizationPolicy implements AuthorizationPolicyInterface
         return $this->authorizeAdminUserWithPermission(PermissionService::USERS_CREATE, $context, false);
     }
 
+    // Returns the full capabilities map as attributes — the submit handler re-uses it to avoid recalculating.
     private function authorizeAdminUsersEditContext(array $context): AuthorizationDecision
     {
         return $this->buildEditContextDecision($context);
@@ -309,6 +310,7 @@ class UserAuthorizationPolicy implements AuthorizationPolicyInterface
             return AuthorizationDecision::allow();
         }
 
+        // 404 instead of 403 — don't reveal that the resource exists outside the actor's scope.
         if (!$this->scopeGateway->canAccess('users', $targetUserId, $actorUserId)) {
             return AuthorizationDecision::deny(404, 'not_found');
         }
diff --git a/lib/Service/AddressBook/AddressBookService.php b/lib/Service/AddressBook/AddressBookService.php
index 737af87..2a98120 100644
--- a/lib/Service/AddressBook/AddressBookService.php
+++ b/lib/Service/AddressBook/AddressBookService.php
@@ -222,6 +222,7 @@ class AddressBookService
             return ['status' => 'not_found'];
         }
 
+        // Users can always view their own profile; others require scope access.
         if (
             $currentUserId !== $targetUserId
             && !$this->directoryGateway->canAccessUser($currentUserId, $targetUserId)
@@ -239,6 +240,7 @@ class AddressBookService
             }
             $tenantId = (int) ($department['tenant_id'] ?? 0);
             $label = trim((string) ($department['description'] ?? ''));
+            // Only show departments in tenants the viewer also belongs to — prevents leaking org structure.
             if ($tenantId <= 0 || $label === '' || !in_array($tenantId, $viewerTenantIds, true)) {
                 continue;
             }
@@ -327,6 +329,7 @@ class AddressBookService
         return array_values(array_filter($ids, static fn (int $id): bool => $id > 0));
     }
 
+    // Accepts either a '||'-delimited DB aggregate string (from GROUP_CONCAT) or a plain array.
     private function normalizeLabelList($value): array
     {
         if (is_string($value)) {
diff --git a/lib/Service/Audit/ApiAuditService.php b/lib/Service/Audit/ApiAuditService.php
index dd679e4..8aa6b58 100644
--- a/lib/Service/Audit/ApiAuditService.php
+++ b/lib/Service/Audit/ApiAuditService.php
@@ -3,6 +3,7 @@
 namespace MintyPHP\Service\Audit;
 
 use MintyPHP\Http\ApiAuth;
+use MintyPHP\Http\RequestRuntimeInterface;
 use MintyPHP\Http\RequestContext;
 use MintyPHP\Repository\Audit\ApiAuditLogRepositoryInterface;
 
@@ -15,8 +16,10 @@ class ApiAuditService
 
     private ?array $context = null;
 
-    public function __construct(private readonly ApiAuditLogRepositoryInterface $apiAuditLogRepository)
-    {
+    public function __construct(
+        private readonly ApiAuditLogRepositoryInterface $apiAuditLogRepository,
+        private readonly RequestRuntimeInterface $requestRuntime
+    ) {
     }
 
     public function startRequestContext(): void
@@ -29,14 +32,13 @@ class ApiAuditService
         RequestContext::setChannel('api');
         $requestContext = RequestContext::context();
 
-        $method = strtoupper(trim((string) ($_SERVER['REQUEST_METHOD'] ?? 'GET')));
+        $method = strtoupper(trim($this->requestRuntime->method()));
         if ($method === 'OPTIONS') {
             $this->context = ['active' => false, 'finished' => true];
             return;
         }
 
-        $path = parse_url((string) ($_SERVER['REQUEST_URI'] ?? ''), PHP_URL_PATH);
-        $path = is_string($path) ? trim($path) : '';
+        $path = trim($this->requestRuntime->path());
         if ($path === '') {
             $this->context = ['active' => false, 'finished' => true];
             return;
@@ -49,7 +51,7 @@ class ApiAuditService
             'request_id' => (string) ($requestContext['request_id'] ?? RequestContext::id()),
             'method' => (string) ($requestContext['method'] ?? substr($method !== '' ? $method : 'GET', 0, 8)),
             'path' => (string) ($requestContext['path'] ?? substr($path, 0, 255)),
-            'query_json' => $this->buildRedactedQueryJson($_GET),
+            'query_json' => $this->buildRedactedQueryJson($this->requestRuntime->queryParams()),
         ];
     }
 
@@ -95,14 +97,14 @@ class ApiAuditService
 
         $requestContext = RequestContext::context();
 
-        $ip = trim((string) ($requestContext['ip'] ?? ($_SERVER['REMOTE_ADDR'] ?? '')));
+        $ip = trim((string) ($requestContext['ip'] ?? $this->requestRuntime->ip()));
         if ($ip === '') {
             $ip = null;
         } elseif (strlen($ip) > 45) {
             $ip = substr($ip, 0, 45);
         }
 
-        $userAgent = trim((string) ($requestContext['user_agent'] ?? ($_SERVER['HTTP_USER_AGENT'] ?? '')));
+        $userAgent = trim((string) ($requestContext['user_agent'] ?? $this->requestRuntime->userAgent()));
         if ($userAgent === '') {
             $userAgent = null;
         } elseif (strlen($userAgent) > self::MAX_USER_AGENT_LENGTH) {
diff --git a/lib/Service/Audit/AuditServicesFactory.php b/lib/Service/Audit/AuditServicesFactory.php
index 108db5c..3bbd018 100644
--- a/lib/Service/Audit/AuditServicesFactory.php
+++ b/lib/Service/Audit/AuditServicesFactory.php
@@ -2,10 +2,12 @@
 
 namespace MintyPHP\Service\Audit;
 
+use MintyPHP\Http\RequestRuntimeInterface;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Audit\ApiAuditLogRepositoryInterface;
 use MintyPHP\Repository\Audit\SystemAuditLogRepositoryInterface;
 use MintyPHP\Repository\Audit\UserLifecycleAuditRepositoryInterface;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsSystemAuditGateway;
 
 class AuditServicesFactory
 {
@@ -16,7 +18,9 @@ class AuditServicesFactory
 
     public function __construct(
         private readonly AuditRepositoryFactory $auditRepositoryFactory,
-        private readonly SettingGateway $settingGateway
+        private readonly SettingsSystemAuditGateway $settingsSystemAuditGateway,
+        private readonly RequestRuntimeInterface $requestRuntime,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -37,7 +41,10 @@ class AuditServicesFactory
 
     public function createApiAuditService(): ApiAuditService
     {
-        return $this->apiAuditService ??= new ApiAuditService($this->createApiAuditLogRepository());
+        return $this->apiAuditService ??= new ApiAuditService(
+            $this->createApiAuditLogRepository(),
+            $this->requestRuntime
+        );
     }
 
     public function createUserLifecycleAuditService(): UserLifecycleAuditService
@@ -57,7 +64,8 @@ class AuditServicesFactory
         return $this->systemAuditService ??= new SystemAuditService(
             $this->createSystemAuditLogRepository(),
             $this->createSystemAuditRedactionService(),
-            $this->settingGateway
+            $this->settingsSystemAuditGateway,
+            $this->sessionStore
         );
     }
 }
diff --git a/lib/Service/Audit/FrontendTelemetryIngestService.php b/lib/Service/Audit/FrontendTelemetryIngestService.php
new file mode 100644
index 0000000..67c34bd
--- /dev/null
+++ b/lib/Service/Audit/FrontendTelemetryIngestService.php
@@ -0,0 +1,515 @@
+<?php
+
+namespace MintyPHP\Service\Audit;
+
+use DateTimeImmutable;
+use DateTimeZone;
+use MintyPHP\Domain\Taxonomy\SystemAuditOutcome;
+use MintyPHP\Http\RequestContext;
+use MintyPHP\Http\SessionStoreInterface;
+use MintyPHP\Service\Security\RateLimiterService;
+use MintyPHP\Service\Settings\SettingsFrontendTelemetryGateway;
+
+class FrontendTelemetryIngestService
+{
+    private const INGEST_RATE_SCOPE = 'frontend.telemetry.ingest';
+    private const SESSION_STATE_KEY = 'frontend_telemetry_state';
+
+    private const INGEST_MAX_HITS = 80;
+    private const INGEST_WINDOW_SECONDS = 300;
+    private const INGEST_BLOCK_SECONDS = 120;
+    private const FAST_DROP_MAX_HITS = 30;
+    private const FAST_DROP_WINDOW_SECONDS = 60;
+
+    private const DEDUPE_WINDOW_SECONDS = 300;
+
+    private const MESSAGE_MAX_LENGTH = 280;
+    private const FINGERPRINT_MAX_LENGTH = 96;
+    private const META_MAX_ENTRIES = 12;
+    private const META_VALUE_MAX_LENGTH = 140;
+
+    private const EVENT_WARN_ONCE = 'frontend.warn_once';
+    private const EVENT_AJAX_ERROR = 'frontend.ajax_error';
+
+    /** @var array<string, string> */
+    private const EVENT_KEY_MAP = [
+        self::EVENT_WARN_ONCE => 'warn_once',
+        self::EVENT_AJAX_ERROR => 'ajax_error',
+    ];
+
+    /** @var array<int, string> */
+    private const ALLOWED_META_KEYS = [
+        'action',
+        'code',
+        'component',
+        'error_code',
+        'feature',
+        'http_method',
+        'http_status',
+        'location',
+        'module',
+        'page_request_id',
+        'request_path',
+        'source',
+        'status_text',
+    ];
+
+    public function __construct(
+        private readonly SystemAuditService $systemAuditService,
+        private readonly SettingsFrontendTelemetryGateway $settingsFrontendTelemetryGateway,
+        private readonly RateLimiterService $rateLimiterService,
+        private readonly SessionStoreInterface $sessionStore
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $input
+     * @return array{accepted:bool, reason:string}
+     */
+    public function ingest(array $input): array
+    {
+        if (!$this->settingsFrontendTelemetryGateway->isFrontendTelemetryEnabled()) {
+            return ['accepted' => false, 'reason' => 'disabled'];
+        }
+
+        $payload = $this->normalizePayload($input);
+        if ($payload === null) {
+            return ['accepted' => false, 'reason' => 'invalid'];
+        }
+
+        if (!$this->isAllowedEvent($payload['event_type'])) {
+            return ['accepted' => false, 'reason' => 'event_not_allowed'];
+        }
+
+        if (!$this->shouldSample($this->settingsFrontendTelemetryGateway->getFrontendTelemetrySampleRate())) {
+            return ['accepted' => false, 'reason' => 'sampled_out'];
+        }
+
+        $now = time();
+        $sessionState = $this->loadSessionState();
+        if ($this->applyBurstLimit($sessionState, $now)) {
+            $this->saveSessionState($sessionState);
+            return ['accepted' => false, 'reason' => 'burst_limited'];
+        }
+
+        $subject = $this->subjectKey();
+
+        $rateDecision = $this->rateLimiterService->hit(
+            self::INGEST_RATE_SCOPE,
+            $subject,
+            self::INGEST_MAX_HITS,
+            self::INGEST_WINDOW_SECONDS,
+            self::INGEST_BLOCK_SECONDS
+        );
+        if (!(bool) ($rateDecision['allowed'] ?? true)) {
+            $this->saveSessionState($sessionState);
+            return ['accepted' => false, 'reason' => 'rate_limited'];
+        }
+
+        if ($this->isDuplicateAndTouch($sessionState, $payload['fingerprint_hash'], $now)) {
+            $this->saveSessionState($sessionState);
+            return ['accepted' => false, 'reason' => 'duplicate'];
+        }
+
+        $this->saveSessionState($sessionState);
+
+        $outcome = $payload['severity'] === 'error'
+            ? SystemAuditOutcome::Failed->value
+            : SystemAuditOutcome::Success->value;
+
+        $recordId = $this->systemAuditService->record($payload['event_type'], $outcome, [
+            'target_type' => 'frontend',
+            'metadata' => [
+                'severity' => $payload['severity'],
+                'message' => $payload['message'],
+                'fingerprint_hash' => $payload['fingerprint_hash'],
+                'occurred_at' => $payload['occurred_at'],
+                'meta' => $payload['meta'],
+            ],
+        ]);
+
+        if ($recordId === null) {
+            return ['accepted' => false, 'reason' => 'record_failed'];
+        }
+
+        return ['accepted' => true, 'reason' => 'logged'];
+    }
+
+    /**
+     * @param array<string, mixed> $input
+     * @return array{
+     *   event_type:string,
+     *   severity:string,
+     *   message:string,
+     *   fingerprint_hash:string,
+     *   occurred_at:string,
+     *   meta: array<string, mixed>
+     * }|null
+     */
+    private function normalizePayload(array $input): ?array
+    {
+        $eventType = $this->normalizeEventType((string) ($input['event_type'] ?? ''));
+        if ($eventType === '') {
+            return null;
+        }
+
+        $message = $this->sanitizeText((string) ($input['message'] ?? ''), self::MESSAGE_MAX_LENGTH);
+        if ($message === '') {
+            return null;
+        }
+
+        $meta = $this->normalizeMeta($input['meta'] ?? []);
+        $route = trim((string) ($meta['location'] ?? ''));
+
+        $fingerprint = $this->sanitizeFingerprint((string) ($input['fingerprint'] ?? ''));
+        if ($fingerprint === '') {
+            $fingerprint = $this->sanitizeFingerprint(
+                'v1_' . substr(hash('sha256', $eventType . '|' . $route . '|' . $message), 0, 24)
+            );
+        }
+        if ($fingerprint === '') {
+            return null;
+        }
+
+        return [
+            'event_type' => $eventType,
+            'severity' => $this->normalizeSeverity((string) ($input['severity'] ?? ''), $eventType),
+            'message' => $message,
+            'fingerprint_hash' => RequestContext::hashValue($fingerprint),
+            'occurred_at' => $this->normalizeOccurredAt((string) ($input['occurred_at'] ?? '')),
+            'meta' => $meta,
+        ];
+    }
+
+    private function normalizeEventType(string $eventType): string
+    {
+        $eventType = strtolower(trim($eventType));
+        if ($eventType === '') {
+            return '';
+        }
+
+        if (str_starts_with($eventType, 'frontend.')) {
+            return isset(self::EVENT_KEY_MAP[$eventType]) ? $eventType : '';
+        }
+
+        foreach (self::EVENT_KEY_MAP as $name => $short) {
+            if ($eventType === $short) {
+                return $name;
+            }
+        }
+
+        return '';
+    }
+
+    private function normalizeSeverity(string $severity, string $eventType): string
+    {
+        $severity = strtolower(trim($severity));
+        if (in_array($severity, ['info', 'warning', 'error'], true)) {
+            return $severity;
+        }
+
+        return $eventType === self::EVENT_AJAX_ERROR ? 'error' : 'warning';
+    }
+
+    private function normalizeOccurredAt(string $occurredAt): string
+    {
+        $occurredAt = trim($occurredAt);
+        if ($occurredAt !== '') {
+            try {
+                $date = new DateTimeImmutable($occurredAt);
+                return $date->setTimezone(new DateTimeZone('UTC'))->format('Y-m-d\TH:i:s\Z');
+            } catch (\Throwable) {
+                // Fall back to now below.
+            }
+        }
+
+        return (new DateTimeImmutable('now', new DateTimeZone('UTC')))->format('Y-m-d\TH:i:s\Z');
+    }
+
+    private function sanitizeFingerprint(string $value): string
+    {
+        $value = strtolower(trim($value));
+        if ($value === '') {
+            return '';
+        }
+
+        $value = preg_replace('/[^a-z0-9:_-]/', '', $value) ?? '';
+        if ($value === '') {
+            return '';
+        }
+
+        return substr($value, 0, self::FINGERPRINT_MAX_LENGTH);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private function normalizeMeta(mixed $rawMeta): array
+    {
+        $source = [];
+        if (is_array($rawMeta)) {
+            $source = $rawMeta;
+        } elseif (is_string($rawMeta) && trim($rawMeta) !== '') {
+            $decoded = json_decode($rawMeta, true);
+            if (is_array($decoded)) {
+                $source = $decoded;
+            }
+        }
+
+        if ($source === []) {
+            return [];
+        }
+
+        $meta = [];
+        $count = 0;
+        foreach ($source as $rawKey => $rawValue) {
+            if ($count >= self::META_MAX_ENTRIES) {
+                break;
+            }
+
+            $key = strtolower(trim((string) $rawKey));
+            if ($key === '' || !in_array($key, self::ALLOWED_META_KEYS, true)) {
+                continue;
+            }
+
+            if ($key === 'location' || $key === 'request_path') {
+                $normalizedPath = $this->sanitizePath((string) $rawValue);
+                if ($normalizedPath === '') {
+                    continue;
+                }
+                $meta[$key] = $normalizedPath;
+                $count++;
+                continue;
+            }
+
+            if ($key === 'http_status') {
+                $status = (int) $rawValue;
+                if ($status < 100 || $status > 599) {
+                    continue;
+                }
+                $meta[$key] = $status;
+                $count++;
+                continue;
+            }
+
+            if ($key === 'page_request_id') {
+                $requestId = strtolower(trim((string) $rawValue));
+                if (preg_match('/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/', $requestId) !== 1) {
+                    continue;
+                }
+                $meta[$key] = $requestId;
+                $count++;
+                continue;
+            }
+
+            $value = $this->sanitizeText((string) $rawValue, self::META_VALUE_MAX_LENGTH);
+            if ($value === '') {
+                continue;
+            }
+
+            $meta[$key] = $value;
+            $count++;
+        }
+
+        return $meta;
+    }
+
+    private function sanitizePath(string $value): string
+    {
+        $value = trim($value);
+        if ($value === '') {
+            return '';
+        }
+
+        if (filter_var($value, FILTER_VALIDATE_URL)) {
+            $parsedPath = parse_url($value, PHP_URL_PATH);
+            $value = is_string($parsedPath) ? $parsedPath : '';
+        }
+
+        $value = (string) preg_replace('/[?#].*/', '', $value);
+        $value = preg_replace('/\/[0-9]{3,}(?=\/|$)/', '/:id', $value) ?? $value;
+        $value = preg_replace(
+            '/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/i',
+            ':uuid',
+            $value
+        ) ?? $value;
+
+        $value = trim($value);
+        if ($value === '') {
+            return '';
+        }
+        if (!str_starts_with($value, '/')) {
+            $value = '/' . $value;
+        }
+
+        return substr($value, 0, 255);
+    }
+
+    private function sanitizeText(string $value, int $maxLength): string
+    {
+        $value = trim($value);
+        if ($value === '') {
+            return '';
+        }
+
+        $value = preg_replace('/\s+/', ' ', $value) ?? $value;
+        $value = preg_replace('/([?&][a-z0-9_.-]{1,64}=)[^&#\s]+/i', '$1[REDACTED]', $value) ?? $value;
+        $value = preg_replace('/(^|\s)(token|access_token|refresh_token|id_token|authorization|api_key|secret)=([^\s]+)/i', '$1$2=[REDACTED]', $value) ?? $value;
+        $value = preg_replace('/[A-Z0-9._%+\-]+@[A-Z0-9.\-]+\.[A-Z]{2,}/i', '[REDACTED_EMAIL]', $value) ?? $value;
+        $value = preg_replace(
+            '/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/i',
+            '[UUID]',
+            $value
+        ) ?? $value;
+        $value = preg_replace('/\b[a-f0-9]{24,}\b/i', '[TOKEN]', $value) ?? $value;
+
+        return substr($value, 0, max(1, $maxLength));
+    }
+
+    private function isAllowedEvent(string $eventType): bool
+    {
+        $eventKey = self::EVENT_KEY_MAP[$eventType] ?? null;
+        if ($eventKey === null) {
+            return false;
+        }
+
+        $allowed = $this->settingsFrontendTelemetryGateway->getFrontendTelemetryAllowedEvents();
+        return in_array($eventKey, $allowed, true);
+    }
+
+    private function shouldSample(float $sampleRate): bool
+    {
+        if ($sampleRate <= 0.0) {
+            return false;
+        }
+        if ($sampleRate >= 1.0) {
+            return true;
+        }
+
+        try {
+            $max = 10000;
+            $threshold = (int) floor($sampleRate * $max);
+            return random_int(1, $max) <= max(1, $threshold);
+        } catch (\Throwable) {
+            $threshold = (int) floor($sampleRate * 10000);
+            return mt_rand(1, 10000) <= max(1, $threshold);
+        }
+    }
+
+    private function subjectKey(): string
+    {
+        $session = $this->sessionStore->all();
+        $userId = (int) ($session['user']['id'] ?? 0);
+        if ($userId > 0) {
+            return 'user:' . $userId;
+        }
+
+        $sessionId = trim(session_id());
+        if ($sessionId !== '') {
+            return 'session:' . $sessionId;
+        }
+
+        $requestContext = RequestContext::context();
+        $ip = trim((string) ($requestContext['ip'] ?? ''));
+        if ($ip !== '') {
+            return 'ip:' . RequestContext::hashValue($ip);
+        }
+
+        return 'anonymous';
+    }
+
+    /**
+     * @return array{dedupe: array<string,int>, burst: array{window_start:int,count:int}}
+     */
+    private function loadSessionState(): array
+    {
+        $rawState = $this->sessionStore->get(self::SESSION_STATE_KEY, []);
+        if (!is_array($rawState)) {
+            $rawState = [];
+        }
+
+        $dedupe = is_array($rawState['dedupe'] ?? null) ? $rawState['dedupe'] : [];
+        $burst = is_array($rawState['burst'] ?? null) ? $rawState['burst'] : [];
+
+        return [
+            'dedupe' => $dedupe,
+            'burst' => [
+                'window_start' => is_int($burst['window_start'] ?? null) ? (int) $burst['window_start'] : 0,
+                'count' => is_int($burst['count'] ?? null) ? max(0, (int) $burst['count']) : 0,
+            ],
+        ];
+    }
+
+    /**
+     * @param array{dedupe: array<string,int>, burst: array{window_start:int,count:int}} $state
+     */
+    private function saveSessionState(array $state): void
+    {
+        $this->sessionStore->set(self::SESSION_STATE_KEY, $state);
+    }
+
+    /**
+     * @param array{dedupe: array<string,int>, burst: array{window_start:int,count:int}} $state
+     */
+    private function applyBurstLimit(array &$state, int $now): bool
+    {
+        $windowStart = (int) ($state['burst']['window_start'] ?? 0);
+        $count = max(0, (int) ($state['burst']['count'] ?? 0));
+
+        if ($windowStart <= 0 || ($now - $windowStart) >= self::FAST_DROP_WINDOW_SECONDS) {
+            $windowStart = $now;
+            $count = 0;
+        }
+
+        if ($count >= self::FAST_DROP_MAX_HITS) {
+            $state['burst'] = [
+                'window_start' => $windowStart,
+                'count' => $count,
+            ];
+            return true;
+        }
+
+        $state['burst'] = [
+            'window_start' => $windowStart,
+            'count' => $count + 1,
+        ];
+        return false;
+    }
+
+    /**
+     * @param array{dedupe: array<string,int>, burst: array{window_start:int,count:int}} $state
+     */
+    private function isDuplicateAndTouch(array &$state, string $fingerprintHash, int $now): bool
+    {
+        $seen = $state['dedupe'] ?? [];
+        if (!is_array($seen)) {
+            $seen = [];
+        }
+
+        $cutoff = $now - self::DEDUPE_WINDOW_SECONDS;
+        foreach ($seen as $key => $timestamp) {
+            if (!is_string($key)) {
+                unset($seen[$key]);
+                continue;
+            }
+            if (!is_int($timestamp) || $timestamp < $cutoff) {
+                unset($seen[$key]);
+            }
+        }
+
+        if (isset($seen[$fingerprintHash]) && (int) $seen[$fingerprintHash] >= $cutoff) {
+            $seen[$fingerprintHash] = $now;
+            $isDuplicate = true;
+        } else {
+            $seen[$fingerprintHash] = $now;
+            $isDuplicate = false;
+        }
+
+        if (count($seen) > 120) {
+            arsort($seen, SORT_NUMERIC);
+            $seen = array_slice($seen, 0, 120, true);
+        }
+        $state['dedupe'] = $seen;
+        return $isDuplicate;
+    }
+}
diff --git a/lib/Service/Audit/SystemAuditRedactionService.php b/lib/Service/Audit/SystemAuditRedactionService.php
index 92f0ff0..da199d2 100644
--- a/lib/Service/Audit/SystemAuditRedactionService.php
+++ b/lib/Service/Audit/SystemAuditRedactionService.php
@@ -9,6 +9,7 @@ class SystemAuditRedactionService
     private const MAX_STRING_LENGTH = 500;
     private const MAX_ARRAY_ITEMS = 50;
 
+    // email/to_email are PII, not credentials, but still redacted to avoid leaking addresses in audit logs.
     /** @var array<int, string> */
     private const SENSITIVE_KEYS = [
         'password',
@@ -27,6 +28,8 @@ class SystemAuditRedactionService
         'to_email',
     ];
 
+    // Only fields on this list show actual before/after values in change sets.
+    // Everything else is recorded as '[REDACTED]' — callers must explicitly opt in to expose change values.
     /** @var array<int, string> */
     private const CHANGE_VALUE_ALLOWLIST = [
         'active',
@@ -45,6 +48,9 @@ class SystemAuditRedactionService
         'user_inactivity_delete_days',
         'system_audit_enabled',
         'system_audit_retention_days',
+        'frontend_telemetry_enabled',
+        'frontend_telemetry_sample_rate',
+        'frontend_telemetry_allowed_events',
     ];
 
     public function redactMetadata(array $metadata): array
@@ -157,6 +163,7 @@ class SystemAuditRedactionService
         return $string;
     }
 
+    // Use json_encode for arrays to get consistent comparison regardless of type coercion.
     private function valuesEqual(mixed $left, mixed $right): bool
     {
         if (is_array($left) || is_array($right)) {
@@ -177,6 +184,7 @@ class SystemAuditRedactionService
             return true;
         }
 
+        // Heuristic fallback catches new sensitive keys that weren't explicitly listed.
         return str_contains($key, 'password')
             || str_contains($key, 'secret')
             || str_contains($key, 'token')
diff --git a/lib/Service/Audit/SystemAuditService.php b/lib/Service/Audit/SystemAuditService.php
index fffa9cb..7ba8617 100644
--- a/lib/Service/Audit/SystemAuditService.php
+++ b/lib/Service/Audit/SystemAuditService.php
@@ -6,9 +6,10 @@ use MintyPHP\Domain\Taxonomy\SystemAuditChannel;
 use MintyPHP\Domain\Taxonomy\SystemAuditOutcome;
 use MintyPHP\Http\ApiAuth;
 use MintyPHP\Http\RequestContext;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Audit\SystemAuditLogRepositoryInterface;
 use MintyPHP\Repository\Support\RepoQuery;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsSystemAuditGateway;
 
 class SystemAuditService
 {
@@ -19,7 +20,8 @@ class SystemAuditService
     public function __construct(
         private readonly SystemAuditLogRepositoryInterface $systemAuditLogRepository,
         private readonly SystemAuditRedactionService $systemAuditRedactionService,
-        private readonly SettingGateway $settingGateway
+        private readonly SettingsSystemAuditGateway $settingsSystemAuditGateway,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -39,8 +41,9 @@ class SystemAuditService
 
         $outcome = $this->normalizeOutcome($outcome);
         $requestContext = RequestContext::context();
-        $session = is_array($_SESSION ?? null) ? $_SESSION : [];
+        $session = $this->sessionStore->all();
 
+        // Callers can override actor_user_id/actor_tenant_id in $context; otherwise auto-detect from session/API auth.
         $fallbackActorUserId = !empty($session['user']['id'])
             ? (int) $session['user']['id']
             : (ApiAuth::isAuthenticated() ? ApiAuth::userId() : 0);
@@ -89,6 +92,7 @@ class SystemAuditService
             'target_uuid' => $targetUuid !== '' ? substr($targetUuid, 0, 36) : null,
             'method' => $this->normalizeMethod((string) ($requestContext['method'] ?? '')),
             'path' => $this->normalizePath((string) ($requestContext['path'] ?? '')),
+            // IP and user agent are stored as hashes only — privacy by design, allows correlation without plaintext storage.
             'ip_hash' => $ip !== '' ? $this->systemAuditRedactionService->hashValue($ip) : null,
             'user_agent_hash' => $userAgent !== '' ? $this->systemAuditRedactionService->hashValue($userAgent) : null,
             'metadata_json' => $metadataJson,
@@ -125,7 +129,7 @@ class SystemAuditService
 
     public function retentionDays(): int
     {
-        $days = (int) $this->settingGateway->getSystemAuditRetentionDays();
+        $days = (int) $this->settingsSystemAuditGateway->getSystemAuditRetentionDays();
         if ($days < self::RETENTION_DAYS_MIN || $days > self::RETENTION_DAYS_MAX) {
             return self::RETENTION_DAYS_FALLBACK;
         }
@@ -134,7 +138,7 @@ class SystemAuditService
 
     public function isEnabled(): bool
     {
-        return $this->settingGateway->isSystemAuditEnabled();
+        return $this->settingsSystemAuditGateway->isSystemAuditEnabled();
     }
 
     private function normalizeEventType(string $eventType): string
diff --git a/lib/Service/Auth/ApiTokenService.php b/lib/Service/Auth/ApiTokenService.php
index 0400650..9efbec6 100644
--- a/lib/Service/Auth/ApiTokenService.php
+++ b/lib/Service/Auth/ApiTokenService.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Service\Auth;
 
+use MintyPHP\Http\RequestRuntimeInterface;
 use MintyPHP\Repository\Auth\ApiTokenRepositoryInterface;
 use MintyPHP\Repository\Support\DatabaseSessionRepository;
 use MintyPHP\Repository\User\UserReadRepositoryInterface;
@@ -15,7 +16,8 @@ class ApiTokenService
         private readonly ApiTokenRepositoryInterface $apiTokenRepository,
         private readonly AuthSettingsGateway $settingsGateway,
         private readonly AuthScopeGateway $scopeGateway,
-        private readonly DatabaseSessionRepository $databaseSessionRepository
+        private readonly DatabaseSessionRepository $databaseSessionRepository,
+        private readonly RequestRuntimeInterface $requestRuntime
     ) {
     }
 
@@ -76,6 +78,7 @@ class ApiTokenService
             return ['ok' => false, 'error' => 'invalid_expires_at'];
         }
 
+        // Selector is public (used for lookup); verifier is the secret (only its hash is stored).
         $selector = bin2hex(random_bytes(12));
         $plainToken = bin2hex(random_bytes(32));
         $tokenHash = hash('sha256', $plainToken);
@@ -140,6 +143,7 @@ class ApiTokenService
             $tenantId = null;
         }
 
+        // Wrap revoke+create in a transaction so rotation is atomic — no gap where neither token is valid.
         $transactionStarted = false;
         try {
             $this->databaseSessionRepository->beginTransaction();
@@ -260,7 +264,7 @@ class ApiTokenService
             return null;
         }
 
-        $ip = $_SERVER['REMOTE_ADDR'] ?? '';
+        $ip = $this->requestRuntime->ip();
         $this->apiTokenRepository->updateLastUsed((int) $record['id'], $ip);
 
         return [
diff --git a/lib/Service/Auth/AuthGatewayFactory.php b/lib/Service/Auth/AuthGatewayFactory.php
index 412bb4a..ff92c66 100644
--- a/lib/Service/Auth/AuthGatewayFactory.php
+++ b/lib/Service/Auth/AuthGatewayFactory.php
@@ -4,14 +4,20 @@ namespace MintyPHP\Service\Auth;
 
 use MintyPHP\Service\Access\AccessServicesFactory;
 use MintyPHP\Service\Access\PermissionGateway;
-use MintyPHP\Service\Settings\SettingGateway;
 use MintyPHP\Service\Settings\SettingServicesFactory;
+use MintyPHP\Service\Settings\SettingsApiPolicyGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsMicrosoftGateway;
 use MintyPHP\Service\Tenant\TenantScopeService;
 use MintyPHP\Service\User\UserServicesFactory;
 
 class AuthGatewayFactory
 {
-    private ?SettingGateway $settingGateway = null;
+    private ?SettingsMicrosoftGateway $settingsMicrosoftGateway = null;
+    private ?SettingsApiPolicyGateway $settingsApiPolicyGateway = null;
+    private ?SettingsDefaultsGateway $settingsDefaultsGateway = null;
+    private ?SettingsAppGateway $settingsAppGateway = null;
     private ?PermissionGateway $permissionGateway = null;
     private ?AuthSettingsGateway $authSettingsGateway = null;
     private ?AuthScopeGateway $authScopeGateway = null;
@@ -34,7 +40,12 @@ class AuthGatewayFactory
 
     public function createAuthSettingsGateway(): AuthSettingsGateway
     {
-        return $this->authSettingsGateway ??= new AuthSettingsGateway($this->createSettingGateway());
+        return $this->authSettingsGateway ??= new AuthSettingsGateway(
+            $this->createSettingsMicrosoftGateway(),
+            $this->createSettingsApiPolicyGateway(),
+            $this->createSettingsDefaultsGateway(),
+            $this->createSettingsAppGateway()
+        );
     }
 
     public function createAuthScopeGateway(): AuthScopeGateway
@@ -90,9 +101,24 @@ class AuthGatewayFactory
         return $this->permissionGateway ??= $this->accessServicesFactory->createPermissionGateway();
     }
 
-    private function createSettingGateway(): SettingGateway
+    private function createSettingsMicrosoftGateway(): SettingsMicrosoftGateway
     {
-        return $this->settingGateway ??= $this->settingServicesFactory->createSettingGateway();
+        return $this->settingsMicrosoftGateway ??= $this->settingServicesFactory->createSettingsMicrosoftGateway();
+    }
+
+    private function createSettingsApiPolicyGateway(): SettingsApiPolicyGateway
+    {
+        return $this->settingsApiPolicyGateway ??= $this->settingServicesFactory->createSettingsApiPolicyGateway();
+    }
+
+    private function createSettingsDefaultsGateway(): SettingsDefaultsGateway
+    {
+        return $this->settingsDefaultsGateway ??= $this->settingServicesFactory->createSettingsDefaultsGateway();
+    }
+
+    private function createSettingsAppGateway(): SettingsAppGateway
+    {
+        return $this->settingsAppGateway ??= $this->settingServicesFactory->createSettingsAppGateway();
     }
 
 }
diff --git a/lib/Service/Auth/AuthService.php b/lib/Service/Auth/AuthService.php
index 83b8b9c..a22ccc7 100644
--- a/lib/Service/Auth/AuthService.php
+++ b/lib/Service/Auth/AuthService.php
@@ -3,6 +3,7 @@
 namespace MintyPHP\Service\Auth;
 
 use MintyPHP\Auth;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\User\UserReadRepositoryInterface;
 use MintyPHP\Repository\User\UserWriteRepositoryInterface;
 use MintyPHP\Router;
@@ -23,8 +24,9 @@ class AuthService
         private readonly EmailVerificationService $emailVerificationService,
         private readonly AuthPermissionGateway $permissionGateway,
         private readonly AuthTenantSsoGateway $tenantSsoGateway,
-        private readonly AuthSavedFilterGateway $savedFilterGateway,
-        private readonly SystemAuditService $systemAuditService
+        private readonly AuthSessionTenantContextService $authSessionTenantContextService,
+        private readonly SystemAuditService $systemAuditService,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -62,7 +64,8 @@ class AuthService
             ];
         }
 
-        if (!($_SESSION['user']['active'] ?? 1)) {
+        $sessionUser = $this->sessionUser();
+        if (!($sessionUser['active'] ?? 1)) {
             Auth::logout();
             $this->recordAuthEvent('auth.login.failed', 'failed', [
                 'error_code' => 'account_inactive',
@@ -75,7 +78,7 @@ class AuthService
             ];
         }
 
-        $userId = (int) ($_SESSION['user']['id'] ?? 0);
+        $userId = (int) ($sessionUser['id'] ?? 0);
         if ($userId > 0 && !$this->isLocalPasswordLoginAllowedForUser($userId)) {
             Auth::logout();
             $this->recordAuthEvent('auth.login.failed', 'failed', [
@@ -91,7 +94,7 @@ class AuthService
         if ($userId > 0) {
             $this->permissionGateway->warmUserPermissions($userId, true);
             $this->loadTenantDataIntoSession($userId);
-            if (!empty($_SESSION['no_active_tenant'])) {
+            if ($this->noActiveTenant()) {
                 Auth::logout();
                 $this->recordAuthEvent('auth.login.failed', 'failed', [
                     'error_code' => 'no_active_tenant',
@@ -108,12 +111,14 @@ class AuthService
 
         $this->recordAuthEvent('auth.login.success', 'success', [
             'actor_user_id' => $userId > 0 ? $userId : null,
-            'actor_tenant_id' => (int) ($_SESSION['current_tenant']['id'] ?? 0),
+            'actor_tenant_id' => $this->currentTenantIdFromSession(),
         ]);
 
         return ['ok' => true];
     }
 
+    // Returns true if at least ONE assigned tenant permits local login.
+    // A user is only blocked if ALL tenants enforce Microsoft-only login.
     private function isLocalPasswordLoginAllowedForUser(int $userId): bool
     {
         if ($userId <= 0) {
@@ -168,18 +173,20 @@ class AuthService
         }
 
         Session::regenerate();
-        $_SESSION['user'] = $user;
+        $this->sessionStore->set('user', $user);
 
         if ($preferredTenantId !== null && $preferredTenantId > 0) {
             $setTenant = $this->userTenantContextService->setCurrentTenant($userId, $preferredTenantId);
             if ($setTenant['ok'] ?? false) {
-                $_SESSION['user']['current_tenant_id'] = $preferredTenantId;
+                $sessionUser = $this->sessionUser();
+                $sessionUser['current_tenant_id'] = $preferredTenantId;
+                $this->sessionStore->set('user', $sessionUser);
             }
         }
 
         $this->permissionGateway->warmUserPermissions($userId, true);
         $this->loadTenantDataIntoSession($userId);
-        if (!empty($_SESSION['no_active_tenant'])) {
+        if ($this->noActiveTenant()) {
             Auth::logout();
             $this->recordAuthEvent('auth.login.failed', 'failed', [
                 'error_code' => 'login_no_active_tenant',
@@ -191,7 +198,7 @@ class AuthService
         $this->userWriteRepository->updateLastLogin($userId, $loginProvider);
         $this->recordAuthEvent('auth.login.success', 'success', [
             'actor_user_id' => $userId,
-            'actor_tenant_id' => (int) ($_SESSION['current_tenant']['id'] ?? 0),
+            'actor_tenant_id' => $this->currentTenantIdFromSession(),
             'metadata' => ['provider' => $loginProvider],
         ]);
         return ['ok' => true, 'user' => $user];
@@ -209,7 +216,7 @@ class AuthService
         if (!($result['ok'] ?? false)) {
             // Check if user needs to verify email
             if (!empty($result['needs_verification'])) {
-                $_SESSION['email_verification_email'] = $result['email'] ?? $email;
+                $this->sessionStore->set('email_verification_email', $result['email'] ?? $email);
                 Flash::error(t('Please verify your email first'), 'verify-email', 'login_not_verified');
                 Router::redirect('verify-email');
             }
@@ -221,7 +228,7 @@ class AuthService
         }
 
         if ($remember) {
-            $userId = (int) ($_SESSION['user']['id'] ?? 0);
+            $userId = (int) ($this->sessionUser()['id'] ?? 0);
             if ($userId > 0) {
                 $this->rememberMeService->rememberUser($userId);
             }
@@ -250,8 +257,8 @@ class AuthService
 
     public function logout(): void
     {
-        $actorUserId = (int) ($_SESSION['user']['id'] ?? 0);
-        $actorTenantId = (int) ($_SESSION['current_tenant']['id'] ?? 0);
+        $actorUserId = (int) ($this->sessionUser()['id'] ?? 0);
+        $actorTenantId = $this->currentTenantIdFromSession();
         $this->rememberMeService->forgetCurrentUser();
         Auth::logout();
         $this->recordAuthEvent('auth.logout', 'success', [
@@ -298,7 +305,9 @@ class AuthService
             ];
         }
 
-        $sessionVersion = (int) ($_SESSION['user']['authz_version'] ?? 0);
+        // authz_version is bumped in DB whenever permissions/tenants change.
+        // A mismatch means the session is stale and needs to be refreshed.
+        $sessionVersion = (int) ($this->sessionUser()['authz_version'] ?? 0);
         $dbVersion = max(1, (int) ($snapshot['authz_version'] ?? 1));
         $refreshed = false;
 
@@ -312,13 +321,13 @@ class AuthService
                 ];
             }
 
-            $_SESSION['user'] = $user;
+            $this->sessionStore->set('user', $user);
             $this->permissionGateway->warmUserPermissions($userId, true);
             $this->loadTenantDataIntoSession($userId);
             $refreshed = true;
         }
 
-        if (!empty($_SESSION['no_active_tenant'])) {
+        if ($this->noActiveTenant()) {
             return [
                 'ok' => false,
                 'logout_required' => true,
@@ -336,31 +345,34 @@ class AuthService
 
     public function loadTenantDataIntoSession(int $userId): void
     {
-        if ($userId <= 0) {
-            return;
-        }
+        $this->authSessionTenantContextService->hydrateForUser($userId);
+    }
 
-        // Load available tenants first
-        $availableTenants = $this->userTenantContextService->getAvailableTenants($userId);
-        $_SESSION['available_tenants'] = $availableTenants;
-        $_SESSION['available_departments_by_tenant'] = $this->userTenantContextService->getAvailableDepartmentsByTenant($userId);
-        $_SESSION['address_book_saved_filters'] = $this->savedFilterGateway->listAddressBookFilters($userId);
+    /**
+     * @return array<string, mixed>
+     */
+    private function sessionUser(): array
+    {
+        $user = $this->sessionStore->get('user', []);
+        return is_array($user) ? $user : [];
+    }
 
-        if (!$availableTenants) {
-            $_SESSION['no_active_tenant'] = true;
-            unset($_SESSION['current_tenant']);
-            return;
-        }
-        $_SESSION['no_active_tenant'] = false;
+    /**
+     * @return array<string, mixed>
+     */
+    private function sessionCurrentTenant(): array
+    {
+        $tenant = $this->sessionStore->get('current_tenant', []);
+        return is_array($tenant) ? $tenant : [];
+    }
 
-        // Load current tenant (with fallback to first available)
-        $currentTenant = $this->userTenantContextService->getCurrentTenant($userId);
-        if (!$currentTenant) {
-            // Fallback: use first available tenant
-            $currentTenant = $availableTenants[0];
-        }
-        if ($currentTenant) {
-            $_SESSION['current_tenant'] = $currentTenant;
-        }
+    private function currentTenantIdFromSession(): int
+    {
+        return (int) ($this->sessionCurrentTenant()['id'] ?? 0);
+    }
+
+    private function noActiveTenant(): bool
+    {
+        return (bool) $this->sessionStore->get('no_active_tenant', false);
     }
 }
diff --git a/lib/Service/Auth/AuthServicesFactory.php b/lib/Service/Auth/AuthServicesFactory.php
index f258cec..10e2a40 100644
--- a/lib/Service/Auth/AuthServicesFactory.php
+++ b/lib/Service/Auth/AuthServicesFactory.php
@@ -2,6 +2,9 @@
 
 namespace MintyPHP\Service\Auth;
 
+use MintyPHP\Http\CookieStoreInterface;
+use MintyPHP\Http\RequestRuntimeInterface;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Support\DatabaseSessionRepository;
 use MintyPHP\Service\Audit\AuditServicesFactory;
 use MintyPHP\Service\Mail\MailServicesFactory;
@@ -18,6 +21,7 @@ class AuthServicesFactory
     private ?RememberMeService $rememberMeService = null;
     private ?AuthService $authService = null;
     private ?SsoUserLinkService $ssoUserLinkService = null;
+    private ?AuthSessionTenantContextService $authSessionTenantContextService = null;
 
     public function __construct(
         private readonly UserServicesFactory $userServicesFactory,
@@ -25,7 +29,10 @@ class AuthServicesFactory
         private readonly MailServicesFactory $mailServicesFactory,
         private readonly AuthRepositoryFactory $authRepositoryFactory,
         private readonly AuthGatewayFactory $authGatewayFactory,
-        private readonly DatabaseSessionRepository $databaseSessionRepository
+        private readonly DatabaseSessionRepository $databaseSessionRepository,
+        private readonly SessionStoreInterface $sessionStore,
+        private readonly CookieStoreInterface $cookieStore,
+        private readonly RequestRuntimeInterface $requestRuntime
     ) {
     }
 
@@ -36,7 +43,8 @@ class AuthServicesFactory
             $this->authRepositoryFactory->createApiTokenRepository(),
             $this->authGatewayFactory->createAuthSettingsGateway(),
             $this->createAuthScopeGateway(),
-            $this->databaseSessionRepository
+            $this->databaseSessionRepository,
+            $this->requestRuntime
         );
     }
 
@@ -67,9 +75,11 @@ class AuthServicesFactory
             $this->userServicesFactory->createUserReadRepository(),
             $this->userServicesFactory->createUserWriteRepository(),
             $this->authRepositoryFactory->createRememberTokenRepository(),
-            $this->userServicesFactory->createUserTenantContextService(),
             $this->authGatewayFactory->createAuthPermissionGateway(),
-            $this->authGatewayFactory->createAuthSavedFilterGateway()
+            $this->createAuthSessionTenantContextService(),
+            $this->sessionStore,
+            $this->cookieStore,
+            $this->requestRuntime
         );
     }
 
@@ -84,8 +94,9 @@ class AuthServicesFactory
             $this->createEmailVerificationService(),
             $this->authGatewayFactory->createAuthPermissionGateway(),
             $this->createAuthTenantSsoGateway(),
-            $this->authGatewayFactory->createAuthSavedFilterGateway(),
-            $this->auditServicesFactory->createSystemAuditService()
+            $this->createAuthSessionTenantContextService(),
+            $this->auditServicesFactory->createSystemAuditService(),
+            $this->sessionStore
         );
     }
 
@@ -115,7 +126,7 @@ class AuthServicesFactory
 
     public function createMicrosoftOidcStateStore(): MicrosoftOidcStateStoreService
     {
-        return $this->microsoftOidcStateStoreService ??= new MicrosoftOidcStateStoreService();
+        return $this->microsoftOidcStateStoreService ??= new MicrosoftOidcStateStoreService($this->sessionStore);
     }
 
     public function createMicrosoftOidcService(): MicrosoftOidcService
@@ -142,4 +153,13 @@ class AuthServicesFactory
     {
         return new OidcHttpGateway();
     }
+
+    private function createAuthSessionTenantContextService(): AuthSessionTenantContextService
+    {
+        return $this->authSessionTenantContextService ??= new AuthSessionTenantContextService(
+            $this->userServicesFactory->createUserTenantContextService(),
+            $this->authGatewayFactory->createAuthSavedFilterGateway(),
+            $this->sessionStore
+        );
+    }
 }
diff --git a/lib/Service/Auth/AuthSessionTenantContextService.php b/lib/Service/Auth/AuthSessionTenantContextService.php
new file mode 100644
index 0000000..b538947
--- /dev/null
+++ b/lib/Service/Auth/AuthSessionTenantContextService.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace MintyPHP\Service\Auth;
+
+use MintyPHP\Http\SessionStoreInterface;
+use MintyPHP\Service\User\UserTenantContextService;
+
+class AuthSessionTenantContextService
+{
+    public function __construct(
+        private readonly UserTenantContextService $userTenantContextService,
+        private readonly AuthSavedFilterGateway $savedFilterGateway,
+        private readonly SessionStoreInterface $sessionStore
+    ) {
+    }
+
+    public function hydrateForUser(int $userId): void
+    {
+        if ($userId <= 0) {
+            return;
+        }
+
+        $availableTenants = $this->userTenantContextService->getAvailableTenants($userId);
+        $this->sessionStore->set('available_tenants', $availableTenants);
+        $this->sessionStore->set('available_departments_by_tenant', $this->userTenantContextService->getAvailableDepartmentsByTenant($userId));
+        $this->sessionStore->set('address_book_saved_filters', $this->savedFilterGateway->listAddressBookFilters($userId));
+
+        if (!$availableTenants) {
+            $this->sessionStore->set('no_active_tenant', true);
+            $this->sessionStore->remove('current_tenant');
+            return;
+        }
+
+        $this->sessionStore->set('no_active_tenant', false);
+
+        // If the DB has no preferred tenant stored, fall back to the first available one.
+        $currentTenant = $this->userTenantContextService->getCurrentTenant($userId);
+        if (!$currentTenant) {
+            $currentTenant = $availableTenants[0];
+        }
+
+        if ($currentTenant) {
+            $this->sessionStore->set('current_tenant', $currentTenant);
+        }
+    }
+}
diff --git a/lib/Service/Auth/AuthSettingsGateway.php b/lib/Service/Auth/AuthSettingsGateway.php
index d69d97d..85e8014 100644
--- a/lib/Service/Auth/AuthSettingsGateway.php
+++ b/lib/Service/Auth/AuthSettingsGateway.php
@@ -2,51 +2,58 @@
 
 namespace MintyPHP\Service\Auth;
 
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsApiPolicyGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsMicrosoftGateway;
 
 class AuthSettingsGateway
 {
-    public function __construct(private readonly SettingGateway $settingGateway)
-    {
+    public function __construct(
+        private readonly SettingsMicrosoftGateway $settingsMicrosoftGateway,
+        private readonly SettingsApiPolicyGateway $settingsApiPolicyGateway,
+        private readonly SettingsDefaultsGateway $settingsDefaultsGateway,
+        private readonly SettingsAppGateway $settingsAppGateway
+    ) {
     }
 
     public function getMicrosoftSharedClientId(): string
     {
-        return (string) $this->settingGateway->getMicrosoftSharedClientId();
+        return (string) $this->settingsMicrosoftGateway->getMicrosoftSharedClientId();
     }
 
     public function getMicrosoftSharedClientSecret(): string
     {
-        return (string) $this->settingGateway->getMicrosoftSharedClientSecret();
+        return (string) $this->settingsMicrosoftGateway->getMicrosoftSharedClientSecret();
     }
 
     public function getMicrosoftAuthority(): string
     {
-        return (string) $this->settingGateway->getMicrosoftAuthority();
+        return (string) $this->settingsMicrosoftGateway->getMicrosoftAuthority();
     }
 
     public function getApiTokenMaxTtlDays(): int
     {
-        return $this->settingGateway->getApiTokenMaxTtlDays();
+        return $this->settingsApiPolicyGateway->getApiTokenMaxTtlDays();
     }
 
     public function getApiTokenDefaultTtlDays(): int
     {
-        return $this->settingGateway->getApiTokenDefaultTtlDays();
+        return $this->settingsApiPolicyGateway->getApiTokenDefaultTtlDays();
     }
 
     public function getAppTheme(): string
     {
-        return (string) $this->settingGateway->getAppTheme();
+        return (string) $this->settingsAppGateway->getAppTheme();
     }
 
     public function getDefaultRoleId(): int
     {
-        return (int) $this->settingGateway->getDefaultRoleId();
+        return (int) $this->settingsDefaultsGateway->getDefaultRoleId();
     }
 
     public function getDefaultDepartmentId(): int
     {
-        return (int) $this->settingGateway->getDefaultDepartmentId();
+        return (int) $this->settingsDefaultsGateway->getDefaultDepartmentId();
     }
 }
diff --git a/lib/Service/Auth/MicrosoftOidcService.php b/lib/Service/Auth/MicrosoftOidcService.php
index b47ae48..36b6be2 100644
--- a/lib/Service/Auth/MicrosoftOidcService.php
+++ b/lib/Service/Auth/MicrosoftOidcService.php
@@ -7,6 +7,7 @@ use MintyPHP\I18n;
 
 class MicrosoftOidcService
 {
+    // 120s tolerance on exp/nbf checks to handle minor clock drift between systems.
     private const CLOCK_SKEW = 120;
 
     public function __construct(
@@ -30,6 +31,7 @@ class MicrosoftOidcService
         }
         $metadata = $oidc['config'] ?? [];
 
+        // PKCE flow: store code_verifier in session, send only the SHA-256 challenge to the AS.
         $state = self::randomString(32);
         $nonce = self::randomString(32);
         $codeVerifier = self::randomString(64);
@@ -461,6 +463,8 @@ class MicrosoftOidcService
         return is_string($decoded) ? $decoded : '';
     }
 
+    // Builds a PEM public key from a JWK RSA key (n, e) by constructing the ASN.1 DER structure manually.
+    // PHP's openssl extension doesn't support importing JWK directly, so we encode it ourselves.
     private static function jwkToPem(array $jwk): ?string
     {
         $n = self::base64UrlDecode((string) ($jwk['n'] ?? ''));
diff --git a/lib/Service/Auth/MicrosoftOidcStateStoreService.php b/lib/Service/Auth/MicrosoftOidcStateStoreService.php
index c0212c8..cea609d 100644
--- a/lib/Service/Auth/MicrosoftOidcStateStoreService.php
+++ b/lib/Service/Auth/MicrosoftOidcStateStoreService.php
@@ -2,11 +2,14 @@
 
 namespace MintyPHP\Service\Auth;
 
+use MintyPHP\Http\SessionStoreInterface;
+
 class MicrosoftOidcStateStoreService
 {
     private const SESSION_KEY = 'microsoft_oidc_states';
 
     public function __construct(
+        private readonly SessionStoreInterface $sessionStore,
         private readonly int $ttlSeconds = 600,
         private readonly int $maxEntries = 50
     ) {
@@ -25,6 +28,7 @@ class MicrosoftOidcStateStoreService
         $payload['created_at'] = (int) ($payload['created_at'] ?? time());
         $states[$state] = $payload;
 
+        // Cap size to prevent session bloat from many unfinished authorization flows.
         if (count($states) > $this->maxEntries) {
             uasort($states, static function (array $a, array $b): int {
                 return ((int) ($a['created_at'] ?? 0)) <=> ((int) ($b['created_at'] ?? 0));
@@ -34,7 +38,7 @@ class MicrosoftOidcStateStoreService
             }
         }
 
-        $_SESSION[self::SESSION_KEY] = $states;
+        $this->sessionStore->set(self::SESSION_KEY, $states);
     }
 
     /**
@@ -53,8 +57,9 @@ class MicrosoftOidcStateStoreService
             return ['ok' => false, 'error' => 'state_invalid'];
         }
 
+        // Remove the state before checking TTL — prevents replay even if the check below rejects it.
         unset($states[$state]);
-        $_SESSION[self::SESSION_KEY] = $states;
+        $this->sessionStore->set(self::SESSION_KEY, $states);
 
         $createdAt = (int) ($entry['created_at'] ?? 0);
         if ($createdAt <= 0 || (time() - $createdAt) > $this->ttlSeconds) {
@@ -66,12 +71,12 @@ class MicrosoftOidcStateStoreService
 
     public function prune(): void
     {
-        $_SESSION[self::SESSION_KEY] = $this->pruneExpiredStates($this->states());
+        $this->sessionStore->set(self::SESSION_KEY, $this->pruneExpiredStates($this->states()));
     }
 
     private function states(): array
     {
-        $states = $_SESSION[self::SESSION_KEY] ?? [];
+        $states = $this->sessionStore->get(self::SESSION_KEY, []);
         return is_array($states) ? $states : [];
     }
 
diff --git a/lib/Service/Auth/PasswordResetService.php b/lib/Service/Auth/PasswordResetService.php
index 9210454..cd45b05 100644
--- a/lib/Service/Auth/PasswordResetService.php
+++ b/lib/Service/Auth/PasswordResetService.php
@@ -31,6 +31,7 @@ class PasswordResetService
             return ['ok' => false, 'error' => 'email_required'];
         }
 
+        // Return ok:true even when the email is unknown — prevents email enumeration.
         $user = $this->userReadRepository->findByEmail($email);
         if (!$user || !isset($user['id'])) {
             return ['ok' => true];
@@ -148,6 +149,7 @@ class PasswordResetService
         return ['ok' => true];
     }
 
+    // random_int is cryptographically secure; str_pad preserves leading zeros (e.g. "001234").
     private function generateCode(): string
     {
         $max = (10 ** self::CODE_LENGTH) - 1;
diff --git a/lib/Service/Auth/RememberMeService.php b/lib/Service/Auth/RememberMeService.php
index 171e5ae..d12637c 100644
--- a/lib/Service/Auth/RememberMeService.php
+++ b/lib/Service/Auth/RememberMeService.php
@@ -3,11 +3,13 @@
 namespace MintyPHP\Service\Auth;
 
 use MintyPHP\Auth;
+use MintyPHP\Http\CookieStoreInterface;
 use MintyPHP\I18n;
+use MintyPHP\Http\RequestRuntimeInterface;
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Auth\RememberTokenRepositoryInterface;
 use MintyPHP\Repository\User\UserReadRepositoryInterface;
 use MintyPHP\Repository\User\UserWriteRepositoryInterface;
-use MintyPHP\Service\User\UserTenantContextService;
 use MintyPHP\Session;
 
 class RememberMeService
@@ -19,9 +21,11 @@ class RememberMeService
         private readonly UserReadRepositoryInterface $userReadRepository,
         private readonly UserWriteRepositoryInterface $userWriteRepository,
         private readonly RememberTokenRepositoryInterface $rememberTokenRepository,
-        private readonly UserTenantContextService $userTenantContextService,
         private readonly AuthPermissionGateway $permissionGateway,
-        private readonly AuthSavedFilterGateway $savedFilterGateway
+        private readonly AuthSessionTenantContextService $authSessionTenantContextService,
+        private readonly SessionStoreInterface $sessionStore,
+        private readonly CookieStoreInterface $cookieStore,
+        private readonly RequestRuntimeInterface $requestRuntime
     ) {
     }
 
@@ -37,10 +41,11 @@ class RememberMeService
 
     public function autoLoginFromCookie(): bool
     {
-        if (!empty($_SESSION['user']['id'])) {
+        $sessionUser = $this->sessionStore->get('user', []);
+        if (is_array($sessionUser) && !empty($sessionUser['id'])) {
             return false;
         }
-        $value = $_COOKIE[$this->cookieName()] ?? '';
+        $value = $this->cookieStore->get($this->cookieName());
         if ($value === '' || strpos($value, ':') === false) {
             return false;
         }
@@ -86,15 +91,15 @@ class RememberMeService
         }
 
         Session::regenerate();
-        $_SESSION['user'] = $user;
+        $this->sessionStore->set('user', $user);
         if (!empty($user['locale'])) {
             I18n::$locale = (string) $user['locale'];
         }
         $userId = (int) $user['id'];
         if ($userId > 0) {
             $this->permissionGateway->warmUserPermissions($userId, true);
-            $this->loadTenantDataIntoSession($userId);
-            if (!empty($_SESSION['no_active_tenant'])) {
+            $this->authSessionTenantContextService->hydrateForUser($userId);
+            if ((bool) $this->sessionStore->get('no_active_tenant', false)) {
                 // Enforce the same tenant policy as interactive login.
                 $this->forgetCurrentUser();
                 Auth::logout();
@@ -103,6 +108,7 @@ class RememberMeService
             $this->userWriteRepository->updateLastLogin($userId, 'local');
         }
 
+        // Rotate token on each auto-login — limits the window if a cookie is stolen.
         $newToken = bin2hex(random_bytes(32));
         $newHash = hash('sha256', $newToken);
         $newExpires = gmdate('Y-m-d H:i:s', time() + $this->lifetimeSeconds());
@@ -114,7 +120,7 @@ class RememberMeService
 
     public function forgetCurrentUser(): void
     {
-        $value = $_COOKIE[$this->cookieName()] ?? '';
+        $value = $this->cookieStore->get($this->cookieName());
         if ($value !== '' && strpos($value, ':') !== false) {
             [$selector] = explode(':', $value, 2);
             $selector = trim($selector);
@@ -142,10 +148,9 @@ class RememberMeService
     {
         $value = $selector . ':' . $token;
         $expires = time() + $this->lifetimeSeconds();
-        $secure = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off')
-            || (($_SERVER['HTTP_X_FORWARDED_PROTO'] ?? '') === 'https');
+        $secure = $this->requestRuntime->isSecure();
 
-        setcookie($this->cookieName(), $value, [
+        $this->cookieStore->set($this->cookieName(), $value, [
             'expires' => $expires,
             'path' => '/',
             'secure' => $secure,
@@ -156,10 +161,8 @@ class RememberMeService
 
     private function clearCookie(): void
     {
-        $secure = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off')
-            || (($_SERVER['HTTP_X_FORWARDED_PROTO'] ?? '') === 'https');
-        setcookie($this->cookieName(), '', [
-            'expires' => time() - 3600,
+        $secure = $this->requestRuntime->isSecure();
+        $this->cookieStore->remove($this->cookieName(), [
             'path' => '/',
             'secure' => $secure,
             'httponly' => true,
@@ -178,30 +181,4 @@ class RememberMeService
         return trim($name) !== '' ? $name : self::COOKIE_NAME;
     }
 
-    private function loadTenantDataIntoSession(int $userId): void
-    {
-        if ($userId <= 0) {
-            return;
-        }
-
-        $availableTenants = $this->userTenantContextService->getAvailableTenants($userId);
-        $_SESSION['available_tenants'] = $availableTenants;
-        $_SESSION['available_departments_by_tenant'] = $this->userTenantContextService->getAvailableDepartmentsByTenant($userId);
-        $_SESSION['address_book_saved_filters'] = $this->savedFilterGateway->listAddressBookFilters($userId);
-
-        if (!$availableTenants) {
-            $_SESSION['no_active_tenant'] = true;
-            unset($_SESSION['current_tenant']);
-            return;
-        }
-        $_SESSION['no_active_tenant'] = false;
-
-        $currentTenant = $this->userTenantContextService->getCurrentTenant($userId);
-        if (!$currentTenant) {
-            $currentTenant = $availableTenants[0];
-        }
-        if ($currentTenant) {
-            $_SESSION['current_tenant'] = $currentTenant;
-        }
-    }
 }
diff --git a/lib/Service/Auth/SsoUserLinkService.php b/lib/Service/Auth/SsoUserLinkService.php
index e61e0a4..f80554d 100644
--- a/lib/Service/Auth/SsoUserLinkService.php
+++ b/lib/Service/Auth/SsoUserLinkService.php
@@ -35,6 +35,8 @@ class SsoUserLinkService
         }
 
         $providerKey = $this->tenantSsoGateway->microsoftProviderKey();
+        // Look up by OID first (stable Microsoft object ID), fall back to issuer+subject
+        // to handle tenants that migrated from an older OIDC setup without OID.
         $identity = $this->externalIdentityGateway->findByProviderTidOid(
             $providerKey,
             $tid,
@@ -257,6 +259,8 @@ class SsoUserLinkService
         return $locale;
     }
 
+    // SSO users never log in with a password, but the DB column is NOT NULL.
+    // The suffix ensures the hash satisfies any strength validators.
     private function randomPassword(): string
     {
         return 'sso-' . bin2hex(random_bytes(24)) . '-A1!';
diff --git a/lib/Service/Auth/TenantSsoService.php b/lib/Service/Auth/TenantSsoService.php
index 8851841..5db5a29 100644
--- a/lib/Service/Auth/TenantSsoService.php
+++ b/lib/Service/Auth/TenantSsoService.php
@@ -55,6 +55,7 @@ class TenantSsoService
             }
         }
 
+        // Reject ambiguous slugs — if two tenants have the same name-slug, neither matches.
         if (count($matches) !== 1) {
             return null;
         }
@@ -300,6 +301,7 @@ class TenantSsoService
         return ['ok' => true];
     }
 
+    // Empty allowedDomains list means all email domains are permitted.
     public function isEmailDomainAllowed(string $email, array $allowedDomains): bool
     {
         $allowedDomains = array_values(array_filter(array_map(
diff --git a/lib/Service/Branding/BrandingFaviconService.php b/lib/Service/Branding/BrandingFaviconService.php
index 2898f60..a017ac4 100644
--- a/lib/Service/Branding/BrandingFaviconService.php
+++ b/lib/Service/Branding/BrandingFaviconService.php
@@ -3,7 +3,7 @@
 namespace MintyPHP\Service\Branding;
 
 use MintyPHP\Service\Image\ImageUploadTrait;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
 
 class BrandingFaviconService
 {
@@ -19,7 +19,7 @@ class BrandingFaviconService
         512 => 'web-app-manifest-512x512.png',
     ];
 
-    public function __construct(private readonly SettingGateway $settingGateway)
+    public function __construct(private readonly SettingsAppGateway $settingsAppGateway)
     {
     }
 
@@ -132,7 +132,7 @@ class BrandingFaviconService
             }
         }
 
-        $title = $this->settingGateway->getAppTitle();
+        $title = $this->settingsAppGateway->getAppTitle();
         if ($title === null || $title === '') {
             $title = defined('APP_NAME') ? APP_NAME : 'IMVS';
         }
diff --git a/lib/Service/Branding/BrandingLogoService.php b/lib/Service/Branding/BrandingLogoService.php
index f502f06..529f6a3 100644
--- a/lib/Service/Branding/BrandingLogoService.php
+++ b/lib/Service/Branding/BrandingLogoService.php
@@ -103,6 +103,7 @@ class BrandingLogoService
         }
         @chmod($originalPath, 0644);
 
+        // SVGs are served as-is (no rasterization); raster images get WebP variants if GD supports it.
         $variantExt = function_exists('imagewebp') ? 'webp' : 'jpg';
         if (!$isSvg && self::imageCanResize()) {
             foreach (self::SIZES as $size) {
@@ -127,6 +128,7 @@ class BrandingLogoService
         return self::DEFAULT_SIZE;
     }
 
+    // Multiple extensions may exist (e.g. after format change) — pick the most recently modified one.
     private function findVariantPath(string $dir, int $size): ?string
     {
         $matches = glob($dir . '/logo-' . $size . '.*');
diff --git a/lib/Service/Branding/BrandingServicesFactory.php b/lib/Service/Branding/BrandingServicesFactory.php
index bd0864a..e910383 100644
--- a/lib/Service/Branding/BrandingServicesFactory.php
+++ b/lib/Service/Branding/BrandingServicesFactory.php
@@ -2,7 +2,7 @@
 
 namespace MintyPHP\Service\Branding;
 
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
 
 class BrandingServicesFactory
 {
@@ -10,7 +10,7 @@ class BrandingServicesFactory
     private ?BrandingFaviconService $brandingFaviconService = null;
 
     public function __construct(
-        private readonly SettingGateway $settingGateway
+        private readonly SettingsAppGateway $settingsAppGateway
     ) {
     }
 
@@ -21,11 +21,11 @@ class BrandingServicesFactory
 
     public function createBrandingFaviconService(): BrandingFaviconService
     {
-        return $this->brandingFaviconService ??= new BrandingFaviconService($this->createSettingGateway());
+        return $this->brandingFaviconService ??= new BrandingFaviconService($this->createSettingsAppGateway());
     }
 
-    private function createSettingGateway(): SettingGateway
+    private function createSettingsAppGateway(): SettingsAppGateway
     {
-        return $this->settingGateway;
+        return $this->settingsAppGateway;
     }
 }
diff --git a/lib/Service/CustomField/TenantCustomFieldService.php b/lib/Service/CustomField/TenantCustomFieldService.php
index b0506ec..0cbf0b7 100644
--- a/lib/Service/CustomField/TenantCustomFieldService.php
+++ b/lib/Service/CustomField/TenantCustomFieldService.php
@@ -129,6 +129,7 @@ class TenantCustomFieldService
             return ['ok' => false, 'errors' => [t('Custom field can not be updated')], 'form' => $form];
         }
 
+        // When type is changed away from select/multiselect, remove orphaned option rows.
         if (in_array($form['type'], ['select', 'multiselect'], true)) {
             TenantCustomFieldOptionRepository::replaceForDefinition((int) $existing['id'], $form['options']);
         } else {
@@ -220,6 +221,7 @@ class TenantCustomFieldService
             $form['options'] = [];
         }
 
+        // Text/textarea types can't be used as filters — too many distinct values to enumerate in UI.
         if (!in_array($type, ['select', 'multiselect', 'boolean', 'date'], true)) {
             $form['is_filterable'] = 0;
         }
@@ -227,6 +229,8 @@ class TenantCustomFieldService
         return $errors;
     }
 
+    // Line format: "key|Label" or just "Label" (key is derived from the label when omitted).
+    // Duplicate keys are silently dropped — first occurrence wins.
     private static function parseOptionsLines(string $value): array
     {
         $lines = preg_split('/\r\n|\r|\n/', $value);
@@ -261,6 +265,8 @@ class TenantCustomFieldService
         return array_values($options);
     }
 
+    // Transliterates accented characters (é → e, ü → u) before slugifying so non-ASCII labels
+    // produce readable keys. Falls back to direct slugification if iconv is unavailable.
     private static function normalizeKey(string $value): string
     {
         $value = trim($value);
@@ -307,6 +313,7 @@ class TenantCustomFieldService
             return '';
         }
 
+        // Auto-increment suffix until a unique key is found; 10000 guard prevents infinite loop.
         $candidate = $base;
         $counter = 2;
         while (true) {
diff --git a/lib/Service/CustomField/UserCustomFieldValueService.php b/lib/Service/CustomField/UserCustomFieldValueService.php
index a74561d..47a92ee 100644
--- a/lib/Service/CustomField/UserCustomFieldValueService.php
+++ b/lib/Service/CustomField/UserCustomFieldValueService.php
@@ -251,7 +251,8 @@ class UserCustomFieldValueService
         }
 
         $tenantIds = self::normalizeTenantIds($tenantIds);
-        // Always clean values that belong to tenants no longer assigned to the user.
+        // Always clean values for tenants no longer assigned — happens even when !$canEdit,
+        // because orphaned custom field data should not persist after tenant reassignment.
         if (!UserCustomFieldValueRepository::deleteByUserOutsideTenantIds($userId, $tenantIds)) {
             return ['ok' => false, 'errors' => [t('Custom field values can not be saved')]];
         }
@@ -454,6 +455,7 @@ class UserCustomFieldValueService
                 continue;
             }
 
+            // URL key prefixes: cf_ = single-value (select/boolean), cfm_ = multiselect, cfd_ = date range.
             if (preg_match('/^cf_([a-f0-9-]{36})$/', $key, $match)) {
                 $uuid = $match[1];
                 $definition = $definitionMapByUuid[$uuid] ?? null;
diff --git a/lib/Service/Directory/DirectoryGatewayFactory.php b/lib/Service/Directory/DirectoryGatewayFactory.php
index 960dc1d..2b4d240 100644
--- a/lib/Service/Directory/DirectoryGatewayFactory.php
+++ b/lib/Service/Directory/DirectoryGatewayFactory.php
@@ -19,7 +19,7 @@ class DirectoryGatewayFactory
     public function createDirectorySettingsGateway(): DirectorySettingsGateway
     {
         return $this->directorySettingsGateway ??= new DirectorySettingsGateway(
-            $this->settingServicesFactory->createSettingGateway()
+            $this->settingServicesFactory->createSettingsDefaultsGateway()
         );
     }
 
diff --git a/lib/Service/Directory/DirectoryScopeGateway.php b/lib/Service/Directory/DirectoryScopeGateway.php
index b33f83e..fc9fde5 100644
--- a/lib/Service/Directory/DirectoryScopeGateway.php
+++ b/lib/Service/Directory/DirectoryScopeGateway.php
@@ -41,6 +41,9 @@ class DirectoryScopeGateway
         return $this->tenantScopeService->filterTenantIdsForUser($tenantIds, $userId);
     }
 
+    // When a scoped admin updates tenant assignments, they can't see tenants outside their scope.
+    // This merges the requested IDs with any out-of-scope IDs from existing assignments so those
+    // aren't silently dropped when the admin saves.
     public function mergeTenantIdsPreservingOutOfScope(
         array $requestedTenantIds,
         array $existingTenantIds,
diff --git a/lib/Service/Directory/DirectoryServicesFactory.php b/lib/Service/Directory/DirectoryServicesFactory.php
index cc5a9f4..fd73a25 100644
--- a/lib/Service/Directory/DirectoryServicesFactory.php
+++ b/lib/Service/Directory/DirectoryServicesFactory.php
@@ -55,6 +55,7 @@ class DirectoryServicesFactory
         );
     }
 
+    // Passthrough accessors so callers only need a reference to this factory, not the sub-factories.
     public function createTenantRepository(): TenantRepositoryInterface
     {
         return $this->directoryRepositoryFactory->createTenantRepository();
diff --git a/lib/Service/Directory/DirectorySettingsGateway.php b/lib/Service/Directory/DirectorySettingsGateway.php
index ce55c90..887537d 100644
--- a/lib/Service/Directory/DirectorySettingsGateway.php
+++ b/lib/Service/Directory/DirectorySettingsGateway.php
@@ -2,26 +2,26 @@
 
 namespace MintyPHP\Service\Directory;
 
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
 
 class DirectorySettingsGateway
 {
-    public function __construct(private readonly SettingGateway $settingGateway)
+    public function __construct(private readonly SettingsDefaultsGateway $settingsDefaultsGateway)
     {
     }
 
     public function setDefaultTenantId(?int $tenantId): void
     {
-        $this->settingGateway->setDefaultTenantId($tenantId);
+        $this->settingsDefaultsGateway->setDefaultTenantId($tenantId);
     }
 
     public function setDefaultDepartmentId(?int $departmentId): void
     {
-        $this->settingGateway->setDefaultDepartmentId($departmentId);
+        $this->settingsDefaultsGateway->setDefaultDepartmentId($departmentId);
     }
 
     public function setDefaultRoleId(?int $roleId): void
     {
-        $this->settingGateway->setDefaultRoleId($roleId);
+        $this->settingsDefaultsGateway->setDefaultRoleId($roleId);
     }
 }
diff --git a/lib/Service/Import/CsvReaderService.php b/lib/Service/Import/CsvReaderService.php
index 028a4f5..53d2b78 100644
--- a/lib/Service/Import/CsvReaderService.php
+++ b/lib/Service/Import/CsvReaderService.php
@@ -84,6 +84,7 @@ class CsvReaderService
         fclose($handle);
     }
 
+    // Sample-based detection — reading 5 lines is enough to identify the delimiter without scanning the full file.
     private function detectDelimiter(string $path): string
     {
         $sample = '';
@@ -154,6 +155,7 @@ class CsvReaderService
                 }
             }
 
+            // Case-insensitive duplicate check — "Email" and "email" in the same header row are ambiguous.
             $normalizedKeys = array_map([$this, 'lower'], $headers);
             if (count(array_unique($normalizedKeys)) !== count($normalizedKeys)) {
                 return ['ok' => false, 'code' => 'invalid_csv_header'];
@@ -177,6 +179,7 @@ class CsvReaderService
             $normalized[] = $this->cleanCell((string) $cell);
         }
 
+        // Pad short rows and trim over-long rows so every row has exactly as many cells as headers.
         $current = count($normalized);
         if ($current < $size) {
             $normalized = array_pad($normalized, $size, '');
@@ -236,6 +239,7 @@ class CsvReaderService
         return $value;
     }
 
+    // Remove null bytes (defense against null byte injection) and UTF-8 BOM from each cell.
     private function cleanCell(string $value): string
     {
         $value = str_replace("\0", '', $value);
diff --git a/lib/Service/Import/ImportService.php b/lib/Service/Import/ImportService.php
index f1b61e3..b09dbb4 100644
--- a/lib/Service/Import/ImportService.php
+++ b/lib/Service/Import/ImportService.php
@@ -2,11 +2,12 @@
 
 namespace MintyPHP\Service\Import;
 
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Service\Access\PermissionGateway;
 use MintyPHP\Service\Access\PermissionService;
 use MintyPHP\Service\Audit\ImportAuditService;
 use MintyPHP\Service\Import\Profile\ImportProfileInterface;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
 use MintyPHP\Service\User\UserScopeGateway;
 
 class ImportService
@@ -28,8 +29,9 @@ class ImportService
         private readonly ImportStateStoreService $importStateStoreService,
         private readonly array $profiles,
         private readonly PermissionGateway $permissionGateway,
-        private readonly SettingGateway $settingGateway,
-        private readonly UserScopeGateway $userScopeGateway
+        private readonly SettingsDefaultsGateway $settingsDefaultsGateway,
+        private readonly UserScopeGateway $userScopeGateway,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -139,6 +141,7 @@ class ImportService
         if (!$state) {
             return ['ok' => false, 'code' => 'invalid_file_type'];
         }
+        // Prevent cross-user token reuse — the state token is session-scoped but user_id is verified explicitly.
         if ((int) ($state['user_id'] ?? 0) !== $currentUserId) {
             return ['ok' => false, 'code' => 'invalid_file_type'];
         }
@@ -154,6 +157,8 @@ class ImportService
         }
 
         $mappedTargets = $mappingResult['mapped_targets'] ?? [];
+        // Tenant/role/department column mapping requires a separate permission — a user who can import
+        // users generally may not be allowed to also assign them to tenants.
         if (
             $profile->requiresAssignmentPermission()
             && $this->usesAssignmentTargets($mappedTargets)
@@ -203,7 +208,7 @@ class ImportService
             $mappingResult['mapped_targets'] ?? [],
             isset($state['source_filename']) ? (string) $state['source_filename'] : null,
             $currentUserId,
-            isset($_SESSION['current_tenant']['id']) ? (int) $_SESSION['current_tenant']['id'] : null
+            $this->currentTenantId()
         );
 
         $result = ['ok' => false, 'code' => 'unexpected_error', 'processed' => 0, 'created' => 0, 'skipped' => 0, 'failed' => 1];
@@ -301,6 +306,7 @@ class ImportService
 
                     $normalized = $validation['normalized'];
                     $identifier = $profile->rowIdentifier($normalized);
+                    // Detect duplicates within the file itself (e.g. same email appearing twice).
                     $duplicateKey = $profile->inFileDuplicateKey($normalized);
                     if ($duplicateKey !== null && $duplicateKey !== '') {
                         if (isset($seenRowKeys[$duplicateKey])) {
@@ -496,14 +502,28 @@ class ImportService
         return [
             'current_user_id' => $currentUserId,
             'is_global_admin' => $isGlobalAdmin,
+            // Empty allowed_tenant_ids signals "no restriction" to profile validators for global admins.
             'allowed_tenant_ids' => $isGlobalAdmin ? [] : $this->userScopeGateway->getUserTenantIds($currentUserId),
-            'default_tenant_id' => $this->settingGateway->getDefaultTenantId(),
-            'default_role_id' => $this->settingGateway->getDefaultRoleId(),
-            'default_department_id' => $this->settingGateway->getDefaultDepartmentId(),
+            'default_tenant_id' => $this->settingsDefaultsGateway->getDefaultTenantId(),
+            'default_role_id' => $this->settingsDefaultsGateway->getDefaultRoleId(),
+            'default_department_id' => $this->settingsDefaultsGateway->getDefaultDepartmentId(),
             'can_import_assignments' => $this->canImportAssignments($currentUserId),
         ];
     }
 
+    private function currentTenantId(): ?int
+    {
+        $tenant = $this->sessionStore->get('current_tenant', []);
+        if (!is_array($tenant)) {
+            return null;
+        }
+
+        $tenantId = (int) ($tenant['id'] ?? 0);
+        return $tenantId > 0 ? $tenantId : null;
+    }
+
+    // Fallback to uniqid if random_bytes is unavailable — not cryptographically ideal but only
+    // used for session-scoped state tokens, not for security-critical values.
     private function newToken(): string
     {
         try {
@@ -530,6 +550,7 @@ class ImportService
     /**
      * @param array<int, array{row_number:int,identifier:string,code:string,message:string}> $errors
      */
+    // Cap the error list to avoid oversized responses — error_counts still reflects the full count.
     private function pushError(array &$errors, int $lineNumber, string $identifier, string $code, ?string $message): void
     {
         if (count($errors) >= self::MAX_ERROR_ROWS) {
diff --git a/lib/Service/Import/ImportServicesFactory.php b/lib/Service/Import/ImportServicesFactory.php
index 8098791..466112e 100644
--- a/lib/Service/Import/ImportServicesFactory.php
+++ b/lib/Service/Import/ImportServicesFactory.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Service\Import;
 
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Repository\Audit\ImportAuditRunRepositoryInterface;
 use MintyPHP\Service\Access\AccessServicesFactory;
 use MintyPHP\Service\Access\PermissionGateway;
@@ -11,7 +12,7 @@ use MintyPHP\Service\Import\Profile\DepartmentImportGateway;
 use MintyPHP\Service\Import\Profile\DepartmentImportProfile;
 use MintyPHP\Service\Import\Profile\UserImportGateway;
 use MintyPHP\Service\Import\Profile\UserImportProfile;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
 use MintyPHP\Service\Settings\SettingServicesFactory;
 use MintyPHP\Service\User\UserServicesFactory;
 
@@ -22,7 +23,7 @@ class ImportServicesFactory
     private ?ImportStateStoreService $importStateStoreService = null;
     private ?ImportAuditService $importAuditService = null;
     private ?PermissionGateway $permissionGateway = null;
-    private ?SettingGateway $settingGateway = null;
+    private ?SettingsDefaultsGateway $settingsDefaultsGateway = null;
     private ?ImportService $importService = null;
 
     public function __construct(
@@ -30,7 +31,8 @@ class ImportServicesFactory
         private readonly AccessServicesFactory $accessServicesFactory,
         private readonly SettingServicesFactory $settingServicesFactory,
         private readonly DirectoryServicesFactory $directoryServicesFactory,
-        private readonly ImportRepositoryFactory $importRepositoryFactory
+        private readonly ImportRepositoryFactory $importRepositoryFactory,
+        private readonly SessionStoreInterface $sessionStore
     ) {
     }
 
@@ -62,8 +64,9 @@ class ImportServicesFactory
             $this->createImportStateStoreService(),
             $profiles,
             $this->createPermissionGateway(),
-            $this->createSettingGateway(),
-            $this->userServicesFactory->createUserScopeGateway()
+            $this->createSettingsDefaultsGateway(),
+            $this->userServicesFactory->createUserScopeGateway(),
+            $this->sessionStore
         );
     }
 
@@ -74,7 +77,10 @@ class ImportServicesFactory
 
     public function createImportStateStoreService(): ImportStateStoreService
     {
-        return $this->importStateStoreService ??= new ImportStateStoreService($this->getImportTempFileService());
+        return $this->importStateStoreService ??= new ImportStateStoreService(
+            $this->getImportTempFileService(),
+            $this->sessionStore
+        );
     }
 
     private function getCsvReaderService(): CsvReaderService
@@ -97,8 +103,8 @@ class ImportServicesFactory
         return $this->permissionGateway ??= $this->accessServicesFactory->createPermissionGateway();
     }
 
-    private function createSettingGateway(): SettingGateway
+    private function createSettingsDefaultsGateway(): SettingsDefaultsGateway
     {
-        return $this->settingGateway ??= $this->settingServicesFactory->createSettingGateway();
+        return $this->settingsDefaultsGateway ??= $this->settingServicesFactory->createSettingsDefaultsGateway();
     }
 }
diff --git a/lib/Service/Import/ImportStateStoreService.php b/lib/Service/Import/ImportStateStoreService.php
index b8d0c22..52f6456 100644
--- a/lib/Service/Import/ImportStateStoreService.php
+++ b/lib/Service/Import/ImportStateStoreService.php
@@ -2,12 +2,17 @@
 
 namespace MintyPHP\Service\Import;
 
+use MintyPHP\Http\SessionStoreInterface;
+
 class ImportStateStoreService
 {
     private const SESSION_KEY = 'admin_imports_v1';
     private const STATE_TTL_SECONDS = 7200;
 
-    public function __construct(private readonly ImportTempFileService $importTempFileService)
+    public function __construct(
+        private readonly ImportTempFileService $importTempFileService,
+        private readonly SessionStoreInterface $sessionStore
+    )
     {
     }
 
@@ -16,10 +21,12 @@ class ImportStateStoreService
      */
     public function setState(string $token, array $state): void
     {
-        if (!isset($_SESSION[self::SESSION_KEY]) || !is_array($_SESSION[self::SESSION_KEY])) {
-            $_SESSION[self::SESSION_KEY] = [];
+        $states = $this->sessionStore->get(self::SESSION_KEY, []);
+        if (!is_array($states)) {
+            $states = [];
         }
-        $_SESSION[self::SESSION_KEY][$token] = $state;
+        $states[$token] = $state;
+        $this->sessionStore->set(self::SESSION_KEY, $states);
     }
 
     /**
@@ -32,7 +39,7 @@ class ImportStateStoreService
             return null;
         }
 
-        $all = $_SESSION[self::SESSION_KEY] ?? [];
+        $all = $this->sessionStore->get(self::SESSION_KEY, []);
         if (!is_array($all)) {
             return null;
         }
@@ -42,6 +49,7 @@ class ImportStateStoreService
             return null;
         }
 
+        // Lazy expiry: clean up the temp file and session entry when the state is accessed after TTL.
         $createdAt = (int) ($state['created_at'] ?? 0);
         if ($createdAt > 0 && (time() - $createdAt) > self::STATE_TTL_SECONDS) {
             $this->importTempFileService->delete((string) ($state['path'] ?? ''));
@@ -54,9 +62,12 @@ class ImportStateStoreService
 
     public function clearState(string $token): void
     {
-        if (!isset($_SESSION[self::SESSION_KEY]) || !is_array($_SESSION[self::SESSION_KEY])) {
+        $states = $this->sessionStore->get(self::SESSION_KEY, []);
+        if (!is_array($states)) {
             return;
         }
-        unset($_SESSION[self::SESSION_KEY][$token]);
+
+        unset($states[$token]);
+        $this->sessionStore->set(self::SESSION_KEY, $states);
     }
 }
diff --git a/lib/Service/Import/ImportTempFileService.php b/lib/Service/Import/ImportTempFileService.php
index 2b6dc61..d31f7b4 100644
--- a/lib/Service/Import/ImportTempFileService.php
+++ b/lib/Service/Import/ImportTempFileService.php
@@ -40,6 +40,7 @@ class ImportTempFileService
             return ['ok' => false, 'code' => 'unexpected_error'];
         }
 
+        // Lazy cleanup on each upload — removes abandoned files without needing a separate cron job.
         $this->cleanupExpired();
 
         try {
@@ -47,6 +48,8 @@ class ImportTempFileService
         } catch (\Throwable $exception) {
             $target = $dir . '/import_' . str_replace('.', '', uniqid('', true)) . '.csv';
         }
+        // Real uploads use move_uploaded_file (validates PHP upload context).
+        // Fallback rename/copy path handles test uploads without a real HTTP context.
         $moved = false;
         if (is_uploaded_file($tmpName)) {
             $moved = @move_uploaded_file($tmpName, $target);
@@ -122,6 +125,7 @@ class ImportTempFileService
         return in_array($extension, ['csv', 'txt'], true);
     }
 
+    // Resolves both paths via realpath to prevent path traversal attacks (e.g. "../../../etc/passwd").
     private function isInTmpDir(string $path): bool
     {
         $tmpDir = $this->tmpDir();
diff --git a/lib/Service/Mail/MailService.php b/lib/Service/Mail/MailService.php
index 9434068..7e2b4ef 100644
--- a/lib/Service/Mail/MailService.php
+++ b/lib/Service/Mail/MailService.php
@@ -5,7 +5,7 @@ namespace MintyPHP\Service\Mail;
 use MintyPHP\Domain\Taxonomy\MailLogStatus;
 use MintyPHP\I18n;
 use MintyPHP\Repository\Mail\MailLogRepositoryInterface;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsSmtpGateway;
 use PHPMailer\PHPMailer\Exception as MailerException;
 use PHPMailer\PHPMailer\PHPMailer;
 
@@ -13,7 +13,7 @@ class MailService
 {
     public function __construct(
         private readonly MailLogRepositoryInterface $mailLogRepository,
-        private readonly SettingGateway $settingGateway
+        private readonly SettingsSmtpGateway $settingsSmtpGateway
     ) {
     }
 
@@ -39,6 +39,7 @@ class MailService
         string $text,
         array $meta = []
     ): array {
+        // Log before sending so there's a record even if the send throws an exception.
         $logId = $this->mailLogRepository->create([
             'to_email' => $to,
             'subject' => $subject,
@@ -90,19 +91,6 @@ class MailService
         if (!is_file($textPath)) {
             $textPath = $base . '/' . $template . '.txt';
         }
-        if (!is_file($htmlHeaderPath)) {
-            $htmlHeaderPath = $base . '/partials/header.html';
-        }
-        if (!is_file($htmlFooterPath)) {
-            $htmlFooterPath = $base . '/partials/footer.html';
-        }
-        if (!is_file($textHeaderPath)) {
-            $textHeaderPath = $base . '/partials/header.txt';
-        }
-        if (!is_file($textFooterPath)) {
-            $textFooterPath = $base . '/partials/footer.txt';
-        }
-
         $html = is_file($htmlPath) ? file_get_contents($htmlPath) : '';
         $text = is_file($textPath) ? file_get_contents($textPath) : '';
         if (!isset($vars['email_header'])) {
@@ -138,16 +126,18 @@ class MailService
         $mailer = new PHPMailer(true);
         $mailer->isSMTP();
 
-        $host = $this->settingGateway->getSmtpHost() ?? (getenv('SMTP_HOST') ?: '');
-        $port = $this->settingGateway->getSmtpPort() ?? (int) (getenv('SMTP_PORT') ?: 587);
-        $user = $this->settingGateway->getSmtpUser() ?? (getenv('SMTP_USER') ?: '');
-        $pass = $this->settingGateway->getSmtpPassword() ?? (getenv('SMTP_PASS') ?: '');
-        $secure = $this->settingGateway->getSmtpSecure() ?? strtolower((string) (getenv('SMTP_SECURE') ?: 'tls'));
-        $from = $this->settingGateway->getSmtpFrom() ?? (getenv('SMTP_FROM') ?: ($user ?: 'no-reply@localhost'));
-        $fromName = $this->settingGateway->getSmtpFromName() ?? (getenv('SMTP_FROM_NAME') ?: appTitle());
+        // DB setting takes priority; env var fallback allows Docker-compose-style configuration without a DB record.
+        $host = $this->settingsSmtpGateway->getSmtpHost() ?? (getenv('SMTP_HOST') ?: '');
+        $port = $this->settingsSmtpGateway->getSmtpPort() ?? (int) (getenv('SMTP_PORT') ?: 587);
+        $user = $this->settingsSmtpGateway->getSmtpUser() ?? (getenv('SMTP_USER') ?: '');
+        $pass = $this->settingsSmtpGateway->getSmtpPassword() ?? (getenv('SMTP_PASS') ?: '');
+        $secure = $this->settingsSmtpGateway->getSmtpSecure() ?? strtolower((string) (getenv('SMTP_SECURE') ?: 'tls'));
+        $from = $this->settingsSmtpGateway->getSmtpFrom() ?? (getenv('SMTP_FROM') ?: ($user ?: 'no-reply@localhost'));
+        $fromName = $this->settingsSmtpGateway->getSmtpFromName() ?? (getenv('SMTP_FROM_NAME') ?: appTitle());
 
         $mailer->Host = $host;
         $mailer->Port = $port;
+        // Enable SMTP auth only if credentials are configured — supports relay servers without auth.
         $mailer->SMTPAuth = $user !== '' || $pass !== '';
         $mailer->Username = $user;
         $mailer->Password = $pass;
diff --git a/lib/Service/Mail/MailServicesFactory.php b/lib/Service/Mail/MailServicesFactory.php
index 14e1e62..c2d27fe 100644
--- a/lib/Service/Mail/MailServicesFactory.php
+++ b/lib/Service/Mail/MailServicesFactory.php
@@ -3,7 +3,7 @@
 namespace MintyPHP\Service\Mail;
 
 use MintyPHP\Repository\Mail\MailLogRepositoryInterface;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsSmtpGateway;
 
 class MailServicesFactory
 {
@@ -12,7 +12,7 @@ class MailServicesFactory
 
     public function __construct(
         private readonly MailRepositoryFactory $mailRepositoryFactory,
-        private readonly SettingGateway $settingGateway
+        private readonly SettingsSmtpGateway $settingsSmtpGateway
     ) {
     }
 
@@ -25,7 +25,7 @@ class MailServicesFactory
     {
         return $this->mailService ??= new MailService(
             $this->createMailLogRepository(),
-            $this->createSettingGateway()
+            $this->createSettingsSmtpGateway()
         );
     }
 
@@ -34,8 +34,8 @@ class MailServicesFactory
         return $this->mailLogService ??= new MailLogService($this->createMailLogRepository());
     }
 
-    private function createSettingGateway(): SettingGateway
+    private function createSettingsSmtpGateway(): SettingsSmtpGateway
     {
-        return $this->settingGateway;
+        return $this->settingsSmtpGateway;
     }
 }
diff --git a/lib/Service/Org/DepartmentService.php b/lib/Service/Org/DepartmentService.php
index 3202a27..13a19d0 100644
--- a/lib/Service/Org/DepartmentService.php
+++ b/lib/Service/Org/DepartmentService.php
@@ -26,6 +26,7 @@ class DepartmentService
 
     public function listPaged(array $options): array
     {
+        // Global-scope users see all departments — remove tenant filter so the query isn't restricted.
         if (!empty($options['tenantUserId'])) {
             $tenantUserId = (int) $options['tenantUserId'];
             if ($tenantUserId > 0 && $this->scopeGateway->hasGlobalAccess($tenantUserId)) {
@@ -78,6 +79,8 @@ class DepartmentService
         return $this->departmentRepository->listByIds($departmentIds);
     }
 
+    // Merges the tenant-scoped list with any already-selected departments outside the filter —
+    // ensures a user keeps visibility of departments they're already assigned to.
     public function listForUserAssignments(array $tenantIds, array $selectedDepartmentIds): array
     {
         $departments = $tenantIds ? $this->listByTenantIds($tenantIds) : $this->list();
@@ -192,6 +195,8 @@ class DepartmentService
         return ['ok' => true, 'form' => $form, 'warnings' => $warnings];
     }
 
+    // After moving a department to a different tenant, users who aren't in the new tenant
+    // are no longer valid members — remove their assignments immediately.
     public function syncTenant(int $departmentId, int $tenantId): int
     {
         $updated = $this->departmentRepository->setTenant($departmentId, $tenantId);
@@ -201,6 +206,7 @@ class DepartmentService
         return $this->cleanupUserAssignments($departmentId);
     }
 
+    // Departments belong to exactly one tenant — only the first ID in the array is used.
     public function syncTenants(int $departmentId, array $tenantIds): int
     {
         $tenantId = (int) ($tenantIds[0] ?? 0);
@@ -266,6 +272,8 @@ class DepartmentService
         return $errors;
     }
 
+    // Duplicate codes are a warning, not a hard error — codes are optional identifiers,
+    // not unique keys, so duplicates are allowed but surfaced to the user.
     private function warningsForCode(array $form, int $excludeId): array
     {
         $warnings = [];
diff --git a/lib/Service/Scheduler/ScheduledJobService.php b/lib/Service/Scheduler/ScheduledJobService.php
index d0ac3bf..f7db841 100644
--- a/lib/Service/Scheduler/ScheduledJobService.php
+++ b/lib/Service/Scheduler/ScheduledJobService.php
@@ -17,6 +17,8 @@ class ScheduledJobService
     ) {
     }
 
+    // Syncs the registry definitions to the DB on every request that needs job data —
+    // new jobs are inserted automatically without a separate migration step.
     public function ensureSystemJobs(): void
     {
         $definitions = $this->scheduledJobRegistry->definitions();
@@ -217,6 +219,7 @@ class ScheduledJobService
     {
         $type = $this->scheduleCalculator->normalizeScheduleType((string) ($existing['schedule_type'] ?? ($definition['default_schedule_type'] ?? 'daily')));
         $normalized = [
+            // label and description always come from the registry — admin edits to those fields are not preserved.
             'label' => (string) ($definition['label'] ?? (string) ($existing['label'] ?? '')),
             'description' => (string) ($definition['description'] ?? (string) ($existing['description'] ?? '')),
             'enabled' => (int) ($existing['enabled'] ?? ($definition['default_enabled'] ?? 1)),
diff --git a/lib/Service/Scheduler/SchedulerRunService.php b/lib/Service/Scheduler/SchedulerRunService.php
index 38d1202..1d37a2c 100644
--- a/lib/Service/Scheduler/SchedulerRunService.php
+++ b/lib/Service/Scheduler/SchedulerRunService.php
@@ -160,6 +160,7 @@ class SchedulerRunService
             return $run;
         }
 
+        // markRunning uses a conditional update — failure means another process already claimed this job.
         $markedRunning = $this->scheduledJobRepository->markRunning($jobId, $startedAtUtc);
         if (!$markedRunning) {
             $this->insertRunLog([
@@ -268,6 +269,7 @@ class SchedulerRunService
         return $run;
     }
 
+    // Fail-open: a logging failure must not kill the job run that already completed.
     private function insertRunLog(array $data): void
     {
         try {
diff --git a/lib/Service/Security/RateLimiterService.php b/lib/Service/Security/RateLimiterService.php
index d7e4e62..d9b6516 100644
--- a/lib/Service/Security/RateLimiterService.php
+++ b/lib/Service/Security/RateLimiterService.php
@@ -98,6 +98,9 @@ class RateLimiterService
             $nowTs = time();
             $nowSql = gmdate('Y-m-d H:i:s', $nowTs);
 
+            // Two-attempt loop handles a creation race: if two requests arrive simultaneously for a
+            // new subject, both may find no row and try to INSERT. The second INSERT fails (unique key),
+            // so we retry once and the second attempt reads the now-existing row.
             for ($attempt = 0; $attempt < 2; $attempt++) {
                 $row = $this->rateLimitRepository->findByScopeAndHash($normalized['scope'], $normalized['subject_hash']);
 
@@ -136,6 +139,7 @@ class RateLimiterService
                 }
 
                 $windowStartedTs = $this->parseTimestamp((string) ($row['window_started_at'] ?? ''));
+                // Sliding window expired — reset the window start and hit count.
                 if ($windowStartedTs === null || ($windowStartedTs + $windowSeconds) <= $nowTs) {
                     $windowStartedTs = $nowTs;
                     $hits = 0;
@@ -189,6 +193,7 @@ class RateLimiterService
             $scope = substr($scope, 0, 64);
         }
 
+        // Hash the subject (e.g. email or IP) so PII is never stored in the rate limit table.
         return [
             'scope' => $scope,
             'subject_hash' => hash(self::HASH_ALGO, $subject),
diff --git a/lib/Service/Settings/AdminSettingsService.php b/lib/Service/Settings/AdminSettingsService.php
index 80094ed..c6e25c3 100644
--- a/lib/Service/Settings/AdminSettingsService.php
+++ b/lib/Service/Settings/AdminSettingsService.php
@@ -12,7 +12,15 @@ use MintyPHP\Service\Tenant\TenantService;
 class AdminSettingsService
 {
     public function __construct(
-        private readonly SettingGateway $settingGateway,
+        private readonly SettingsDefaultsGateway $settingsDefaultsGateway,
+        private readonly SettingsAppGateway $settingsAppGateway,
+        private readonly SettingsApiPolicyGateway $settingsApiPolicyGateway,
+        private readonly SettingsUserLifecycleGateway $settingsUserLifecycleGateway,
+        private readonly SettingsSystemAuditGateway $settingsSystemAuditGateway,
+        private readonly SettingsFrontendTelemetryGateway $settingsFrontendTelemetryGateway,
+        private readonly SettingsMicrosoftGateway $settingsMicrosoftGateway,
+        private readonly SettingsSmtpGateway $settingsSmtpGateway,
+        private readonly SettingsMetadataGateway $settingsMetadataGateway,
         private readonly SettingCacheService $settingCacheService,
         private readonly TenantService $tenantService,
         private readonly RoleService $roleService,
@@ -40,58 +48,64 @@ class AdminSettingsService
             'roles' => $roles,
             'departments' => $departments,
             'values' => [
-                'default_tenant_id' => $this->settingGateway->getDefaultTenantId(),
-                'default_role_id' => $this->settingGateway->getDefaultRoleId(),
-                'default_department_id' => $this->settingGateway->getDefaultDepartmentId(),
-                'app_title' => $this->settingGateway->getValue(SettingService::APP_TITLE_KEY),
-                'app_locale' => $this->settingGateway->getValue(SettingService::APP_LOCALE_KEY),
-                'app_theme' => $this->settingGateway->getValue(SettingService::APP_THEME_KEY),
-                'app_theme_user' => $this->settingGateway->isUserThemeAllowed(),
-                'app_registration' => $this->settingGateway->isRegistrationEnabled(),
-                'app_primary_color' => $this->settingGateway->getValue(SettingService::APP_PRIMARY_COLOR_KEY),
-                'api_token_default_ttl_days' => $this->settingGateway->getApiTokenDefaultTtlDays(),
-                'api_token_max_ttl_days' => $this->settingGateway->getApiTokenMaxTtlDays(),
-                'user_inactivity_deactivate_days' => $this->settingGateway->getUserInactivityDeactivateDays(),
-                'user_inactivity_delete_days' => $this->settingGateway->getUserInactivityDeleteDays(),
-                'api_cors_allowed_origins' => $this->settingGateway->getApiCorsAllowedOriginsText(),
-                'system_audit_enabled' => $this->settingGateway->isSystemAuditEnabled(),
-                'system_audit_retention_days' => $this->settingGateway->getSystemAuditRetentionDays(),
-                'microsoft_shared_client_id' => $this->settingGateway->getValue(SettingService::MICROSOFT_SHARED_CLIENT_ID_KEY),
-                'microsoft_authority' => $this->settingGateway->getMicrosoftAuthority(),
-                'smtp_host' => $this->settingGateway->getValue(SettingService::SMTP_HOST_KEY),
-                'smtp_port' => $this->settingGateway->getValue(SettingService::SMTP_PORT_KEY),
-                'smtp_user' => $this->settingGateway->getValue(SettingService::SMTP_USER_KEY),
-                'smtp_secure' => $this->settingGateway->getSmtpSecure(),
-                'smtp_from' => $this->settingGateway->getValue(SettingService::SMTP_FROM_KEY),
-                'smtp_from_name' => $this->settingGateway->getValue(SettingService::SMTP_FROM_NAME_KEY),
+                'default_tenant_id' => $this->settingsDefaultsGateway->getDefaultTenantId(),
+                'default_role_id' => $this->settingsDefaultsGateway->getDefaultRoleId(),
+                'default_department_id' => $this->settingsDefaultsGateway->getDefaultDepartmentId(),
+                'app_title' => $this->settingsMetadataGateway->getValue(SettingKeys::APP_TITLE_KEY),
+                'app_locale' => $this->settingsMetadataGateway->getValue(SettingKeys::APP_LOCALE_KEY),
+                'app_theme' => $this->settingsMetadataGateway->getValue(SettingKeys::APP_THEME_KEY),
+                'app_theme_user' => $this->settingsAppGateway->isUserThemeAllowed(),
+                'app_registration' => $this->settingsAppGateway->isRegistrationEnabled(),
+                'app_primary_color' => $this->settingsMetadataGateway->getValue(SettingKeys::APP_PRIMARY_COLOR_KEY),
+                'api_token_default_ttl_days' => $this->settingsApiPolicyGateway->getApiTokenDefaultTtlDays(),
+                'api_token_max_ttl_days' => $this->settingsApiPolicyGateway->getApiTokenMaxTtlDays(),
+                'user_inactivity_deactivate_days' => $this->settingsUserLifecycleGateway->getUserInactivityDeactivateDays(),
+                'user_inactivity_delete_days' => $this->settingsUserLifecycleGateway->getUserInactivityDeleteDays(),
+                'api_cors_allowed_origins' => $this->settingsApiPolicyGateway->getApiCorsAllowedOriginsText(),
+                'system_audit_enabled' => $this->settingsSystemAuditGateway->isSystemAuditEnabled(),
+                'system_audit_retention_days' => $this->settingsSystemAuditGateway->getSystemAuditRetentionDays(),
+                'frontend_telemetry_enabled' => $this->settingsFrontendTelemetryGateway->isFrontendTelemetryEnabled(),
+                'frontend_telemetry_sample_rate' => $this->settingsFrontendTelemetryGateway->getFrontendTelemetrySampleRate(),
+                'frontend_telemetry_allowed_events' => $this->settingsFrontendTelemetryGateway->getFrontendTelemetryAllowedEvents(),
+                'microsoft_shared_client_id' => $this->settingsMetadataGateway->getValue(SettingKeys::MICROSOFT_SHARED_CLIENT_ID_KEY),
+                'microsoft_authority' => $this->settingsMicrosoftGateway->getMicrosoftAuthority(),
+                'smtp_host' => $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_HOST_KEY),
+                'smtp_port' => $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_PORT_KEY),
+                'smtp_user' => $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_USER_KEY),
+                'smtp_secure' => $this->settingsSmtpGateway->getSmtpSecure(),
+                'smtp_from' => $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_FROM_KEY),
+                'smtp_from_name' => $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_FROM_NAME_KEY),
             ],
             'settings' => [
-                'default_tenant' => $this->settingGateway->get(SettingService::DEFAULT_TENANT_KEY),
-                'default_role' => $this->settingGateway->get(SettingService::DEFAULT_ROLE_KEY),
-                'default_department' => $this->settingGateway->get(SettingService::DEFAULT_DEPARTMENT_KEY),
-                'app_title' => $this->settingGateway->get(SettingService::APP_TITLE_KEY),
-                'app_locale' => $this->settingGateway->get(SettingService::APP_LOCALE_KEY),
-                'app_theme' => $this->settingGateway->get(SettingService::APP_THEME_KEY),
-                'app_theme_user' => $this->settingGateway->get(SettingService::APP_THEME_USER_KEY),
-                'app_registration' => $this->settingGateway->get(SettingService::APP_REGISTRATION_KEY),
-                'app_primary_color' => $this->settingGateway->get(SettingService::APP_PRIMARY_COLOR_KEY),
-                'api_token_default_ttl_days' => $this->settingGateway->get(SettingService::API_TOKEN_DEFAULT_TTL_DAYS_KEY),
-                'api_token_max_ttl_days' => $this->settingGateway->get(SettingService::API_TOKEN_MAX_TTL_DAYS_KEY),
-                'user_inactivity_deactivate_days' => $this->settingGateway->get(SettingService::USER_INACTIVITY_DEACTIVATE_DAYS_KEY),
-                'user_inactivity_delete_days' => $this->settingGateway->get(SettingService::USER_INACTIVITY_DELETE_DAYS_KEY),
-                'api_cors_allowed_origins' => $this->settingGateway->get(SettingService::API_CORS_ALLOWED_ORIGINS_KEY),
-                'system_audit_enabled' => $this->settingGateway->get(SettingService::SYSTEM_AUDIT_ENABLED_KEY),
-                'system_audit_retention_days' => $this->settingGateway->get(SettingService::SYSTEM_AUDIT_RETENTION_DAYS_KEY),
-                'microsoft_shared_client_id' => $this->settingGateway->get(SettingService::MICROSOFT_SHARED_CLIENT_ID_KEY),
-                'microsoft_shared_client_secret_enc' => $this->settingGateway->get(SettingService::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY),
-                'microsoft_authority' => $this->settingGateway->get(SettingService::MICROSOFT_AUTHORITY_KEY),
-                'smtp_host' => $this->settingGateway->get(SettingService::SMTP_HOST_KEY),
-                'smtp_port' => $this->settingGateway->get(SettingService::SMTP_PORT_KEY),
-                'smtp_user' => $this->settingGateway->get(SettingService::SMTP_USER_KEY),
-                'smtp_password' => $this->settingGateway->get(SettingService::SMTP_PASSWORD_KEY),
-                'smtp_secure' => $this->settingGateway->get(SettingService::SMTP_SECURE_KEY),
-                'smtp_from' => $this->settingGateway->get(SettingService::SMTP_FROM_KEY),
-                'smtp_from_name' => $this->settingGateway->get(SettingService::SMTP_FROM_NAME_KEY),
+                'default_tenant' => $this->settingsMetadataGateway->get(SettingKeys::DEFAULT_TENANT_KEY),
+                'default_role' => $this->settingsMetadataGateway->get(SettingKeys::DEFAULT_ROLE_KEY),
+                'default_department' => $this->settingsMetadataGateway->get(SettingKeys::DEFAULT_DEPARTMENT_KEY),
+                'app_title' => $this->settingsMetadataGateway->get(SettingKeys::APP_TITLE_KEY),
+                'app_locale' => $this->settingsMetadataGateway->get(SettingKeys::APP_LOCALE_KEY),
+                'app_theme' => $this->settingsMetadataGateway->get(SettingKeys::APP_THEME_KEY),
+                'app_theme_user' => $this->settingsMetadataGateway->get(SettingKeys::APP_THEME_USER_KEY),
+                'app_registration' => $this->settingsMetadataGateway->get(SettingKeys::APP_REGISTRATION_KEY),
+                'app_primary_color' => $this->settingsMetadataGateway->get(SettingKeys::APP_PRIMARY_COLOR_KEY),
+                'api_token_default_ttl_days' => $this->settingsMetadataGateway->get(SettingKeys::API_TOKEN_DEFAULT_TTL_DAYS_KEY),
+                'api_token_max_ttl_days' => $this->settingsMetadataGateway->get(SettingKeys::API_TOKEN_MAX_TTL_DAYS_KEY),
+                'user_inactivity_deactivate_days' => $this->settingsMetadataGateway->get(SettingKeys::USER_INACTIVITY_DEACTIVATE_DAYS_KEY),
+                'user_inactivity_delete_days' => $this->settingsMetadataGateway->get(SettingKeys::USER_INACTIVITY_DELETE_DAYS_KEY),
+                'api_cors_allowed_origins' => $this->settingsMetadataGateway->get(SettingKeys::API_CORS_ALLOWED_ORIGINS_KEY),
+                'system_audit_enabled' => $this->settingsMetadataGateway->get(SettingKeys::SYSTEM_AUDIT_ENABLED_KEY),
+                'system_audit_retention_days' => $this->settingsMetadataGateway->get(SettingKeys::SYSTEM_AUDIT_RETENTION_DAYS_KEY),
+                'frontend_telemetry_enabled' => $this->settingsMetadataGateway->get(SettingKeys::FRONTEND_TELEMETRY_ENABLED_KEY),
+                'frontend_telemetry_sample_rate' => $this->settingsMetadataGateway->get(SettingKeys::FRONTEND_TELEMETRY_SAMPLE_RATE_KEY),
+                'frontend_telemetry_allowed_events' => $this->settingsMetadataGateway->get(SettingKeys::FRONTEND_TELEMETRY_ALLOWED_EVENTS_KEY),
+                'microsoft_shared_client_id' => $this->settingsMetadataGateway->get(SettingKeys::MICROSOFT_SHARED_CLIENT_ID_KEY),
+                'microsoft_shared_client_secret_enc' => $this->settingsMetadataGateway->get(SettingKeys::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY),
+                'microsoft_authority' => $this->settingsMetadataGateway->get(SettingKeys::MICROSOFT_AUTHORITY_KEY),
+                'smtp_host' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_HOST_KEY),
+                'smtp_port' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_PORT_KEY),
+                'smtp_user' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_USER_KEY),
+                'smtp_password' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_PASSWORD_KEY),
+                'smtp_secure' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_SECURE_KEY),
+                'smtp_from' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_FROM_KEY),
+                'smtp_from_name' => $this->settingsMetadataGateway->get(SettingKeys::SMTP_FROM_NAME_KEY),
             ],
             'active_login_tokens' => $this->rememberTokenRepository->countActive(),
             'active_api_tokens' => $this->apiTokenRepository->countActive(),
@@ -115,6 +129,9 @@ class AdminSettingsService
         $apiCorsAllowedOrigins = $this->normalizeScalarText($post['api_cors_allowed_origins'] ?? '');
         $systemAuditEnabled = isset($post['system_audit_enabled']);
         $systemAuditRetentionDays = (int) ($post['system_audit_retention_days'] ?? 0);
+        $frontendTelemetryEnabled = isset($post['frontend_telemetry_enabled']);
+        $frontendTelemetrySampleRate = $this->normalizeScalarText($post['frontend_telemetry_sample_rate'] ?? '');
+        $frontendTelemetryAllowedEvents = $post['frontend_telemetry_allowed_events'] ?? [];
         $appPrimaryColor = $this->normalizePrimaryColor($post['app_primary_color'] ?? '');
         $smtpHost = trim((string) ($post['smtp_host'] ?? ''));
         $smtpPort = (int) ($post['smtp_port'] ?? 0);
@@ -129,41 +146,44 @@ class AdminSettingsService
 
         $errors = [];
         $beforeAudit = [
-            'default_tenant_id' => $this->settingGateway->getDefaultTenantId(),
-            'default_role_id' => $this->settingGateway->getDefaultRoleId(),
-            'default_department_id' => $this->settingGateway->getDefaultDepartmentId(),
-            'app_locale' => $this->settingGateway->getAppLocale(),
-            'app_theme' => $this->settingGateway->getAppTheme(),
-            'app_theme_user' => $this->settingGateway->isUserThemeAllowed(),
-            'app_registration' => $this->settingGateway->isRegistrationEnabled(),
-            'app_primary_color' => $this->settingGateway->getAppPrimaryColor(),
-            'api_token_default_ttl_days' => $this->settingGateway->getApiTokenDefaultTtlDays(),
-            'api_token_max_ttl_days' => $this->settingGateway->getApiTokenMaxTtlDays(),
-            'user_inactivity_deactivate_days' => $this->settingGateway->getUserInactivityDeactivateDays(),
-            'user_inactivity_delete_days' => $this->settingGateway->getUserInactivityDeleteDays(),
-            'system_audit_enabled' => $this->settingGateway->isSystemAuditEnabled(),
-            'system_audit_retention_days' => $this->settingGateway->getSystemAuditRetentionDays(),
+            'default_tenant_id' => $this->settingsDefaultsGateway->getDefaultTenantId(),
+            'default_role_id' => $this->settingsDefaultsGateway->getDefaultRoleId(),
+            'default_department_id' => $this->settingsDefaultsGateway->getDefaultDepartmentId(),
+            'app_locale' => $this->settingsAppGateway->getAppLocale(),
+            'app_theme' => $this->settingsAppGateway->getAppTheme(),
+            'app_theme_user' => $this->settingsAppGateway->isUserThemeAllowed(),
+            'app_registration' => $this->settingsAppGateway->isRegistrationEnabled(),
+            'app_primary_color' => $this->settingsAppGateway->getAppPrimaryColor(),
+            'api_token_default_ttl_days' => $this->settingsApiPolicyGateway->getApiTokenDefaultTtlDays(),
+            'api_token_max_ttl_days' => $this->settingsApiPolicyGateway->getApiTokenMaxTtlDays(),
+            'user_inactivity_deactivate_days' => $this->settingsUserLifecycleGateway->getUserInactivityDeactivateDays(),
+            'user_inactivity_delete_days' => $this->settingsUserLifecycleGateway->getUserInactivityDeleteDays(),
+            'system_audit_enabled' => $this->settingsSystemAuditGateway->isSystemAuditEnabled(),
+            'system_audit_retention_days' => $this->settingsSystemAuditGateway->getSystemAuditRetentionDays(),
+            'frontend_telemetry_enabled' => $this->settingsFrontendTelemetryGateway->isFrontendTelemetryEnabled(),
+            'frontend_telemetry_sample_rate' => $this->settingsFrontendTelemetryGateway->getFrontendTelemetrySampleRate(),
+            'frontend_telemetry_allowed_events' => $this->settingsFrontendTelemetryGateway->getFrontendTelemetryAllowedEvents(),
         ];
 
-        $this->settingGateway->setDefaultTenantId($defaultTenantId > 0 ? $defaultTenantId : null);
-        $this->settingGateway->setDefaultRoleId($defaultRoleId > 0 ? $defaultRoleId : null);
-        $this->settingGateway->setDefaultDepartmentId($defaultDepartmentId > 0 ? $defaultDepartmentId : null);
-        $this->settingGateway->setAppTitle($appTitle);
-        $this->settingGateway->setAppLocale($appLocale);
-        $this->settingGateway->setAppTheme($appTheme);
-        $this->settingGateway->setUserThemeAllowed($appThemeUser);
-        $this->settingGateway->setRegistrationEnabled($appRegistration);
+        $this->settingsDefaultsGateway->setDefaultTenantId($defaultTenantId > 0 ? $defaultTenantId : null);
+        $this->settingsDefaultsGateway->setDefaultRoleId($defaultRoleId > 0 ? $defaultRoleId : null);
+        $this->settingsDefaultsGateway->setDefaultDepartmentId($defaultDepartmentId > 0 ? $defaultDepartmentId : null);
+        $this->settingsAppGateway->setAppTitle($appTitle);
+        $this->settingsAppGateway->setAppLocale($appLocale);
+        $this->settingsAppGateway->setAppTheme($appTheme);
+        $this->settingsAppGateway->setUserThemeAllowed($appThemeUser);
+        $this->settingsAppGateway->setRegistrationEnabled($appRegistration);
 
-        $apiTokenMaxTtlOk = $this->settingGateway->setApiTokenMaxTtlDays($apiTokenMaxTtlDays > 0 ? $apiTokenMaxTtlDays : null);
+        $apiTokenMaxTtlOk = $this->settingsApiPolicyGateway->setApiTokenMaxTtlDays($apiTokenMaxTtlDays > 0 ? $apiTokenMaxTtlDays : null);
         if (!$apiTokenMaxTtlOk) {
             $errors[] = ['message' => 'API token max lifetime is invalid', 'key' => 'api_token_max_ttl_invalid'];
         }
-        $apiTokenTtlOk = $this->settingGateway->setApiTokenDefaultTtlDays($apiTokenDefaultTtlDays > 0 ? $apiTokenDefaultTtlDays : null);
+        $apiTokenTtlOk = $this->settingsApiPolicyGateway->setApiTokenDefaultTtlDays($apiTokenDefaultTtlDays > 0 ? $apiTokenDefaultTtlDays : null);
         if (!$apiTokenTtlOk) {
             $errors[] = ['message' => 'API token default lifetime is invalid', 'key' => 'api_token_default_ttl_invalid'];
         }
 
-        $userDeactivateOk = $this->settingGateway->setUserInactivityDeactivateDays($userInactivityDeactivateDays);
+        $userDeactivateOk = $this->settingsUserLifecycleGateway->setUserInactivityDeactivateDays($userInactivityDeactivateDays);
         if (!$userDeactivateOk) {
             $errors[] = [
                 'message' => 'User inactivity deactivation period is invalid',
@@ -172,7 +192,7 @@ class AdminSettingsService
         }
 
         if ($userInactivityDeactivateDays > 0) {
-            $userDeleteOk = $this->settingGateway->setUserInactivityDeleteDays($userInactivityDeleteDays);
+            $userDeleteOk = $this->settingsUserLifecycleGateway->setUserInactivityDeleteDays($userInactivityDeleteDays);
             if (!$userDeleteOk) {
                 $errors[] = [
                     'message' => 'User inactivity deletion period is invalid',
@@ -186,56 +206,76 @@ class AdminSettingsService
                     'key' => 'user_inactivity_delete_requires_deactivate',
                 ];
             }
-            $this->settingGateway->setUserInactivityDeleteDays(0);
+            $this->settingsUserLifecycleGateway->setUserInactivityDeleteDays(0);
         }
 
-        $apiCorsOriginsOk = $this->settingGateway->setApiCorsAllowedOrigins($apiCorsAllowedOrigins);
+        $apiCorsOriginsOk = $this->settingsApiPolicyGateway->setApiCorsAllowedOrigins($apiCorsAllowedOrigins);
         if (!$apiCorsOriginsOk) {
             $errors[] = ['message' => 'CORS allowed origins are invalid', 'key' => 'api_cors_allowed_origins_invalid'];
         }
 
-        $systemAuditEnabledOk = $this->settingGateway->setSystemAuditEnabled($systemAuditEnabled);
+        $systemAuditEnabledOk = $this->settingsSystemAuditGateway->setSystemAuditEnabled($systemAuditEnabled);
         if (!$systemAuditEnabledOk) {
             $errors[] = ['message' => 'System audit setting is invalid', 'key' => 'system_audit_enabled_invalid'];
         }
 
-        $systemAuditRetentionOk = $this->settingGateway->setSystemAuditRetentionDays(
+        $systemAuditRetentionOk = $this->settingsSystemAuditGateway->setSystemAuditRetentionDays(
             $systemAuditRetentionDays > 0 ? $systemAuditRetentionDays : null
         );
         if (!$systemAuditRetentionOk) {
             $errors[] = ['message' => 'System audit retention is invalid', 'key' => 'system_audit_retention_invalid'];
         }
 
-        $primaryOk = $this->settingGateway->setAppPrimaryColor($appPrimaryColor);
+        $frontendTelemetryEnabledOk = $this->settingsFrontendTelemetryGateway->setFrontendTelemetryEnabled($frontendTelemetryEnabled);
+        if (!$frontendTelemetryEnabledOk) {
+            $errors[] = ['message' => 'Frontend telemetry enabled setting is invalid', 'key' => 'frontend_telemetry_enabled_invalid'];
+        }
+
+        $frontendTelemetryRateValue = null;
+        if ($frontendTelemetrySampleRate !== '') {
+            $frontendTelemetryRateValue = is_numeric($frontendTelemetrySampleRate)
+                ? (float) $frontendTelemetrySampleRate
+                : NAN;
+        }
+        $frontendTelemetrySampleRateOk = $this->settingsFrontendTelemetryGateway->setFrontendTelemetrySampleRate($frontendTelemetryRateValue);
+        if (!$frontendTelemetrySampleRateOk) {
+            $errors[] = ['message' => 'Frontend telemetry sample rate is invalid', 'key' => 'frontend_telemetry_sample_rate_invalid'];
+        }
+
+        $frontendTelemetryAllowedEventsOk = $this->settingsFrontendTelemetryGateway->setFrontendTelemetryAllowedEvents($frontendTelemetryAllowedEvents);
+        if (!$frontendTelemetryAllowedEventsOk) {
+            $errors[] = ['message' => 'Frontend telemetry allowed events are invalid', 'key' => 'frontend_telemetry_allowed_events_invalid'];
+        }
+
+        $primaryOk = $this->settingsAppGateway->setAppPrimaryColor($appPrimaryColor);
         if (!$primaryOk) {
             $appPrimaryColor = '';
             $errors[] = ['message' => 'Primary color is invalid', 'key' => 'app_primary_invalid'];
         }
 
-        $this->settingGateway->setSmtpHost($smtpHost);
-        $this->settingGateway->setSmtpPort($smtpPort > 0 ? $smtpPort : null);
-        $this->settingGateway->setSmtpUser($smtpUser);
+        $this->settingsSmtpGateway->setSmtpHost($smtpHost);
+        $this->settingsSmtpGateway->setSmtpPort($smtpPort > 0 ? $smtpPort : null);
+        $this->settingsSmtpGateway->setSmtpUser($smtpUser);
         if (trim($smtpPassword) !== '') {
-            $this->settingGateway->setSmtpPassword($smtpPassword);
+            $this->settingsSmtpGateway->setSmtpPassword($smtpPassword);
         }
-        $this->settingGateway->setSmtpSecure($smtpSecure);
-        $this->settingGateway->setSmtpFrom($smtpFrom);
-        $this->settingGateway->setSmtpFromName($smtpFromName);
+        $this->settingsSmtpGateway->setSmtpSecure($smtpSecure);
+        $this->settingsSmtpGateway->setSmtpFrom($smtpFrom);
+        $this->settingsSmtpGateway->setSmtpFromName($smtpFromName);
 
-        $msClientIdOk = $this->settingGateway->setMicrosoftSharedClientId($microsoftSharedClientId);
+        $msClientIdOk = $this->settingsMicrosoftGateway->setMicrosoftSharedClientId($microsoftSharedClientId);
         if (!$msClientIdOk) {
             $errors[] = ['message' => 'Microsoft client ID is invalid', 'key' => 'microsoft_client_id_invalid'];
         }
 
-        $msAuthorityOk = $this->settingGateway->setMicrosoftAuthority($microsoftAuthority);
+        $msAuthorityOk = $this->settingsMicrosoftGateway->setMicrosoftAuthority($microsoftAuthority);
         if (!$msAuthorityOk) {
             $errors[] = ['message' => 'Microsoft authority is invalid', 'key' => 'microsoft_authority_invalid'];
         }
 
         if (trim($microsoftSharedClientSecret) !== '') {
-            try {
-                $this->settingGateway->setMicrosoftSharedClientSecret($microsoftSharedClientSecret);
-            } catch (\Throwable) {
+            $msSecretOk = $this->settingsMicrosoftGateway->setMicrosoftSharedClientSecret($microsoftSharedClientSecret);
+            if (!$msSecretOk) {
                 $errors[] = [
                     'message' => 'Microsoft client secret could not be encrypted',
                     'key' => 'microsoft_client_secret_invalid',
@@ -250,26 +290,32 @@ class AdminSettingsService
             'app_theme_user' => $appThemeUser ? '1' : '0',
             'app_registration' => $appRegistration ? '1' : '0',
             'app_primary_color' => $appPrimaryColor !== '' ? $appPrimaryColor : null,
-            'api_token_default_ttl_days' => (string) $this->settingGateway->getApiTokenDefaultTtlDays(),
-            'api_token_max_ttl_days' => (string) $this->settingGateway->getApiTokenMaxTtlDays(),
-            'api_cors_allowed_origins' => $this->settingGateway->getValue(SettingService::API_CORS_ALLOWED_ORIGINS_KEY),
+            'api_token_default_ttl_days' => (string) $this->settingsApiPolicyGateway->getApiTokenDefaultTtlDays(),
+            'api_token_max_ttl_days' => (string) $this->settingsApiPolicyGateway->getApiTokenMaxTtlDays(),
+            'api_cors_allowed_origins' => $this->settingsMetadataGateway->getValue(SettingKeys::API_CORS_ALLOWED_ORIGINS_KEY),
+            'frontend_telemetry_enabled' => $this->settingsFrontendTelemetryGateway->isFrontendTelemetryEnabled() ? '1' : '0',
+            'frontend_telemetry_sample_rate' => (string) $this->settingsFrontendTelemetryGateway->getFrontendTelemetrySampleRate(),
+            'frontend_telemetry_allowed_events' => implode(',', $this->settingsFrontendTelemetryGateway->getFrontendTelemetryAllowedEvents()),
         ]);
 
         $afterAudit = [
-            'default_tenant_id' => $this->settingGateway->getDefaultTenantId(),
-            'default_role_id' => $this->settingGateway->getDefaultRoleId(),
-            'default_department_id' => $this->settingGateway->getDefaultDepartmentId(),
-            'app_locale' => $this->settingGateway->getAppLocale(),
-            'app_theme' => $this->settingGateway->getAppTheme(),
-            'app_theme_user' => $this->settingGateway->isUserThemeAllowed(),
-            'app_registration' => $this->settingGateway->isRegistrationEnabled(),
-            'app_primary_color' => $this->settingGateway->getAppPrimaryColor(),
-            'api_token_default_ttl_days' => $this->settingGateway->getApiTokenDefaultTtlDays(),
-            'api_token_max_ttl_days' => $this->settingGateway->getApiTokenMaxTtlDays(),
-            'user_inactivity_deactivate_days' => $this->settingGateway->getUserInactivityDeactivateDays(),
-            'user_inactivity_delete_days' => $this->settingGateway->getUserInactivityDeleteDays(),
-            'system_audit_enabled' => $this->settingGateway->isSystemAuditEnabled(),
-            'system_audit_retention_days' => $this->settingGateway->getSystemAuditRetentionDays(),
+            'default_tenant_id' => $this->settingsDefaultsGateway->getDefaultTenantId(),
+            'default_role_id' => $this->settingsDefaultsGateway->getDefaultRoleId(),
+            'default_department_id' => $this->settingsDefaultsGateway->getDefaultDepartmentId(),
+            'app_locale' => $this->settingsAppGateway->getAppLocale(),
+            'app_theme' => $this->settingsAppGateway->getAppTheme(),
+            'app_theme_user' => $this->settingsAppGateway->isUserThemeAllowed(),
+            'app_registration' => $this->settingsAppGateway->isRegistrationEnabled(),
+            'app_primary_color' => $this->settingsAppGateway->getAppPrimaryColor(),
+            'api_token_default_ttl_days' => $this->settingsApiPolicyGateway->getApiTokenDefaultTtlDays(),
+            'api_token_max_ttl_days' => $this->settingsApiPolicyGateway->getApiTokenMaxTtlDays(),
+            'user_inactivity_deactivate_days' => $this->settingsUserLifecycleGateway->getUserInactivityDeactivateDays(),
+            'user_inactivity_delete_days' => $this->settingsUserLifecycleGateway->getUserInactivityDeleteDays(),
+            'system_audit_enabled' => $this->settingsSystemAuditGateway->isSystemAuditEnabled(),
+            'system_audit_retention_days' => $this->settingsSystemAuditGateway->getSystemAuditRetentionDays(),
+            'frontend_telemetry_enabled' => $this->settingsFrontendTelemetryGateway->isFrontendTelemetryEnabled(),
+            'frontend_telemetry_sample_rate' => $this->settingsFrontendTelemetryGateway->getFrontendTelemetrySampleRate(),
+            'frontend_telemetry_allowed_events' => $this->settingsFrontendTelemetryGateway->getFrontendTelemetryAllowedEvents(),
         ];
 
         $outcome = $errors === [] ? 'success' : 'failed';
diff --git a/lib/Service/Settings/SettingCacheService.php b/lib/Service/Settings/SettingCacheService.php
index 90b74cf..51ad23b 100644
--- a/lib/Service/Settings/SettingCacheService.php
+++ b/lib/Service/Settings/SettingCacheService.php
@@ -61,11 +61,14 @@ class SettingCacheService
             return false;
         }
 
+        // Write to a temp file first, then rename — rename is atomic on most filesystems,
+        // so readers never see a half-written file. LOCK_EX prevents concurrent write corruption.
         $tmp = tempnam($dir, 'settings_');
         if ($tmp === false) {
             return false;
         }
 
+        // PHP include returns an array — loaded by OPcache on subsequent requests, much faster than DB.
         $payload = "<?php\nreturn " . $this->exportValue($settings) . ";\n";
         $written = @file_put_contents($tmp, $payload, LOCK_EX);
         if ($written === false) {
diff --git a/lib/Service/Settings/SettingGateway.php b/lib/Service/Settings/SettingGateway.php
deleted file mode 100644
index a18ca2a..0000000
--- a/lib/Service/Settings/SettingGateway.php
+++ /dev/null
@@ -1,285 +0,0 @@
-<?php
-
-namespace MintyPHP\Service\Settings;
-
-class SettingGateway
-{
-    public function __construct(private readonly SettingService $settingService)
-    {
-    }
-
-    public function get(string $key): ?array
-    {
-        return $this->settingService->get($key);
-    }
-
-    public function getValue(string $key): ?string
-    {
-        return $this->settingService->getValue($key);
-    }
-
-    public function getDefaultTenantId(): ?int
-    {
-        return $this->settingService->getDefaultTenantId();
-    }
-
-    public function setDefaultTenantId(?int $tenantId, ?string $description = null): bool
-    {
-        return $this->settingService->setDefaultTenantId($tenantId, $description);
-    }
-
-    public function getDefaultRoleId(): ?int
-    {
-        return $this->settingService->getDefaultRoleId();
-    }
-
-    public function setDefaultRoleId(?int $roleId, ?string $description = null): bool
-    {
-        return $this->settingService->setDefaultRoleId($roleId, $description);
-    }
-
-    public function getDefaultDepartmentId(): ?int
-    {
-        return $this->settingService->getDefaultDepartmentId();
-    }
-
-    public function setDefaultDepartmentId(?int $departmentId, ?string $description = null): bool
-    {
-        return $this->settingService->setDefaultDepartmentId($departmentId, $description);
-    }
-
-    public function getAppTitle(): ?string
-    {
-        return $this->settingService->getAppTitle();
-    }
-
-    public function setAppTitle(?string $title, ?string $description = null): bool
-    {
-        return $this->settingService->setAppTitle($title, $description);
-    }
-
-    public function getAppLocale(): ?string
-    {
-        return $this->settingService->getAppLocale();
-    }
-
-    public function setAppLocale(?string $locale, ?string $description = null): bool
-    {
-        return $this->settingService->setAppLocale($locale, $description);
-    }
-
-    public function getAppTheme(): ?string
-    {
-        return $this->settingService->getAppTheme();
-    }
-
-    public function setAppTheme(?string $theme, ?string $description = null): bool
-    {
-        return $this->settingService->setAppTheme($theme, $description);
-    }
-
-    public function isUserThemeAllowed(): bool
-    {
-        return $this->settingService->isUserThemeAllowed();
-    }
-
-    public function setUserThemeAllowed(bool $allowed, ?string $description = null): bool
-    {
-        return $this->settingService->setUserThemeAllowed($allowed, $description);
-    }
-
-    public function isRegistrationEnabled(): bool
-    {
-        return $this->settingService->isRegistrationEnabled();
-    }
-
-    public function setRegistrationEnabled(bool $allowed, ?string $description = null): bool
-    {
-        return $this->settingService->setRegistrationEnabled($allowed, $description);
-    }
-
-    public function getApiTokenDefaultTtlDays(): int
-    {
-        return $this->settingService->getApiTokenDefaultTtlDays();
-    }
-
-    public function setApiTokenDefaultTtlDays(?int $days, ?string $description = null): bool
-    {
-        return $this->settingService->setApiTokenDefaultTtlDays($days, $description);
-    }
-
-    public function getApiTokenMaxTtlDays(): int
-    {
-        return $this->settingService->getApiTokenMaxTtlDays();
-    }
-
-    public function setApiTokenMaxTtlDays(?int $days, ?string $description = null): bool
-    {
-        return $this->settingService->setApiTokenMaxTtlDays($days, $description);
-    }
-
-    public function getUserInactivityDeactivateDays(): int
-    {
-        return $this->settingService->getUserInactivityDeactivateDays();
-    }
-
-    public function setUserInactivityDeactivateDays(?int $days, ?string $description = null): bool
-    {
-        return $this->settingService->setUserInactivityDeactivateDays($days, $description);
-    }
-
-    public function getUserInactivityDeleteDays(): int
-    {
-        return $this->settingService->getUserInactivityDeleteDays();
-    }
-
-    public function setUserInactivityDeleteDays(?int $days, ?string $description = null): bool
-    {
-        return $this->settingService->setUserInactivityDeleteDays($days, $description);
-    }
-
-    public function isSystemAuditEnabled(): bool
-    {
-        return $this->settingService->isSystemAuditEnabled();
-    }
-
-    public function setSystemAuditEnabled(bool $enabled, ?string $description = null): bool
-    {
-        return $this->settingService->setSystemAuditEnabled($enabled, $description);
-    }
-
-    public function getSystemAuditRetentionDays(): int
-    {
-        return $this->settingService->getSystemAuditRetentionDays();
-    }
-
-    public function setSystemAuditRetentionDays(?int $days, ?string $description = null): bool
-    {
-        return $this->settingService->setSystemAuditRetentionDays($days, $description);
-    }
-
-    public function getApiCorsAllowedOrigins(): array
-    {
-        return $this->settingService->getApiCorsAllowedOrigins();
-    }
-
-    public function getApiCorsAllowedOriginsText(): string
-    {
-        return $this->settingService->getApiCorsAllowedOriginsText();
-    }
-
-    public function setApiCorsAllowedOrigins(?string $rawOrigins, ?string $description = null): bool
-    {
-        return $this->settingService->setApiCorsAllowedOrigins($rawOrigins, $description);
-    }
-
-    public function getMicrosoftSharedClientId(): ?string
-    {
-        return $this->settingService->getMicrosoftSharedClientId();
-    }
-
-    public function setMicrosoftSharedClientId(?string $clientId, ?string $description = null): bool
-    {
-        return $this->settingService->setMicrosoftSharedClientId($clientId, $description);
-    }
-
-    public function getMicrosoftSharedClientSecret(): ?string
-    {
-        return $this->settingService->getMicrosoftSharedClientSecret();
-    }
-
-    public function setMicrosoftSharedClientSecret(?string $secret, ?string $description = null): bool
-    {
-        return $this->settingService->setMicrosoftSharedClientSecret($secret, $description);
-    }
-
-    public function getMicrosoftAuthority(): string
-    {
-        return $this->settingService->getMicrosoftAuthority();
-    }
-
-    public function setMicrosoftAuthority(?string $authority, ?string $description = null): bool
-    {
-        return $this->settingService->setMicrosoftAuthority($authority, $description);
-    }
-
-    public function getAppPrimaryColor(): ?string
-    {
-        return $this->settingService->getAppPrimaryColor();
-    }
-
-    public function setAppPrimaryColor(?string $color, ?string $description = null): bool
-    {
-        return $this->settingService->setAppPrimaryColor($color, $description);
-    }
-
-    public function getSmtpHost(): ?string
-    {
-        return $this->settingService->getSmtpHost();
-    }
-
-    public function setSmtpHost(?string $host, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpHost($host, $description);
-    }
-
-    public function getSmtpPort(): ?int
-    {
-        return $this->settingService->getSmtpPort();
-    }
-
-    public function setSmtpPort(?int $port, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpPort($port, $description);
-    }
-
-    public function getSmtpUser(): ?string
-    {
-        return $this->settingService->getSmtpUser();
-    }
-
-    public function setSmtpUser(?string $user, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpUser($user, $description);
-    }
-
-    public function getSmtpPassword(): ?string
-    {
-        return $this->settingService->getSmtpPassword();
-    }
-
-    public function setSmtpPassword(?string $password, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpPassword($password, $description);
-    }
-
-    public function getSmtpSecure(): ?string
-    {
-        return $this->settingService->getSmtpSecure();
-    }
-
-    public function setSmtpSecure(?string $secure, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpSecure($secure, $description);
-    }
-
-    public function getSmtpFrom(): ?string
-    {
-        return $this->settingService->getSmtpFrom();
-    }
-
-    public function setSmtpFrom(?string $from, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpFrom($from, $description);
-    }
-
-    public function getSmtpFromName(): ?string
-    {
-        return $this->settingService->getSmtpFromName();
-    }
-
-    public function setSmtpFromName(?string $fromName, ?string $description = null): bool
-    {
-        return $this->settingService->setSmtpFromName($fromName, $description);
-    }
-}
diff --git a/lib/Service/Settings/SettingKeys.php b/lib/Service/Settings/SettingKeys.php
new file mode 100644
index 0000000..526f4d8
--- /dev/null
+++ b/lib/Service/Settings/SettingKeys.php
@@ -0,0 +1,40 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+final class SettingKeys
+{
+    public const DEFAULT_TENANT_KEY = 'default_tenant_id';
+    public const DEFAULT_ROLE_KEY = 'default_role_id';
+    public const DEFAULT_DEPARTMENT_KEY = 'default_department_id';
+    public const APP_TITLE_KEY = 'app_title';
+    public const APP_LOCALE_KEY = 'app_locale';
+    public const APP_THEME_KEY = 'app_theme';
+    public const APP_THEME_USER_KEY = 'app_theme_user';
+    public const APP_REGISTRATION_KEY = 'app_registration';
+    public const APP_PRIMARY_COLOR_KEY = 'app_primary_color';
+    public const API_TOKEN_DEFAULT_TTL_DAYS_KEY = 'api_token_default_ttl_days';
+    public const API_TOKEN_MAX_TTL_DAYS_KEY = 'api_token_max_ttl_days';
+    public const API_CORS_ALLOWED_ORIGINS_KEY = 'api_cors_allowed_origins';
+    public const MICROSOFT_SHARED_CLIENT_ID_KEY = 'microsoft_shared_client_id';
+    public const MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY = 'microsoft_shared_client_secret_enc';
+    public const MICROSOFT_AUTHORITY_KEY = 'microsoft_authority';
+    public const SMTP_HOST_KEY = 'smtp_host';
+    public const SMTP_PORT_KEY = 'smtp_port';
+    public const SMTP_USER_KEY = 'smtp_user';
+    public const SMTP_PASSWORD_KEY = 'smtp_password';
+    public const SMTP_SECURE_KEY = 'smtp_secure';
+    public const SMTP_FROM_KEY = 'smtp_from';
+    public const SMTP_FROM_NAME_KEY = 'smtp_from_name';
+    public const USER_INACTIVITY_DEACTIVATE_DAYS_KEY = 'user_inactivity_deactivate_days';
+    public const USER_INACTIVITY_DELETE_DAYS_KEY = 'user_inactivity_delete_days';
+    public const SYSTEM_AUDIT_ENABLED_KEY = 'system_audit_enabled';
+    public const SYSTEM_AUDIT_RETENTION_DAYS_KEY = 'system_audit_retention_days';
+    public const FRONTEND_TELEMETRY_ENABLED_KEY = 'frontend_telemetry_enabled';
+    public const FRONTEND_TELEMETRY_SAMPLE_RATE_KEY = 'frontend_telemetry_sample_rate';
+    public const FRONTEND_TELEMETRY_ALLOWED_EVENTS_KEY = 'frontend_telemetry_allowed_events';
+
+    private function __construct()
+    {
+    }
+}
diff --git a/lib/Service/Settings/SettingService.php b/lib/Service/Settings/SettingService.php
deleted file mode 100644
index f20124c..0000000
--- a/lib/Service/Settings/SettingService.php
+++ /dev/null
@@ -1,720 +0,0 @@
-<?php
-
-namespace MintyPHP\Service\Settings;
-
-use MintyPHP\Repository\Access\RoleRepositoryInterface;
-use MintyPHP\Repository\Org\DepartmentRepositoryInterface;
-use MintyPHP\Repository\Settings\SettingRepositoryInterface;
-use MintyPHP\Repository\Tenant\TenantRepositoryInterface;
-use MintyPHP\Support\Crypto;
-
-class SettingService
-{
-    public function __construct(
-        private readonly SettingRepositoryInterface $settingRepository,
-        private readonly TenantRepositoryInterface $tenantRepository,
-        private readonly RoleRepositoryInterface $roleRepository,
-        private readonly DepartmentRepositoryInterface $departmentRepository,
-        private readonly ThemeConfigService $themeConfigService
-    ) {
-    }
-    public const DEFAULT_TENANT_KEY = 'default_tenant_id';
-    public const DEFAULT_ROLE_KEY = 'default_role_id';
-    public const DEFAULT_DEPARTMENT_KEY = 'default_department_id';
-    public const APP_TITLE_KEY = 'app_title';
-    public const APP_LOCALE_KEY = 'app_locale';
-    public const APP_THEME_KEY = 'app_theme';
-    public const APP_THEME_USER_KEY = 'app_theme_user';
-    public const APP_REGISTRATION_KEY = 'app_registration';
-    public const APP_PRIMARY_COLOR_KEY = 'app_primary_color';
-    public const API_TOKEN_DEFAULT_TTL_DAYS_KEY = 'api_token_default_ttl_days';
-    public const API_TOKEN_MAX_TTL_DAYS_KEY = 'api_token_max_ttl_days';
-    public const API_CORS_ALLOWED_ORIGINS_KEY = 'api_cors_allowed_origins';
-    public const MICROSOFT_SHARED_CLIENT_ID_KEY = 'microsoft_shared_client_id';
-    public const MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY = 'microsoft_shared_client_secret_enc';
-    public const MICROSOFT_AUTHORITY_KEY = 'microsoft_authority';
-    public const SMTP_HOST_KEY = 'smtp_host';
-    public const SMTP_PORT_KEY = 'smtp_port';
-    public const SMTP_USER_KEY = 'smtp_user';
-    public const SMTP_PASSWORD_KEY = 'smtp_password';
-    public const SMTP_SECURE_KEY = 'smtp_secure';
-    public const SMTP_FROM_KEY = 'smtp_from';
-    public const SMTP_FROM_NAME_KEY = 'smtp_from_name';
-    public const USER_INACTIVITY_DEACTIVATE_DAYS_KEY = 'user_inactivity_deactivate_days';
-    public const USER_INACTIVITY_DELETE_DAYS_KEY = 'user_inactivity_delete_days';
-    public const SYSTEM_AUDIT_ENABLED_KEY = 'system_audit_enabled';
-    public const SYSTEM_AUDIT_RETENTION_DAYS_KEY = 'system_audit_retention_days';
-    private const API_TOKEN_DEFAULT_TTL_DAYS_FALLBACK = 90;
-    private const API_TOKEN_MAX_TTL_DAYS_FALLBACK = 365;
-    private const API_TOKEN_TTL_DAYS_MIN = 1;
-    private const API_TOKEN_TTL_DAYS_HARD_MAX = 3650;
-    private const USER_INACTIVITY_DEACTIVATE_DAYS_FALLBACK = 180;
-    private const USER_INACTIVITY_DELETE_DAYS_FALLBACK = 365;
-    private const USER_INACTIVITY_DAYS_MIN = 0;
-    private const USER_INACTIVITY_DAYS_MAX = 3650;
-    private const SYSTEM_AUDIT_ENABLED_FALLBACK = true;
-    private const SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK = 365;
-    private const SYSTEM_AUDIT_RETENTION_DAYS_MIN = 30;
-    private const SYSTEM_AUDIT_RETENTION_DAYS_MAX = 1095;
-
-    public function get(string $key): ?array
-    {
-        return $this->settingRepository->find($key);
-    }
-
-    public function getValue(string $key): ?string
-    {
-        return $this->settingRepository->getValue($key);
-    }
-
-    public function getInt(string $key): ?int
-    {
-        $value = $this->settingRepository->getValue($key);
-        if ($value === null || $value === '') {
-            return null;
-        }
-        return (int) $value;
-    }
-
-    public function set(string $key, ?string $value, ?string $description = null): bool
-    {
-        return $this->settingRepository->set($key, $value, $description);
-    }
-
-    public function getDefaultTenantId(): ?int
-    {
-        $id = $this->getInt(self::DEFAULT_TENANT_KEY);
-        return $id && $id > 0 ? $id : null;
-    }
-
-    public function setDefaultTenantId(?int $tenantId, ?string $description = null): bool
-    {
-        $value = $tenantId && $tenantId > 0 ? (string) $tenantId : null;
-        if ($value !== null) {
-            $exists = $this->tenantRepository->find($tenantId);
-            if (!$exists) {
-                return false;
-            }
-        }
-        $desc = $description ?? 'setting.default_tenant';
-        return $this->settingRepository->set(self::DEFAULT_TENANT_KEY, $value, $desc);
-    }
-
-    public function getDefaultRoleId(): ?int
-    {
-        $id = $this->getInt(self::DEFAULT_ROLE_KEY);
-        return $id && $id > 0 ? $id : null;
-    }
-
-    public function setDefaultRoleId(?int $roleId, ?string $description = null): bool
-    {
-        $value = $roleId && $roleId > 0 ? (string) $roleId : null;
-        if ($value !== null) {
-            $exists = $this->roleRepository->find($roleId);
-            if (!$exists) {
-                return false;
-            }
-        }
-        $desc = $description ?? 'setting.default_role';
-        return $this->settingRepository->set(self::DEFAULT_ROLE_KEY, $value, $desc);
-    }
-
-    public function getDefaultDepartmentId(): ?int
-    {
-        $id = $this->getInt(self::DEFAULT_DEPARTMENT_KEY);
-        return $id && $id > 0 ? $id : null;
-    }
-
-    public function setDefaultDepartmentId(?int $departmentId, ?string $description = null): bool
-    {
-        $value = $departmentId && $departmentId > 0 ? (string) $departmentId : null;
-        if ($value !== null) {
-            $exists = $this->departmentRepository->find($departmentId);
-            if (!$exists) {
-                return false;
-            }
-        }
-        $desc = $description ?? 'setting.default_department';
-        return $this->settingRepository->set(self::DEFAULT_DEPARTMENT_KEY, $value, $desc);
-    }
-
-    public function getAppTitle(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::APP_TITLE_KEY);
-        $value = $value !== null ? trim($value) : null;
-        return $value !== '' ? $value : null;
-    }
-
-    public function setAppTitle(?string $title, ?string $description = null): bool
-    {
-        $value = $title !== null ? trim($title) : null;
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.app_title';
-        return $this->settingRepository->set(self::APP_TITLE_KEY, $value, $desc);
-    }
-
-    public function getAppLocale(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::APP_LOCALE_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setAppLocale(?string $locale, ?string $description = null): bool
-    {
-        $value = $locale !== null ? trim((string) $locale) : '';
-        if ($value === '') {
-            $value = null;
-        } else {
-            $allowed = defined('APP_LOCALES') ? APP_LOCALES : [];
-            if ($allowed && !in_array($value, $allowed, true)) {
-                return false;
-            }
-        }
-        $desc = $description ?? 'setting.app_locale';
-        return $this->settingRepository->set(self::APP_LOCALE_KEY, $value, $desc);
-    }
-
-    public function getAppTheme(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::APP_THEME_KEY);
-        $value = $value !== null ? strtolower(trim((string) $value)) : '';
-        if (!in_array($value, $this->allowedThemes(), true)) {
-            return null;
-        }
-        return $value;
-    }
-
-    public function setAppTheme(?string $theme, ?string $description = null): bool
-    {
-        $value = $theme !== null ? strtolower(trim((string) $theme)) : '';
-        if ($value === '' || !in_array($value, $this->allowedThemes(), true)) {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.app_theme';
-        return $this->settingRepository->set(self::APP_THEME_KEY, $value, $desc);
-    }
-
-    public function isUserThemeAllowed(): bool
-    {
-        $value = $this->settingRepository->getValue(self::APP_THEME_USER_KEY);
-        if ($value === null || $value === '') {
-            return true;
-        }
-        return in_array(strtolower($value), ['1', 'true', 'yes', 'on'], true);
-    }
-
-    public function setUserThemeAllowed(bool $allowed, ?string $description = null): bool
-    {
-        $value = $allowed ? '1' : '0';
-        $desc = $description ?? 'setting.app_theme_user';
-        return $this->settingRepository->set(self::APP_THEME_USER_KEY, $value, $desc);
-    }
-
-    private function allowedThemes(): array
-    {
-        return array_keys($this->themeConfigService->all());
-    }
-
-    public function isRegistrationEnabled(): bool
-    {
-        $value = $this->settingRepository->getValue(self::APP_REGISTRATION_KEY);
-        if ($value === null || $value === '') {
-            return true;
-        }
-        return in_array(strtolower($value), ['1', 'true', 'yes', 'on'], true);
-    }
-
-    public function setRegistrationEnabled(bool $allowed, ?string $description = null): bool
-    {
-        $value = $allowed ? '1' : '0';
-        $desc = $description ?? 'setting.app_registration';
-        return $this->settingRepository->set(self::APP_REGISTRATION_KEY, $value, $desc);
-    }
-
-    public function getApiTokenDefaultTtlDays(): int
-    {
-        $maxDays = $this->getApiTokenMaxTtlDays();
-        $value = $this->getInt(self::API_TOKEN_DEFAULT_TTL_DAYS_KEY);
-        if ($value !== null && $value >= self::API_TOKEN_TTL_DAYS_MIN && $value <= self::API_TOKEN_TTL_DAYS_HARD_MAX) {
-            return min($value, $maxDays);
-        }
-        return min(self::API_TOKEN_DEFAULT_TTL_DAYS_FALLBACK, $maxDays);
-    }
-
-    public function setApiTokenDefaultTtlDays(?int $days, ?string $description = null): bool
-    {
-        $value = $days ?? self::API_TOKEN_DEFAULT_TTL_DAYS_FALLBACK;
-        if ($value < self::API_TOKEN_TTL_DAYS_MIN || $value > self::API_TOKEN_TTL_DAYS_HARD_MAX) {
-            return false;
-        }
-        if ($value > $this->getApiTokenMaxTtlDays()) {
-            return false;
-        }
-        $desc = $description ?? 'setting.api_token_default_ttl_days';
-        return $this->settingRepository->set(self::API_TOKEN_DEFAULT_TTL_DAYS_KEY, (string) $value, $desc);
-    }
-
-    public function getApiTokenMaxTtlDays(): int
-    {
-        $value = $this->getInt(self::API_TOKEN_MAX_TTL_DAYS_KEY);
-        if ($value !== null && $value >= self::API_TOKEN_TTL_DAYS_MIN && $value <= self::API_TOKEN_TTL_DAYS_HARD_MAX) {
-            return $value;
-        }
-        return self::API_TOKEN_MAX_TTL_DAYS_FALLBACK;
-    }
-
-    public function setApiTokenMaxTtlDays(?int $days, ?string $description = null): bool
-    {
-        $value = $days ?? self::API_TOKEN_MAX_TTL_DAYS_FALLBACK;
-        if ($value < self::API_TOKEN_TTL_DAYS_MIN || $value > self::API_TOKEN_TTL_DAYS_HARD_MAX) {
-            return false;
-        }
-
-        $currentDefault = $this->getInt(self::API_TOKEN_DEFAULT_TTL_DAYS_KEY);
-        if ($currentDefault !== null && $currentDefault > $value) {
-            $defaultUpdated = $this->settingRepository->set(
-                self::API_TOKEN_DEFAULT_TTL_DAYS_KEY,
-                (string) $value,
-                'setting.api_token_default_ttl_days'
-            );
-            if (!$defaultUpdated) {
-                return false;
-            }
-        }
-
-        $desc = $description ?? 'setting.api_token_max_ttl_days';
-        return $this->settingRepository->set(self::API_TOKEN_MAX_TTL_DAYS_KEY, (string) $value, $desc);
-    }
-
-    public function getUserInactivityDeactivateDays(): int
-    {
-        $value = $this->getInt(self::USER_INACTIVITY_DEACTIVATE_DAYS_KEY);
-        if ($value !== null && $this->isValidInactivityDays($value)) {
-            return $value;
-        }
-        return self::USER_INACTIVITY_DEACTIVATE_DAYS_FALLBACK;
-    }
-
-    public function setUserInactivityDeactivateDays(?int $days, ?string $description = null): bool
-    {
-        $value = $days ?? self::USER_INACTIVITY_DEACTIVATE_DAYS_FALLBACK;
-        if (!$this->isValidInactivityDays($value)) {
-            return false;
-        }
-        if ($value === 0) {
-            $deleteUpdated = $this->settingRepository->set(
-                self::USER_INACTIVITY_DELETE_DAYS_KEY,
-                '0',
-                'setting.user_inactivity_delete_days'
-            );
-            if (!$deleteUpdated) {
-                return false;
-            }
-        }
-        $desc = $description ?? 'setting.user_inactivity_deactivate_days';
-        return $this->settingRepository->set(self::USER_INACTIVITY_DEACTIVATE_DAYS_KEY, (string) $value, $desc);
-    }
-
-    public function getUserInactivityDeleteDays(): int
-    {
-        $deactivateDays = $this->getUserInactivityDeactivateDays();
-        if ($deactivateDays <= 0) {
-            return 0;
-        }
-        $value = $this->getInt(self::USER_INACTIVITY_DELETE_DAYS_KEY);
-        if ($value !== null && $this->isValidInactivityDays($value)) {
-            return $value;
-        }
-        return self::USER_INACTIVITY_DELETE_DAYS_FALLBACK;
-    }
-
-    public function setUserInactivityDeleteDays(?int $days, ?string $description = null): bool
-    {
-        $value = $days ?? self::USER_INACTIVITY_DELETE_DAYS_FALLBACK;
-        if (!$this->isValidInactivityDays($value)) {
-            return false;
-        }
-        if ($value > 0 && $this->getUserInactivityDeactivateDays() <= 0) {
-            return false;
-        }
-        $desc = $description ?? 'setting.user_inactivity_delete_days';
-        return $this->settingRepository->set(self::USER_INACTIVITY_DELETE_DAYS_KEY, (string) $value, $desc);
-    }
-
-    public function isSystemAuditEnabled(): bool
-    {
-        $value = strtolower(trim((string) ($this->settingRepository->getValue(self::SYSTEM_AUDIT_ENABLED_KEY) ?? '')));
-        if ($value === '') {
-            return self::SYSTEM_AUDIT_ENABLED_FALLBACK;
-        }
-
-        return in_array($value, ['1', 'true', 'yes', 'on'], true);
-    }
-
-    public function setSystemAuditEnabled(bool $enabled, ?string $description = null): bool
-    {
-        $desc = $description ?? 'setting.system_audit_enabled';
-        return $this->settingRepository->set(self::SYSTEM_AUDIT_ENABLED_KEY, $enabled ? '1' : '0', $desc);
-    }
-
-    public function getSystemAuditRetentionDays(): int
-    {
-        $value = $this->getInt(self::SYSTEM_AUDIT_RETENTION_DAYS_KEY);
-        if ($value === null) {
-            return self::SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK;
-        }
-        if ($value < self::SYSTEM_AUDIT_RETENTION_DAYS_MIN || $value > self::SYSTEM_AUDIT_RETENTION_DAYS_MAX) {
-            return self::SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK;
-        }
-        return $value;
-    }
-
-    public function setSystemAuditRetentionDays(?int $days, ?string $description = null): bool
-    {
-        $value = $days ?? self::SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK;
-        if ($value < self::SYSTEM_AUDIT_RETENTION_DAYS_MIN || $value > self::SYSTEM_AUDIT_RETENTION_DAYS_MAX) {
-            return false;
-        }
-
-        $desc = $description ?? 'setting.system_audit_retention_days';
-        return $this->settingRepository->set(self::SYSTEM_AUDIT_RETENTION_DAYS_KEY, (string) $value, $desc);
-    }
-
-    public function getApiCorsAllowedOrigins(): array
-    {
-        $stored = $this->settingRepository->getValue(self::API_CORS_ALLOWED_ORIGINS_KEY);
-        if ($stored === null || trim($stored) === '') {
-            return [];
-        }
-        return $this->parseCorsOrigins($stored, false) ?? [];
-    }
-
-    public function getApiCorsAllowedOriginsText(): string
-    {
-        $origins = $this->getApiCorsAllowedOrigins();
-        return implode("\n", $origins);
-    }
-
-    public function setApiCorsAllowedOrigins(?string $rawOrigins, ?string $description = null): bool
-    {
-        $value = (string) ($rawOrigins ?? '');
-        if (trim($value) === '') {
-            return $this->settingRepository->set(
-                self::API_CORS_ALLOWED_ORIGINS_KEY,
-                null,
-                $description ?? 'setting.api_cors_allowed_origins'
-            );
-        }
-
-        $origins = $this->parseCorsOrigins($value, true);
-        if ($origins === null) {
-            return false;
-        }
-
-        return $this->settingRepository->set(
-            self::API_CORS_ALLOWED_ORIGINS_KEY,
-            implode("\n", $origins),
-            $description ?? 'setting.api_cors_allowed_origins'
-        );
-    }
-
-    private function parseCorsOrigins(string $rawOrigins, bool $strict): ?array
-    {
-        $parts = preg_split('/[\r\n,]+/', $rawOrigins) ?: [];
-        $normalizedOrigins = [];
-        foreach ($parts as $part) {
-            $origin = $this->normalizeCorsOrigin($part);
-            if ($origin === null) {
-                if ($strict && trim((string) $part) !== '') {
-                    return null;
-                }
-                continue;
-            }
-            $normalizedOrigins[$origin] = true;
-        }
-        return array_keys($normalizedOrigins);
-    }
-
-    private function normalizeCorsOrigin(string $origin): ?string
-    {
-        $origin = trim($origin);
-        if ($origin === '') {
-            return null;
-        }
-
-        // Browser Origin header never contains a trailing slash.
-        $origin = rtrim($origin, '/');
-        if ($origin === '') {
-            return null;
-        }
-
-        $parsed = parse_url($origin);
-        if (!is_array($parsed)) {
-            return null;
-        }
-
-        $scheme = strtolower((string) ($parsed['scheme'] ?? ''));
-        $host = strtolower((string) ($parsed['host'] ?? ''));
-        $port = isset($parsed['port']) ? (int) $parsed['port'] : null;
-
-        if (!in_array($scheme, ['http', 'https'], true) || $host === '') {
-            return null;
-        }
-
-        if (
-            isset($parsed['path'])
-            || isset($parsed['query'])
-            || isset($parsed['fragment'])
-            || isset($parsed['user'])
-            || isset($parsed['pass'])
-        ) {
-            return null;
-        }
-
-        $defaultPort = ($scheme === 'https') ? 443 : 80;
-        $portSuffix = ($port !== null && $port !== $defaultPort) ? ':' . $port : '';
-        return $scheme . '://' . $host . $portSuffix;
-    }
-
-    public function getMicrosoftSharedClientId(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::MICROSOFT_SHARED_CLIENT_ID_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setMicrosoftSharedClientId(?string $clientId, ?string $description = null): bool
-    {
-        $value = $clientId !== null ? trim((string) $clientId) : '';
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.microsoft_shared_client_id';
-        return $this->settingRepository->set(self::MICROSOFT_SHARED_CLIENT_ID_KEY, $value, $desc);
-    }
-
-    public function getMicrosoftSharedClientSecretEncrypted(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function getMicrosoftSharedClientSecret(): ?string
-    {
-        $encrypted = $this->getMicrosoftSharedClientSecretEncrypted();
-        if ($encrypted === null) {
-            return null;
-        }
-        try {
-            $decrypted = Crypto::decryptString($encrypted);
-        } catch (\Throwable $exception) {
-            return null;
-        }
-        $decrypted = trim($decrypted);
-        return $decrypted !== '' ? $decrypted : null;
-    }
-
-    public function setMicrosoftSharedClientSecret(?string $secret, ?string $description = null): bool
-    {
-        $value = $secret !== null ? trim((string) $secret) : '';
-        if ($value === '') {
-            return $this->settingRepository->set(
-                self::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY,
-                null,
-                $description ?? 'setting.microsoft_shared_client_secret_enc'
-            );
-        }
-        $encrypted = Crypto::encryptString($value);
-        $desc = $description ?? 'setting.microsoft_shared_client_secret_enc';
-        return $this->settingRepository->set(self::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY, $encrypted, $desc);
-    }
-
-    public function getMicrosoftAuthority(): string
-    {
-        $value = $this->settingRepository->getValue(self::MICROSOFT_AUTHORITY_KEY);
-        $value = trim((string) ($value ?? ''));
-        if ($value === '') {
-            return 'https://login.microsoftonline.com/common/v2.0';
-        }
-        return rtrim($value, '/');
-    }
-
-    public function setMicrosoftAuthority(?string $authority, ?string $description = null): bool
-    {
-        $value = trim((string) ($authority ?? ''));
-        if ($value === '') {
-            $value = 'https://login.microsoftonline.com/common/v2.0';
-        }
-        if (!preg_match('#^https://#i', $value)) {
-            return false;
-        }
-        $desc = $description ?? 'setting.microsoft_authority';
-        return $this->settingRepository->set(self::MICROSOFT_AUTHORITY_KEY, rtrim($value, '/'), $desc);
-    }
-
-    public function getAppPrimaryColor(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::APP_PRIMARY_COLOR_KEY);
-        $value = $value !== null ? strtolower(trim((string) $value)) : '';
-        if ($value === '') {
-            return null;
-        }
-        if (!preg_match('/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i', $value)) {
-            return null;
-        }
-        return $value;
-    }
-
-    public function setAppPrimaryColor(?string $color, ?string $description = null): bool
-    {
-        $value = $color !== null ? strtolower(trim((string) $color)) : '';
-        if ($value !== '' && $value[0] !== '#') {
-            if (preg_match('/^[0-9a-f]{3}$/i', $value)
-                || preg_match('/^[0-9a-f]{4}$/i', $value)
-                || preg_match('/^[0-9a-f]{6}$/i', $value)
-                || preg_match('/^[0-9a-f]{8}$/i', $value)) {
-                $value = '#' . $value;
-            }
-        }
-        if ($value === '') {
-            $value = null;
-        } elseif (!preg_match('/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i', $value)) {
-            return false;
-        }
-        $desc = $description ?? 'setting.app_primary_color';
-        return $this->settingRepository->set(self::APP_PRIMARY_COLOR_KEY, $value, $desc);
-    }
-
-    public function getSmtpHost(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_HOST_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setSmtpHost(?string $host, ?string $description = null): bool
-    {
-        $value = $host !== null ? trim((string) $host) : '';
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.smtp_host';
-        return $this->settingRepository->set(self::SMTP_HOST_KEY, $value, $desc);
-    }
-
-    public function getSmtpPort(): ?int
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_PORT_KEY);
-        if ($value === null || $value === '') {
-            return null;
-        }
-        $port = (int) $value;
-        return $port > 0 ? $port : null;
-    }
-
-    public function setSmtpPort(?int $port, ?string $description = null): bool
-    {
-        $value = $port && $port > 0 ? (string) $port : null;
-        $desc = $description ?? 'setting.smtp_port';
-        return $this->settingRepository->set(self::SMTP_PORT_KEY, $value, $desc);
-    }
-
-    public function getSmtpUser(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_USER_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setSmtpUser(?string $user, ?string $description = null): bool
-    {
-        $value = $user !== null ? trim((string) $user) : '';
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.smtp_user';
-        return $this->settingRepository->set(self::SMTP_USER_KEY, $value, $desc);
-    }
-
-    public function getSmtpPassword(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_PASSWORD_KEY);
-        $value = $value !== null ? (string) $value : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setSmtpPassword(?string $password, ?string $description = null): bool
-    {
-        $value = $password !== null ? (string) $password : '';
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.smtp_password';
-        return $this->settingRepository->set(self::SMTP_PASSWORD_KEY, $value, $desc);
-    }
-
-    public function getSmtpSecure(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_SECURE_KEY);
-        $value = $value !== null ? strtolower(trim((string) $value)) : '';
-        if (!in_array($value, ['tls', 'ssl', 'none'], true)) {
-            return null;
-        }
-        return $value === 'none' ? null : $value;
-    }
-
-    public function setSmtpSecure(?string $secure, ?string $description = null): bool
-    {
-        $value = $secure !== null ? strtolower(trim((string) $secure)) : '';
-        if ($value === '' || $value === 'none') {
-            $value = null;
-        } elseif (!in_array($value, ['tls', 'ssl'], true)) {
-            return false;
-        }
-        $desc = $description ?? 'setting.smtp_secure';
-        return $this->settingRepository->set(self::SMTP_SECURE_KEY, $value, $desc);
-    }
-
-    public function getSmtpFrom(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_FROM_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setSmtpFrom(?string $from, ?string $description = null): bool
-    {
-        $value = $from !== null ? trim((string) $from) : '';
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.smtp_from';
-        return $this->settingRepository->set(self::SMTP_FROM_KEY, $value, $desc);
-    }
-
-    public function getSmtpFromName(): ?string
-    {
-        $value = $this->settingRepository->getValue(self::SMTP_FROM_NAME_KEY);
-        $value = $value !== null ? trim((string) $value) : '';
-        return $value !== '' ? $value : null;
-    }
-
-    public function setSmtpFromName(?string $fromName, ?string $description = null): bool
-    {
-        $value = $fromName !== null ? trim((string) $fromName) : '';
-        if ($value === '') {
-            $value = null;
-        }
-        $desc = $description ?? 'setting.smtp_from_name';
-        return $this->settingRepository->set(self::SMTP_FROM_NAME_KEY, $value, $desc);
-    }
-
-    private function isValidInactivityDays(int $days): bool
-    {
-        return $days >= self::USER_INACTIVITY_DAYS_MIN && $days <= self::USER_INACTIVITY_DAYS_MAX;
-    }
-}
diff --git a/lib/Service/Settings/SettingServicesFactory.php b/lib/Service/Settings/SettingServicesFactory.php
index 82167e2..9733b0b 100644
--- a/lib/Service/Settings/SettingServicesFactory.php
+++ b/lib/Service/Settings/SettingServicesFactory.php
@@ -10,9 +10,17 @@ use MintyPHP\Repository\Tenant\TenantRepositoryInterface;
 class SettingServicesFactory
 {
     private ?ThemeConfigService $themeConfigService = null;
-    private ?SettingService $settingService = null;
     private ?SettingCacheService $settingCacheService = null;
-    private ?SettingGateway $settingGateway = null;
+    private ?SettingsCryptoGatewayInterface $settingsCryptoGateway = null;
+    private ?SettingsMetadataGateway $settingsMetadataGateway = null;
+    private ?SettingsDefaultsGateway $settingsDefaultsGateway = null;
+    private ?SettingsAppGateway $settingsAppGateway = null;
+    private ?SettingsApiPolicyGateway $settingsApiPolicyGateway = null;
+    private ?SettingsUserLifecycleGateway $settingsUserLifecycleGateway = null;
+    private ?SettingsSystemAuditGateway $settingsSystemAuditGateway = null;
+    private ?SettingsFrontendTelemetryGateway $settingsFrontendTelemetryGateway = null;
+    private ?SettingsMicrosoftGateway $settingsMicrosoftGateway = null;
+    private ?SettingsSmtpGateway $settingsSmtpGateway = null;
 
     public function __construct(
         private readonly SettingRepositoryFactory $settingRepositoryFactory
@@ -24,20 +32,60 @@ class SettingServicesFactory
         return $this->settingRepositoryFactory->createSettingRepository();
     }
 
-    public function createSettingService(): SettingService
+    public function createSettingsMetadataGateway(): SettingsMetadataGateway
     {
-        return $this->settingService ??= new SettingService(
-            $this->createSettingRepository(),
+        return $this->settingsMetadataGateway ??= new SettingsMetadataGateway($this->createSettingRepository());
+    }
+
+    public function createSettingsDefaultsGateway(): SettingsDefaultsGateway
+    {
+        return $this->settingsDefaultsGateway ??= new SettingsDefaultsGateway(
+            $this->createSettingsMetadataGateway(),
             $this->createTenantRepository(),
             $this->createRoleRepository(),
             $this->createDepartmentRepository(),
-            $this->createThemeConfigService()
         );
     }
 
-    public function createSettingGateway(): SettingGateway
+    public function createSettingsAppGateway(): SettingsAppGateway
     {
-        return $this->settingGateway ??= new SettingGateway($this->createSettingService());
+        return $this->settingsAppGateway ??= new SettingsAppGateway(
+            $this->createSettingsMetadataGateway(),
+            $this->createThemeConfigService(),
+        );
+    }
+
+    public function createSettingsApiPolicyGateway(): SettingsApiPolicyGateway
+    {
+        return $this->settingsApiPolicyGateway ??= new SettingsApiPolicyGateway($this->createSettingsMetadataGateway());
+    }
+
+    public function createSettingsUserLifecycleGateway(): SettingsUserLifecycleGateway
+    {
+        return $this->settingsUserLifecycleGateway ??= new SettingsUserLifecycleGateway($this->createSettingsMetadataGateway());
+    }
+
+    public function createSettingsSystemAuditGateway(): SettingsSystemAuditGateway
+    {
+        return $this->settingsSystemAuditGateway ??= new SettingsSystemAuditGateway($this->createSettingsMetadataGateway());
+    }
+
+    public function createSettingsFrontendTelemetryGateway(): SettingsFrontendTelemetryGateway
+    {
+        return $this->settingsFrontendTelemetryGateway ??= new SettingsFrontendTelemetryGateway($this->createSettingsMetadataGateway());
+    }
+
+    public function createSettingsMicrosoftGateway(): SettingsMicrosoftGateway
+    {
+        return $this->settingsMicrosoftGateway ??= new SettingsMicrosoftGateway(
+            $this->createSettingsMetadataGateway(),
+            $this->createSettingsCryptoGateway(),
+        );
+    }
+
+    public function createSettingsSmtpGateway(): SettingsSmtpGateway
+    {
+        return $this->settingsSmtpGateway ??= new SettingsSmtpGateway($this->createSettingsMetadataGateway());
     }
 
     public function createSettingCacheService(): SettingCacheService
@@ -50,6 +98,11 @@ class SettingServicesFactory
         return $this->themeConfigService ??= new ThemeConfigService();
     }
 
+    public function createSettingsCryptoGateway(): SettingsCryptoGatewayInterface
+    {
+        return $this->settingsCryptoGateway ??= new SettingsCryptoGateway();
+    }
+
     private function createTenantRepository(): TenantRepositoryInterface
     {
         return $this->settingRepositoryFactory->createTenantRepository();
diff --git a/lib/Service/Settings/SettingsApiPolicyGateway.php b/lib/Service/Settings/SettingsApiPolicyGateway.php
new file mode 100644
index 0000000..10160ca
--- /dev/null
+++ b/lib/Service/Settings/SettingsApiPolicyGateway.php
@@ -0,0 +1,170 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+class SettingsApiPolicyGateway
+{
+    private const API_TOKEN_DEFAULT_TTL_DAYS_FALLBACK = 90;
+    private const API_TOKEN_MAX_TTL_DAYS_FALLBACK = 365;
+    private const API_TOKEN_TTL_DAYS_MIN = 1;
+    private const API_TOKEN_TTL_DAYS_HARD_MAX = 3650;
+
+    public function __construct(private readonly SettingsMetadataGateway $settingsMetadataGateway)
+    {
+    }
+
+    public function getApiTokenDefaultTtlDays(): int
+    {
+        $maxDays = $this->getApiTokenMaxTtlDays();
+        $value = $this->settingsMetadataGateway->getInt(SettingKeys::API_TOKEN_DEFAULT_TTL_DAYS_KEY);
+        if ($value !== null && $value >= self::API_TOKEN_TTL_DAYS_MIN && $value <= self::API_TOKEN_TTL_DAYS_HARD_MAX) {
+            return min($value, $maxDays);
+        }
+
+        return min(self::API_TOKEN_DEFAULT_TTL_DAYS_FALLBACK, $maxDays);
+    }
+
+    public function setApiTokenDefaultTtlDays(?int $days, ?string $description = null): bool
+    {
+        $value = $days ?? self::API_TOKEN_DEFAULT_TTL_DAYS_FALLBACK;
+        if ($value < self::API_TOKEN_TTL_DAYS_MIN || $value > self::API_TOKEN_TTL_DAYS_HARD_MAX) {
+            return false;
+        }
+        if ($value > $this->getApiTokenMaxTtlDays()) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.api_token_default_ttl_days';
+        return $this->settingsMetadataGateway->set(SettingKeys::API_TOKEN_DEFAULT_TTL_DAYS_KEY, (string) $value, $desc);
+    }
+
+    public function getApiTokenMaxTtlDays(): int
+    {
+        $value = $this->settingsMetadataGateway->getInt(SettingKeys::API_TOKEN_MAX_TTL_DAYS_KEY);
+        if ($value !== null && $value >= self::API_TOKEN_TTL_DAYS_MIN && $value <= self::API_TOKEN_TTL_DAYS_HARD_MAX) {
+            return $value;
+        }
+
+        return self::API_TOKEN_MAX_TTL_DAYS_FALLBACK;
+    }
+
+    public function setApiTokenMaxTtlDays(?int $days, ?string $description = null): bool
+    {
+        $value = $days ?? self::API_TOKEN_MAX_TTL_DAYS_FALLBACK;
+        if ($value < self::API_TOKEN_TTL_DAYS_MIN || $value > self::API_TOKEN_TTL_DAYS_HARD_MAX) {
+            return false;
+        }
+
+        $currentDefault = $this->settingsMetadataGateway->getInt(SettingKeys::API_TOKEN_DEFAULT_TTL_DAYS_KEY);
+        if ($currentDefault !== null && $currentDefault > $value) {
+            $defaultUpdated = $this->settingsMetadataGateway->set(
+                SettingKeys::API_TOKEN_DEFAULT_TTL_DAYS_KEY,
+                (string) $value,
+                'setting.api_token_default_ttl_days'
+            );
+            if (!$defaultUpdated) {
+                return false;
+            }
+        }
+
+        $desc = $description ?? 'setting.api_token_max_ttl_days';
+        return $this->settingsMetadataGateway->set(SettingKeys::API_TOKEN_MAX_TTL_DAYS_KEY, (string) $value, $desc);
+    }
+
+    public function getApiCorsAllowedOrigins(): array
+    {
+        $stored = $this->settingsMetadataGateway->getValue(SettingKeys::API_CORS_ALLOWED_ORIGINS_KEY);
+        if ($stored === null || trim($stored) === '') {
+            return [];
+        }
+
+        return $this->parseCorsOrigins($stored, false) ?? [];
+    }
+
+    public function getApiCorsAllowedOriginsText(): string
+    {
+        $origins = $this->getApiCorsAllowedOrigins();
+        return implode("\n", $origins);
+    }
+
+    public function setApiCorsAllowedOrigins(?string $rawOrigins, ?string $description = null): bool
+    {
+        $value = (string) ($rawOrigins ?? '');
+        if (trim($value) === '') {
+            return $this->settingsMetadataGateway->set(
+                SettingKeys::API_CORS_ALLOWED_ORIGINS_KEY,
+                null,
+                $description ?? 'setting.api_cors_allowed_origins'
+            );
+        }
+
+        $origins = $this->parseCorsOrigins($value, true);
+        if ($origins === null) {
+            return false;
+        }
+
+        return $this->settingsMetadataGateway->set(
+            SettingKeys::API_CORS_ALLOWED_ORIGINS_KEY,
+            implode("\n", $origins),
+            $description ?? 'setting.api_cors_allowed_origins'
+        );
+    }
+
+    private function parseCorsOrigins(string $rawOrigins, bool $strict): ?array
+    {
+        $parts = preg_split('/[\r\n,]+/', $rawOrigins) ?: [];
+        $normalizedOrigins = [];
+        foreach ($parts as $part) {
+            $origin = $this->normalizeCorsOrigin($part);
+            if ($origin === null) {
+                if ($strict && trim((string) $part) !== '') {
+                    return null;
+                }
+                continue;
+            }
+            $normalizedOrigins[$origin] = true;
+        }
+
+        return array_keys($normalizedOrigins);
+    }
+
+    private function normalizeCorsOrigin(string $origin): ?string
+    {
+        $origin = trim($origin);
+        if ($origin === '') {
+            return null;
+        }
+
+        $origin = rtrim($origin, '/');
+        if ($origin === '') {
+            return null;
+        }
+
+        $parsed = parse_url($origin);
+        if (!is_array($parsed)) {
+            return null;
+        }
+
+        $scheme = strtolower((string) ($parsed['scheme'] ?? ''));
+        $host = strtolower((string) ($parsed['host'] ?? ''));
+        $port = isset($parsed['port']) ? (int) $parsed['port'] : null;
+
+        if (!in_array($scheme, ['http', 'https'], true) || $host === '') {
+            return null;
+        }
+
+        if (
+            isset($parsed['path'])
+            || isset($parsed['query'])
+            || isset($parsed['fragment'])
+            || isset($parsed['user'])
+            || isset($parsed['pass'])
+        ) {
+            return null;
+        }
+
+        $defaultPort = ($scheme === 'https') ? 443 : 80;
+        $portSuffix = ($port !== null && $port !== $defaultPort) ? ':' . $port : '';
+        return $scheme . '://' . $host . $portSuffix;
+    }
+}
diff --git a/lib/Service/Settings/SettingsAppGateway.php b/lib/Service/Settings/SettingsAppGateway.php
new file mode 100644
index 0000000..f74aa35
--- /dev/null
+++ b/lib/Service/Settings/SettingsAppGateway.php
@@ -0,0 +1,162 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+use MintyPHP\I18n;
+
+class SettingsAppGateway
+{
+    public function __construct(
+        private readonly SettingsMetadataGateway $settingsMetadataGateway,
+        private readonly ThemeConfigService $themeConfigService
+    ) {
+    }
+
+    public function getAppTitle(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::APP_TITLE_KEY);
+        $value = $value !== null ? trim($value) : null;
+        return $value !== '' ? $value : null;
+    }
+
+    public function setAppTitle(?string $title, ?string $description = null): bool
+    {
+        $value = $title !== null ? trim($title) : null;
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.app_title';
+        return $this->settingsMetadataGateway->set(SettingKeys::APP_TITLE_KEY, $value, $desc);
+    }
+
+    public function getAppLocale(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::APP_LOCALE_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setAppLocale(?string $locale, ?string $description = null): bool
+    {
+        $value = $locale !== null ? trim($locale) : '';
+        if ($value === '') {
+            $value = null;
+        } else {
+            $allowed = defined('APP_LOCALES') ? APP_LOCALES : [];
+            if ($allowed && !in_array($value, $allowed, true)) {
+                return false;
+            }
+        }
+
+        $desc = $description ?? 'setting.app_locale';
+        return $this->settingsMetadataGateway->set(SettingKeys::APP_LOCALE_KEY, $value, $desc);
+    }
+
+    public function getAppTheme(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::APP_THEME_KEY);
+        $value = $value !== null ? strtolower(trim($value)) : '';
+        if (!in_array($value, $this->allowedThemes(), true)) {
+            return null;
+        }
+
+        return $value;
+    }
+
+    public function setAppTheme(?string $theme, ?string $description = null): bool
+    {
+        $value = $theme !== null ? strtolower(trim($theme)) : '';
+        if ($value === '' || !in_array($value, $this->allowedThemes(), true)) {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.app_theme';
+        return $this->settingsMetadataGateway->set(SettingKeys::APP_THEME_KEY, $value, $desc);
+    }
+
+    public function isUserThemeAllowed(): bool
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::APP_THEME_USER_KEY);
+        if ($value === null || $value === '') {
+            return true;
+        }
+
+        return in_array(strtolower($value), ['1', 'true', 'yes', 'on'], true);
+    }
+
+    public function setUserThemeAllowed(bool $allowed, ?string $description = null): bool
+    {
+        $value = $allowed ? '1' : '0';
+        $desc = $description ?? 'setting.app_theme_user';
+        return $this->settingsMetadataGateway->set(SettingKeys::APP_THEME_USER_KEY, $value, $desc);
+    }
+
+    public function isRegistrationEnabled(): bool
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::APP_REGISTRATION_KEY);
+        if ($value === null || $value === '') {
+            return true;
+        }
+
+        return in_array(strtolower($value), ['1', 'true', 'yes', 'on'], true);
+    }
+
+    public function setRegistrationEnabled(bool $allowed, ?string $description = null): bool
+    {
+        $value = $allowed ? '1' : '0';
+        $desc = $description ?? 'setting.app_registration';
+        return $this->settingsMetadataGateway->set(SettingKeys::APP_REGISTRATION_KEY, $value, $desc);
+    }
+
+    public function getAppPrimaryColor(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::APP_PRIMARY_COLOR_KEY);
+        $value = $value !== null ? strtolower(trim($value)) : '';
+        if ($value === '') {
+            return null;
+        }
+        if (!preg_match('/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i', $value)) {
+            return null;
+        }
+
+        return $value;
+    }
+
+    public function setAppPrimaryColor(?string $color, ?string $description = null): bool
+    {
+        $value = $color !== null ? strtolower(trim($color)) : '';
+        if ($value !== '' && $value[0] !== '#') {
+            if (preg_match('/^[0-9a-f]{3}$/i', $value)
+                || preg_match('/^[0-9a-f]{4}$/i', $value)
+                || preg_match('/^[0-9a-f]{6}$/i', $value)
+                || preg_match('/^[0-9a-f]{8}$/i', $value)) {
+                $value = '#' . $value;
+            }
+        }
+        if ($value === '') {
+            $value = null;
+        } elseif (!preg_match('/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i', $value)) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.app_primary_color';
+        return $this->settingsMetadataGateway->set(SettingKeys::APP_PRIMARY_COLOR_KEY, $value, $desc);
+    }
+
+    private function allowedThemes(): array
+    {
+        return array_keys($this->themeConfigService->all());
+    }
+
+    public function normalizeLocale(?string $locale): string
+    {
+        $value = strtolower(trim((string) $locale));
+        $available = defined('APP_LOCALES') ? APP_LOCALES : [I18n::$defaultLocale];
+        if ($value === '' || !in_array($value, $available, true)) {
+            return I18n::$locale ?? I18n::$defaultLocale;
+        }
+
+        return $value;
+    }
+}
diff --git a/lib/Service/Settings/SettingsCryptoGateway.php b/lib/Service/Settings/SettingsCryptoGateway.php
new file mode 100644
index 0000000..7cf4bf6
--- /dev/null
+++ b/lib/Service/Settings/SettingsCryptoGateway.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+use MintyPHP\Support\Crypto;
+
+class SettingsCryptoGateway implements SettingsCryptoGatewayInterface
+{
+    public function encryptString(string $value): string
+    {
+        return Crypto::encryptString($value);
+    }
+
+    public function decryptString(string $value): string
+    {
+        return Crypto::decryptString($value);
+    }
+}
diff --git a/lib/Service/Settings/SettingsCryptoGatewayInterface.php b/lib/Service/Settings/SettingsCryptoGatewayInterface.php
new file mode 100644
index 0000000..a4d395d
--- /dev/null
+++ b/lib/Service/Settings/SettingsCryptoGatewayInterface.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+interface SettingsCryptoGatewayInterface
+{
+    public function encryptString(string $value): string;
+
+    public function decryptString(string $value): string;
+}
diff --git a/lib/Service/Settings/SettingsDefaultsGateway.php b/lib/Service/Settings/SettingsDefaultsGateway.php
new file mode 100644
index 0000000..4ac8a82
--- /dev/null
+++ b/lib/Service/Settings/SettingsDefaultsGateway.php
@@ -0,0 +1,78 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+use MintyPHP\Repository\Access\RoleRepositoryInterface;
+use MintyPHP\Repository\Org\DepartmentRepositoryInterface;
+use MintyPHP\Repository\Tenant\TenantRepositoryInterface;
+
+class SettingsDefaultsGateway
+{
+    public function __construct(
+        private readonly SettingsMetadataGateway $settingsMetadataGateway,
+        private readonly TenantRepositoryInterface $tenantRepository,
+        private readonly RoleRepositoryInterface $roleRepository,
+        private readonly DepartmentRepositoryInterface $departmentRepository
+    ) {
+    }
+
+    public function getDefaultTenantId(): ?int
+    {
+        $id = $this->settingsMetadataGateway->getInt(SettingKeys::DEFAULT_TENANT_KEY);
+        return $id && $id > 0 ? $id : null;
+    }
+
+    public function setDefaultTenantId(?int $tenantId, ?string $description = null): bool
+    {
+        $value = $tenantId && $tenantId > 0 ? (string) $tenantId : null;
+        if ($value !== null) {
+            $exists = $this->tenantRepository->find($tenantId);
+            if (!$exists) {
+                return false;
+            }
+        }
+
+        $desc = $description ?? 'setting.default_tenant';
+        return $this->settingsMetadataGateway->set(SettingKeys::DEFAULT_TENANT_KEY, $value, $desc);
+    }
+
+    public function getDefaultRoleId(): ?int
+    {
+        $id = $this->settingsMetadataGateway->getInt(SettingKeys::DEFAULT_ROLE_KEY);
+        return $id && $id > 0 ? $id : null;
+    }
+
+    public function setDefaultRoleId(?int $roleId, ?string $description = null): bool
+    {
+        $value = $roleId && $roleId > 0 ? (string) $roleId : null;
+        if ($value !== null) {
+            $exists = $this->roleRepository->find($roleId);
+            if (!$exists) {
+                return false;
+            }
+        }
+
+        $desc = $description ?? 'setting.default_role';
+        return $this->settingsMetadataGateway->set(SettingKeys::DEFAULT_ROLE_KEY, $value, $desc);
+    }
+
+    public function getDefaultDepartmentId(): ?int
+    {
+        $id = $this->settingsMetadataGateway->getInt(SettingKeys::DEFAULT_DEPARTMENT_KEY);
+        return $id && $id > 0 ? $id : null;
+    }
+
+    public function setDefaultDepartmentId(?int $departmentId, ?string $description = null): bool
+    {
+        $value = $departmentId && $departmentId > 0 ? (string) $departmentId : null;
+        if ($value !== null) {
+            $exists = $this->departmentRepository->find($departmentId);
+            if (!$exists) {
+                return false;
+            }
+        }
+
+        $desc = $description ?? 'setting.default_department';
+        return $this->settingsMetadataGateway->set(SettingKeys::DEFAULT_DEPARTMENT_KEY, $value, $desc);
+    }
+}
diff --git a/lib/Service/Settings/SettingsFrontendTelemetryGateway.php b/lib/Service/Settings/SettingsFrontendTelemetryGateway.php
new file mode 100644
index 0000000..d5211e0
--- /dev/null
+++ b/lib/Service/Settings/SettingsFrontendTelemetryGateway.php
@@ -0,0 +1,141 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+class SettingsFrontendTelemetryGateway
+{
+    private const FRONTEND_TELEMETRY_ENABLED_FALLBACK = false;
+    private const FRONTEND_TELEMETRY_SAMPLE_RATE_FALLBACK = 0.2;
+    private const FRONTEND_TELEMETRY_SAMPLE_RATE_MIN = 0.0;
+    private const FRONTEND_TELEMETRY_SAMPLE_RATE_MAX = 1.0;
+    /** @var array<int, string> */
+    private const FRONTEND_TELEMETRY_ALLOWED_EVENTS = ['warn_once', 'ajax_error'];
+    /** @var list<string>|null */
+    private ?array $cachedAllowedEvents = null;
+
+    public function __construct(private readonly SettingsMetadataGateway $settingsMetadataGateway)
+    {
+    }
+
+    public function isFrontendTelemetryEnabled(): bool
+    {
+        $value = strtolower(trim((string) ($this->settingsMetadataGateway->getValue(SettingKeys::FRONTEND_TELEMETRY_ENABLED_KEY) ?? '')));
+        if ($value === '') {
+            return self::FRONTEND_TELEMETRY_ENABLED_FALLBACK;
+        }
+
+        return in_array($value, ['1', 'true', 'yes', 'on'], true);
+    }
+
+    public function setFrontendTelemetryEnabled(bool $enabled, ?string $description = null): bool
+    {
+        $desc = $description ?? 'setting.frontend_telemetry_enabled';
+        return $this->settingsMetadataGateway->set(SettingKeys::FRONTEND_TELEMETRY_ENABLED_KEY, $enabled ? '1' : '0', $desc);
+    }
+
+    public function getFrontendTelemetrySampleRate(): float
+    {
+        $raw = trim((string) ($this->settingsMetadataGateway->getValue(SettingKeys::FRONTEND_TELEMETRY_SAMPLE_RATE_KEY) ?? ''));
+        if ($raw === '') {
+            return self::FRONTEND_TELEMETRY_SAMPLE_RATE_FALLBACK;
+        }
+
+        $value = is_numeric($raw) ? (float) $raw : NAN;
+        if (!is_finite($value) || $value < self::FRONTEND_TELEMETRY_SAMPLE_RATE_MIN || $value > self::FRONTEND_TELEMETRY_SAMPLE_RATE_MAX) {
+            return self::FRONTEND_TELEMETRY_SAMPLE_RATE_FALLBACK;
+        }
+
+        return $value;
+    }
+
+    public function setFrontendTelemetrySampleRate(?float $sampleRate, ?string $description = null): bool
+    {
+        $value = $sampleRate ?? self::FRONTEND_TELEMETRY_SAMPLE_RATE_FALLBACK;
+        if (!is_finite($value) || $value < self::FRONTEND_TELEMETRY_SAMPLE_RATE_MIN || $value > self::FRONTEND_TELEMETRY_SAMPLE_RATE_MAX) {
+            return false;
+        }
+
+        $normalized = $this->normalizeSampleRateString($value);
+        $desc = $description ?? 'setting.frontend_telemetry_sample_rate';
+        return $this->settingsMetadataGateway->set(SettingKeys::FRONTEND_TELEMETRY_SAMPLE_RATE_KEY, $normalized, $desc);
+    }
+
+    /**
+     * @return list<string>
+     */
+    public function getFrontendTelemetryAllowedEvents(): array
+    {
+        if (is_array($this->cachedAllowedEvents)) {
+            return $this->cachedAllowedEvents;
+        }
+
+        $raw = (string) ($this->settingsMetadataGateway->getValue(SettingKeys::FRONTEND_TELEMETRY_ALLOWED_EVENTS_KEY) ?? '');
+        $normalized = $this->normalizeAllowedEvents($raw);
+        if ($normalized === []) {
+            $this->cachedAllowedEvents = self::FRONTEND_TELEMETRY_ALLOWED_EVENTS;
+            return $this->cachedAllowedEvents;
+        }
+        $this->cachedAllowedEvents = $normalized;
+        return $this->cachedAllowedEvents;
+    }
+
+    public function setFrontendTelemetryAllowedEvents(array|string|null $events, ?string $description = null): bool
+    {
+        $normalized = $this->normalizeAllowedEvents($events);
+        if ($normalized === []) {
+            $normalized = self::FRONTEND_TELEMETRY_ALLOWED_EVENTS;
+        }
+
+        $desc = $description ?? 'setting.frontend_telemetry_allowed_events';
+        $saved = $this->settingsMetadataGateway->set(
+            SettingKeys::FRONTEND_TELEMETRY_ALLOWED_EVENTS_KEY,
+            implode(',', $normalized),
+            $desc
+        );
+
+        $this->cachedAllowedEvents = null;
+        return $saved;
+    }
+
+    private function normalizeSampleRateString(float $value): string
+    {
+        $formatted = number_format($value, 4, '.', '');
+        $trimmed = rtrim(rtrim($formatted, '0'), '.');
+        return $trimmed === '' ? '0' : $trimmed;
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function normalizeAllowedEvents(array|string|null $events): array
+    {
+        $raw = [];
+        if (is_array($events)) {
+            $raw = $events;
+        } else {
+            $raw = preg_split('/[\s,]+/', (string) $events) ?: [];
+        }
+
+        $normalized = [];
+        foreach ($raw as $entry) {
+            $event = strtolower(trim((string) $entry));
+            if ($event === '') {
+                continue;
+            }
+
+            if (str_starts_with($event, 'frontend.')) {
+                $event = substr($event, strlen('frontend.'));
+            }
+
+            if (!in_array($event, self::FRONTEND_TELEMETRY_ALLOWED_EVENTS, true)) {
+                continue;
+            }
+
+            $normalized[] = $event;
+        }
+
+        $normalized = array_values(array_unique($normalized));
+        sort($normalized, SORT_STRING);
+        return $normalized;
+    }
+}
diff --git a/lib/Service/Settings/SettingsMetadataGateway.php b/lib/Service/Settings/SettingsMetadataGateway.php
new file mode 100644
index 0000000..449b386
--- /dev/null
+++ b/lib/Service/Settings/SettingsMetadataGateway.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+
+class SettingsMetadataGateway
+{
+    public function __construct(private readonly SettingRepositoryInterface $settingRepository)
+    {
+    }
+
+    public function get(string $key): ?array
+    {
+        return $this->settingRepository->find($key);
+    }
+
+    public function getValue(string $key): ?string
+    {
+        return $this->settingRepository->getValue($key);
+    }
+
+    public function getInt(string $key): ?int
+    {
+        $value = $this->settingRepository->getValue($key);
+        if ($value === null || $value === '') {
+            return null;
+        }
+
+        return (int) $value;
+    }
+
+    public function set(string $key, ?string $value, ?string $description = null): bool
+    {
+        return $this->settingRepository->set($key, $value, $description);
+    }
+}
diff --git a/lib/Service/Settings/SettingsMicrosoftGateway.php b/lib/Service/Settings/SettingsMicrosoftGateway.php
new file mode 100644
index 0000000..6e17167
--- /dev/null
+++ b/lib/Service/Settings/SettingsMicrosoftGateway.php
@@ -0,0 +1,100 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+class SettingsMicrosoftGateway
+{
+    public function __construct(
+        private readonly SettingsMetadataGateway $settingsMetadataGateway,
+        private readonly SettingsCryptoGatewayInterface $settingsCryptoGateway
+    ) {
+    }
+
+    public function getMicrosoftSharedClientId(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::MICROSOFT_SHARED_CLIENT_ID_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setMicrosoftSharedClientId(?string $clientId, ?string $description = null): bool
+    {
+        $value = $clientId !== null ? trim($clientId) : '';
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.microsoft_shared_client_id';
+        return $this->settingsMetadataGateway->set(SettingKeys::MICROSOFT_SHARED_CLIENT_ID_KEY, $value, $desc);
+    }
+
+    public function getMicrosoftSharedClientSecretEncrypted(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function getMicrosoftSharedClientSecret(): ?string
+    {
+        $encrypted = $this->getMicrosoftSharedClientSecretEncrypted();
+        if ($encrypted === null) {
+            return null;
+        }
+
+        try {
+            $decrypted = $this->settingsCryptoGateway->decryptString($encrypted);
+        } catch (\Throwable) {
+            return null;
+        }
+
+        $decrypted = trim($decrypted);
+        return $decrypted !== '' ? $decrypted : null;
+    }
+
+    public function setMicrosoftSharedClientSecret(?string $secret, ?string $description = null): bool
+    {
+        $value = $secret !== null ? trim($secret) : '';
+        if ($value === '') {
+            return $this->settingsMetadataGateway->set(
+                SettingKeys::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY,
+                null,
+                $description ?? 'setting.microsoft_shared_client_secret_enc'
+            );
+        }
+
+        try {
+            $encrypted = $this->settingsCryptoGateway->encryptString($value);
+        } catch (\Throwable) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.microsoft_shared_client_secret_enc';
+        return $this->settingsMetadataGateway->set(SettingKeys::MICROSOFT_SHARED_CLIENT_SECRET_ENC_KEY, $encrypted, $desc);
+    }
+
+    public function getMicrosoftAuthority(): string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::MICROSOFT_AUTHORITY_KEY);
+        $value = trim((string) ($value ?? ''));
+        if ($value === '') {
+            return 'https://login.microsoftonline.com/common/v2.0';
+        }
+
+        return rtrim($value, '/');
+    }
+
+    public function setMicrosoftAuthority(?string $authority, ?string $description = null): bool
+    {
+        $value = trim((string) ($authority ?? ''));
+        if ($value === '') {
+            $value = 'https://login.microsoftonline.com/common/v2.0';
+        }
+        if (!preg_match('#^https://#i', $value)) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.microsoft_authority';
+        return $this->settingsMetadataGateway->set(SettingKeys::MICROSOFT_AUTHORITY_KEY, rtrim($value, '/'), $desc);
+    }
+}
diff --git a/lib/Service/Settings/SettingsSmtpGateway.php b/lib/Service/Settings/SettingsSmtpGateway.php
new file mode 100644
index 0000000..6640c88
--- /dev/null
+++ b/lib/Service/Settings/SettingsSmtpGateway.php
@@ -0,0 +1,142 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+class SettingsSmtpGateway
+{
+    public function __construct(private readonly SettingsMetadataGateway $settingsMetadataGateway)
+    {
+    }
+
+    public function getSmtpHost(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_HOST_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setSmtpHost(?string $host, ?string $description = null): bool
+    {
+        $value = $host !== null ? trim($host) : '';
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.smtp_host';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_HOST_KEY, $value, $desc);
+    }
+
+    public function getSmtpPort(): ?int
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_PORT_KEY);
+        if ($value === null || $value === '') {
+            return null;
+        }
+
+        $port = (int) $value;
+        return $port > 0 ? $port : null;
+    }
+
+    public function setSmtpPort(?int $port, ?string $description = null): bool
+    {
+        $value = $port && $port > 0 ? (string) $port : null;
+        $desc = $description ?? 'setting.smtp_port';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_PORT_KEY, $value, $desc);
+    }
+
+    public function getSmtpUser(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_USER_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setSmtpUser(?string $user, ?string $description = null): bool
+    {
+        $value = $user !== null ? trim($user) : '';
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.smtp_user';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_USER_KEY, $value, $desc);
+    }
+
+    public function getSmtpPassword(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_PASSWORD_KEY);
+        $value = $value !== null ? (string) $value : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setSmtpPassword(?string $password, ?string $description = null): bool
+    {
+        $value = $password !== null ? (string) $password : '';
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.smtp_password';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_PASSWORD_KEY, $value, $desc);
+    }
+
+    public function getSmtpSecure(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_SECURE_KEY);
+        $value = $value !== null ? strtolower(trim($value)) : '';
+        if (!in_array($value, ['tls', 'ssl', 'none'], true)) {
+            return null;
+        }
+
+        return $value === 'none' ? null : $value;
+    }
+
+    public function setSmtpSecure(?string $secure, ?string $description = null): bool
+    {
+        $value = $secure !== null ? strtolower(trim($secure)) : '';
+        if ($value === '' || $value === 'none') {
+            $value = null;
+        } elseif (!in_array($value, ['tls', 'ssl'], true)) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.smtp_secure';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_SECURE_KEY, $value, $desc);
+    }
+
+    public function getSmtpFrom(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_FROM_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setSmtpFrom(?string $from, ?string $description = null): bool
+    {
+        $value = $from !== null ? trim($from) : '';
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.smtp_from';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_FROM_KEY, $value, $desc);
+    }
+
+    public function getSmtpFromName(): ?string
+    {
+        $value = $this->settingsMetadataGateway->getValue(SettingKeys::SMTP_FROM_NAME_KEY);
+        $value = $value !== null ? trim($value) : '';
+        return $value !== '' ? $value : null;
+    }
+
+    public function setSmtpFromName(?string $fromName, ?string $description = null): bool
+    {
+        $value = $fromName !== null ? trim($fromName) : '';
+        if ($value === '') {
+            $value = null;
+        }
+
+        $desc = $description ?? 'setting.smtp_from_name';
+        return $this->settingsMetadataGateway->set(SettingKeys::SMTP_FROM_NAME_KEY, $value, $desc);
+    }
+}
diff --git a/lib/Service/Settings/SettingsSystemAuditGateway.php b/lib/Service/Settings/SettingsSystemAuditGateway.php
new file mode 100644
index 0000000..6b22fb3
--- /dev/null
+++ b/lib/Service/Settings/SettingsSystemAuditGateway.php
@@ -0,0 +1,55 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+class SettingsSystemAuditGateway
+{
+    private const SYSTEM_AUDIT_ENABLED_FALLBACK = true;
+    private const SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK = 365;
+    private const SYSTEM_AUDIT_RETENTION_DAYS_MIN = 30;
+    private const SYSTEM_AUDIT_RETENTION_DAYS_MAX = 1095;
+
+    public function __construct(private readonly SettingsMetadataGateway $settingsMetadataGateway)
+    {
+    }
+
+    public function isSystemAuditEnabled(): bool
+    {
+        $value = strtolower(trim((string) ($this->settingsMetadataGateway->getValue(SettingKeys::SYSTEM_AUDIT_ENABLED_KEY) ?? '')));
+        if ($value === '') {
+            return self::SYSTEM_AUDIT_ENABLED_FALLBACK;
+        }
+
+        return in_array($value, ['1', 'true', 'yes', 'on'], true);
+    }
+
+    public function setSystemAuditEnabled(bool $enabled, ?string $description = null): bool
+    {
+        $desc = $description ?? 'setting.system_audit_enabled';
+        return $this->settingsMetadataGateway->set(SettingKeys::SYSTEM_AUDIT_ENABLED_KEY, $enabled ? '1' : '0', $desc);
+    }
+
+    public function getSystemAuditRetentionDays(): int
+    {
+        $value = $this->settingsMetadataGateway->getInt(SettingKeys::SYSTEM_AUDIT_RETENTION_DAYS_KEY);
+        if ($value === null) {
+            return self::SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK;
+        }
+        if ($value < self::SYSTEM_AUDIT_RETENTION_DAYS_MIN || $value > self::SYSTEM_AUDIT_RETENTION_DAYS_MAX) {
+            return self::SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK;
+        }
+
+        return $value;
+    }
+
+    public function setSystemAuditRetentionDays(?int $days, ?string $description = null): bool
+    {
+        $value = $days ?? self::SYSTEM_AUDIT_RETENTION_DAYS_FALLBACK;
+        if ($value < self::SYSTEM_AUDIT_RETENTION_DAYS_MIN || $value > self::SYSTEM_AUDIT_RETENTION_DAYS_MAX) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.system_audit_retention_days';
+        return $this->settingsMetadataGateway->set(SettingKeys::SYSTEM_AUDIT_RETENTION_DAYS_KEY, (string) $value, $desc);
+    }
+}
diff --git a/lib/Service/Settings/SettingsUserLifecycleGateway.php b/lib/Service/Settings/SettingsUserLifecycleGateway.php
new file mode 100644
index 0000000..ff55bd1
--- /dev/null
+++ b/lib/Service/Settings/SettingsUserLifecycleGateway.php
@@ -0,0 +1,80 @@
+<?php
+
+namespace MintyPHP\Service\Settings;
+
+class SettingsUserLifecycleGateway
+{
+    private const USER_INACTIVITY_DEACTIVATE_DAYS_FALLBACK = 180;
+    private const USER_INACTIVITY_DELETE_DAYS_FALLBACK = 365;
+    private const USER_INACTIVITY_DAYS_MIN = 0;
+    private const USER_INACTIVITY_DAYS_MAX = 3650;
+
+    public function __construct(private readonly SettingsMetadataGateway $settingsMetadataGateway)
+    {
+    }
+
+    public function getUserInactivityDeactivateDays(): int
+    {
+        $value = $this->settingsMetadataGateway->getInt(SettingKeys::USER_INACTIVITY_DEACTIVATE_DAYS_KEY);
+        if ($value !== null && $this->isValidInactivityDays($value)) {
+            return $value;
+        }
+
+        return self::USER_INACTIVITY_DEACTIVATE_DAYS_FALLBACK;
+    }
+
+    public function setUserInactivityDeactivateDays(?int $days, ?string $description = null): bool
+    {
+        $value = $days ?? self::USER_INACTIVITY_DEACTIVATE_DAYS_FALLBACK;
+        if (!$this->isValidInactivityDays($value)) {
+            return false;
+        }
+        if ($value === 0) {
+            $deleteUpdated = $this->settingsMetadataGateway->set(
+                SettingKeys::USER_INACTIVITY_DELETE_DAYS_KEY,
+                '0',
+                'setting.user_inactivity_delete_days'
+            );
+            if (!$deleteUpdated) {
+                return false;
+            }
+        }
+
+        $desc = $description ?? 'setting.user_inactivity_deactivate_days';
+        return $this->settingsMetadataGateway->set(SettingKeys::USER_INACTIVITY_DEACTIVATE_DAYS_KEY, (string) $value, $desc);
+    }
+
+    public function getUserInactivityDeleteDays(): int
+    {
+        $deactivateDays = $this->getUserInactivityDeactivateDays();
+        if ($deactivateDays <= 0) {
+            return 0;
+        }
+
+        $value = $this->settingsMetadataGateway->getInt(SettingKeys::USER_INACTIVITY_DELETE_DAYS_KEY);
+        if ($value !== null && $this->isValidInactivityDays($value)) {
+            return $value;
+        }
+
+        return self::USER_INACTIVITY_DELETE_DAYS_FALLBACK;
+    }
+
+    public function setUserInactivityDeleteDays(?int $days, ?string $description = null): bool
+    {
+        $value = $days ?? self::USER_INACTIVITY_DELETE_DAYS_FALLBACK;
+        if (!$this->isValidInactivityDays($value)) {
+            return false;
+        }
+        if ($value > 0 && $this->getUserInactivityDeactivateDays() <= 0) {
+            return false;
+        }
+
+        $desc = $description ?? 'setting.user_inactivity_delete_days';
+        return $this->settingsMetadataGateway->set(SettingKeys::USER_INACTIVITY_DELETE_DAYS_KEY, (string) $value, $desc);
+    }
+
+    private function isValidInactivityDays(int $days): bool
+    {
+        return $days >= self::USER_INACTIVITY_DAYS_MIN && $days <= self::USER_INACTIVITY_DAYS_MAX;
+    }
+}
diff --git a/lib/Service/Settings/ThemeConfigService.php b/lib/Service/Settings/ThemeConfigService.php
index 7757ef3..b72ebc8 100644
--- a/lib/Service/Settings/ThemeConfigService.php
+++ b/lib/Service/Settings/ThemeConfigService.php
@@ -39,6 +39,7 @@ class ThemeConfigService
             $clean[$themeKey] = $themeLabel;
         }
 
+        // Fall back to defaults if the file returns an empty or invalid list — system must always have themes.
         $this->themes = $clean ?: self::DEFAULT_THEMES;
         return $this->themes;
     }
diff --git a/lib/Service/Tenant/TenantScopeService.php b/lib/Service/Tenant/TenantScopeService.php
index 2af9688..89cd31b 100644
--- a/lib/Service/Tenant/TenantScopeService.php
+++ b/lib/Service/Tenant/TenantScopeService.php
@@ -18,6 +18,7 @@ class TenantScopeService
     ) {
     }
 
+    // Strict mode is the default — permissive mode must be explicitly enabled via the constant.
     public function isStrict(): bool
     {
         return defined('TENANT_SCOPE_STRICT') ? (bool) TENANT_SCOPE_STRICT : true;
@@ -60,9 +61,11 @@ class TenantScopeService
         $resourceTenantIds = $this->filterActiveTenantIds($resourceTenantIdsRaw);
         $userTenantIds = $this->filterActiveTenantIds($userTenantIdsRaw);
 
+        // Resource had tenants, but all are inactive — deny access rather than treating it as unscoped.
         if ($resourceTenantIdsRaw && !$resourceTenantIds) {
             return false;
         }
+        // Resource has no tenant assignment — allow in permissive mode, deny in strict mode.
         if (!$resourceTenantIds) {
             return $this->isStrict() ? false : true;
         }
diff --git a/lib/Service/Tenant/TenantService.php b/lib/Service/Tenant/TenantService.php
index 5757bb8..3687f70 100644
--- a/lib/Service/Tenant/TenantService.php
+++ b/lib/Service/Tenant/TenantService.php
@@ -49,6 +49,7 @@ class TenantService
             return ['ok' => false, 'errors' => $errors, 'form' => $form];
         }
 
+        // Always UTC — consistency across server timezone changes.
         $statusChangedAt = gmdate('Y-m-d H:i:s');
         $createdId = $this->tenantRepository->create([
             'description' => $form['description'],
@@ -68,6 +69,7 @@ class TenantService
             'website' => $form['website'],
             'privacy_url' => $form['privacy_url'],
             'imprint_url' => $form['imprint_url'],
+            // null means "inherit from global settings" for color, theme, and theme-toggle policy.
             'primary_color' => $form['primary_color_use_default']
                 ? null
                 : ($form['primary_color'] !== '' ? $form['primary_color'] : null),
@@ -182,6 +184,7 @@ class TenantService
         }
 
         $tenantId = (int) $tenant['id'];
+        // Block deletion if departments exist — orphaned departments would break user assignments.
         if ($this->departmentRepository->countByTenantId($tenantId) > 0) {
             return ['ok' => false, 'status' => 409, 'error' => 'tenant_has_departments'];
         }
diff --git a/lib/Service/User/UserAccessPdfService.php b/lib/Service/User/UserAccessPdfService.php
index f16db00..d716f5a 100644
--- a/lib/Service/User/UserAccessPdfService.php
+++ b/lib/Service/User/UserAccessPdfService.php
@@ -143,13 +143,6 @@ class UserAccessPdfService
         if (!is_file($htmlFooterPath)) {
             $htmlFooterPath = $emailBase . '/' . $locale . '/partials/footer.html';
         }
-        if (!is_file($htmlHeaderPath)) {
-            $htmlHeaderPath = $emailBase . '/partials/header.html';
-        }
-        if (!is_file($htmlFooterPath)) {
-            $htmlFooterPath = $emailBase . '/partials/footer.html';
-        }
-
         $html = (string) file_get_contents($htmlPath);
         if (!isset($vars['email_header'])) {
             $vars['email_header'] = is_file($htmlHeaderPath) ? (string) file_get_contents($htmlHeaderPath) : '';
diff --git a/lib/Service/User/UserAccountService.php b/lib/Service/User/UserAccountService.php
index 4b8e4d6..a307bf1 100644
--- a/lib/Service/User/UserAccountService.php
+++ b/lib/Service/User/UserAccountService.php
@@ -25,6 +25,7 @@ class UserAccountService
 
     public function listPaged(array $options): array
     {
+        // Users with global tenant scope see all tenants — remove the filter so the query isn't restricted.
         if (!empty($options['tenantUserId'])) {
             $tenantUserId = (int) $options['tenantUserId'];
             if ($tenantUserId > 0 && $this->scopeGateway->hasGlobalAccess($tenantUserId)) {
@@ -704,6 +705,7 @@ class UserAccountService
         if ($primaryTenantId === 0 && count($tenantIds) > 1) {
             return [0, [t('Please select a primary tenant')]];
         }
+        // Single tenant assigned → auto-select it as primary to avoid requiring the user to pick.
         if ($primaryTenantId === 0 && count($tenantIds) === 1) {
             return [(int) $tenantIds[0], []];
         }
diff --git a/lib/Service/User/UserAssignmentService.php b/lib/Service/User/UserAssignmentService.php
index eea112a..1a072ad 100644
--- a/lib/Service/User/UserAssignmentService.php
+++ b/lib/Service/User/UserAssignmentService.php
@@ -218,6 +218,7 @@ class UserAssignmentService
         return $result;
     }
 
+    // Incrementing authz_version causes the session to be re-checked on the user's next request.
     public function bumpAuthzVersion(int $userId): void
     {
         if ($userId <= 0) {
@@ -237,6 +238,7 @@ class UserAssignmentService
             $this->databaseSessionRepository->beginTransaction();
             $transactionStarted = true;
 
+            // bumpAuthz=false on each sync — bump once at the end to avoid redundant DB writes.
             $ok = $this->syncTenants($userId, $tenantIds, false)
                 && $this->syncRoles($userId, $roleIds, false)
                 && $this->syncDepartments($userId, $departmentIds, false);
@@ -258,6 +260,7 @@ class UserAssignmentService
         }
     }
 
+    // Accepts arrays, comma-separated strings, and nested arrays — normalizes to a flat list of IDs.
     public function normalizeIdInput($value): array
     {
         $raw = is_array($value) ? $value : [$value];
diff --git a/lib/Service/User/UserAvatarService.php b/lib/Service/User/UserAvatarService.php
index c5f24dc..ae352cf 100644
--- a/lib/Service/User/UserAvatarService.php
+++ b/lib/Service/User/UserAvatarService.php
@@ -101,6 +101,7 @@ class UserAvatarService
         if (!$ext) {
             return ['ok' => false, 'error' => t('Invalid image file')];
         }
+        // SVG can contain JavaScript — reject files that don't pass the safety check.
         if ($isSvg && !self::imageIsSafeSvg($tmpPath)) {
             return ['ok' => false, 'error' => t('Invalid image file')];
         }
@@ -117,6 +118,7 @@ class UserAvatarService
         }
         @chmod($originalPath, 0644);
 
+        // Prefer WebP for variants (better compression); fall back to JPEG if GD lacks WebP support.
         $variantExt = function_exists('imagewebp') ? 'webp' : 'jpg';
         if (!$isSvg && self::imageCanResize()) {
             foreach (self::SIZES as $size) {
@@ -172,6 +174,7 @@ class UserAvatarService
 
         $this->delete($uuid);
         $originalPath = $dir . '/original.' . $ext;
+        // rename() fails across filesystem boundaries (e.g. /tmp → app storage), fall back to copy.
         if (!@rename($tmpPath, $originalPath)) {
             if (!@copy($tmpPath, $originalPath)) {
                 @unlink($tmpPath);
diff --git a/lib/Service/User/UserGatewayFactory.php b/lib/Service/User/UserGatewayFactory.php
index 81b0107..ce48886 100644
--- a/lib/Service/User/UserGatewayFactory.php
+++ b/lib/Service/User/UserGatewayFactory.php
@@ -5,13 +5,17 @@ namespace MintyPHP\Service\User;
 use MintyPHP\Service\Access\AccessServicesFactory;
 use MintyPHP\Service\Access\PermissionGateway;
 use MintyPHP\Service\Directory\DirectoryRepositoryFactory;
-use MintyPHP\Service\Settings\SettingGateway;
 use MintyPHP\Service\Settings\SettingServicesFactory;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsUserLifecycleGateway;
 use MintyPHP\Service\Tenant\TenantScopeService;
 
 class UserGatewayFactory
 {
-    private ?SettingGateway $settingGateway = null;
+    private ?SettingsDefaultsGateway $settingsDefaultsGateway = null;
+    private ?SettingsAppGateway $settingsAppGateway = null;
+    private ?SettingsUserLifecycleGateway $settingsUserLifecycleGateway = null;
     private ?PermissionGateway $permissionGateway = null;
     private ?UserSettingsGateway $userSettingsGateway = null;
     private ?UserScopeGateway $userScopeGateway = null;
@@ -28,7 +32,11 @@ class UserGatewayFactory
 
     public function createUserSettingsGateway(): UserSettingsGateway
     {
-        return $this->userSettingsGateway ??= new UserSettingsGateway($this->createSettingGateway());
+        return $this->userSettingsGateway ??= new UserSettingsGateway(
+            $this->createSettingsDefaultsGateway(),
+            $this->createSettingsAppGateway(),
+            $this->createSettingsUserLifecycleGateway()
+        );
     }
 
     public function createUserScopeGateway(): UserScopeGateway
@@ -55,8 +63,18 @@ class UserGatewayFactory
         return $this->permissionGateway ??= $this->accessServicesFactory->createPermissionGateway();
     }
 
-    private function createSettingGateway(): SettingGateway
+    private function createSettingsDefaultsGateway(): SettingsDefaultsGateway
     {
-        return $this->settingGateway ??= $this->settingServicesFactory->createSettingGateway();
+        return $this->settingsDefaultsGateway ??= $this->settingServicesFactory->createSettingsDefaultsGateway();
+    }
+
+    private function createSettingsAppGateway(): SettingsAppGateway
+    {
+        return $this->settingsAppGateway ??= $this->settingServicesFactory->createSettingsAppGateway();
+    }
+
+    private function createSettingsUserLifecycleGateway(): SettingsUserLifecycleGateway
+    {
+        return $this->settingsUserLifecycleGateway ??= $this->settingServicesFactory->createSettingsUserLifecycleGateway();
     }
 }
diff --git a/lib/Service/User/UserLifecycleService.php b/lib/Service/User/UserLifecycleService.php
index bac2795..da00f5f 100644
--- a/lib/Service/User/UserLifecycleService.php
+++ b/lib/Service/User/UserLifecycleService.php
@@ -34,6 +34,7 @@ class UserLifecycleService
             $deleteDays = 0;
         }
 
+        // Exclude admins with settings/tenant management rights — they must be deactivated manually.
         $privilegedUserIds = $this->userReadRepository->listPrivilegedUserIdsByPermissionKeys([
             PermissionService::SETTINGS_UPDATE,
             PermissionService::TENANTS_UPDATE,
@@ -55,6 +56,7 @@ class UserLifecycleService
             'duration_ms' => 0,
         ];
 
+        // Advisory lock prevents concurrent runs (e.g. cron and a manual trigger at the same time).
         if (!$this->acquireLock()) {
             $result['ok'] = false;
             $result['locked'] = true;
diff --git a/lib/Service/User/UserPasswordPolicyService.php b/lib/Service/User/UserPasswordPolicyService.php
index 1c5e5f6..aee2e03 100644
--- a/lib/Service/User/UserPasswordPolicyService.php
+++ b/lib/Service/User/UserPasswordPolicyService.php
@@ -61,6 +61,7 @@ class UserPasswordPolicyService
         return self::PASSWORD_MIN_LENGTH;
     }
 
+    // Wrapper so this service can be used in tests before the t() helper is loaded.
     private function translate(string $text, mixed ...$args): string
     {
         if (function_exists('t')) {
diff --git a/lib/Service/User/UserSettingsGateway.php b/lib/Service/User/UserSettingsGateway.php
index b37658c..9f92ab2 100644
--- a/lib/Service/User/UserSettingsGateway.php
+++ b/lib/Service/User/UserSettingsGateway.php
@@ -2,41 +2,46 @@
 
 namespace MintyPHP\Service\User;
 
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsUserLifecycleGateway;
 
 class UserSettingsGateway
 {
-    public function __construct(private readonly SettingGateway $settingGateway)
-    {
+    public function __construct(
+        private readonly SettingsDefaultsGateway $settingsDefaultsGateway,
+        private readonly SettingsAppGateway $settingsAppGateway,
+        private readonly SettingsUserLifecycleGateway $settingsUserLifecycleGateway
+    ) {
     }
 
     public function getDefaultTenantId(): ?int
     {
-        return $this->settingGateway->getDefaultTenantId();
+        return $this->settingsDefaultsGateway->getDefaultTenantId();
     }
 
     public function getDefaultRoleId(): ?int
     {
-        return $this->settingGateway->getDefaultRoleId();
+        return $this->settingsDefaultsGateway->getDefaultRoleId();
     }
 
     public function getDefaultDepartmentId(): ?int
     {
-        return $this->settingGateway->getDefaultDepartmentId();
+        return $this->settingsDefaultsGateway->getDefaultDepartmentId();
     }
 
     public function getAppTheme(): ?string
     {
-        return $this->settingGateway->getAppTheme();
+        return $this->settingsAppGateway->getAppTheme();
     }
 
     public function getUserInactivityDeactivateDays(): int
     {
-        return $this->settingGateway->getUserInactivityDeactivateDays();
+        return $this->settingsUserLifecycleGateway->getUserInactivityDeactivateDays();
     }
 
     public function getUserInactivityDeleteDays(): int
     {
-        return $this->settingGateway->getUserInactivityDeleteDays();
+        return $this->settingsUserLifecycleGateway->getUserInactivityDeleteDays();
     }
 }
diff --git a/lib/Service/User/UserTenantContextService.php b/lib/Service/User/UserTenantContextService.php
index 6ae2767..cd6eb58 100644
--- a/lib/Service/User/UserTenantContextService.php
+++ b/lib/Service/User/UserTenantContextService.php
@@ -32,6 +32,7 @@ class UserTenantContextService
             return null;
         }
 
+        // Priority: last-used tenant → primary tenant → first available.
         $currentTenantId = (int) ($user['current_tenant_id'] ?? 0);
         if ($currentTenantId > 0 && in_array($currentTenantId, $activeTenantIds, true)) {
             return $currentTenantId;
diff --git a/lib/Support/Crypto.php b/lib/Support/Crypto.php
index 2781efa..0ef8784 100644
--- a/lib/Support/Crypto.php
+++ b/lib/Support/Crypto.php
@@ -2,6 +2,8 @@
 
 namespace MintyPHP\Support;
 
+// AES-256-GCM encryption/decryption for sensitive stored values (e.g. SSO secrets).
+// Requires APP_CRYPTO_KEY — see EnvValidator for accepted key formats.
 class Crypto
 {
     private const CIPHER = 'aes-256-gcm';
@@ -33,6 +35,8 @@ class Crypto
             throw new \RuntimeException('Encryption failed');
         }
 
+        // Outer base64 wraps a JSON object with v (version), iv, auth tag, and ciphertext —
+        // all inner binary values are base64url-encoded to stay JSON-safe.
         $payload = json_encode([
             'v' => 1,
             'iv' => self::base64UrlEncode($iv),
@@ -94,6 +98,7 @@ class Crypto
             return null;
         }
 
+        // Accepts 64-char hex (32 bytes) or base64-encoded 32 bytes — both yield a 256-bit key.
         $hex = preg_match('/^[0-9a-f]{64}$/i', $raw) ? hex2bin($raw) : false;
         if (is_string($hex) && strlen($hex) === 32) {
             return $hex;
@@ -107,6 +112,7 @@ class Crypto
         return null;
     }
 
+    // URL-safe base64: replaces +/ with -_ and strips = padding.
     private static function base64UrlEncode(string $value): string
     {
         return rtrim(strtr(base64_encode($value), '+/', '-_'), '=');
diff --git a/lib/Support/Flash.php b/lib/Support/Flash.php
index c79d3a3..72d434f 100644
--- a/lib/Support/Flash.php
+++ b/lib/Support/Flash.php
@@ -4,6 +4,7 @@ namespace MintyPHP\Support;
 
 use MintyPHP\Session;
 
+// Session-based flash message store. Messages are written before a redirect and consumed on the next page.
 class Flash
 {
     private const SESSION_KEY = 'flash_messages';
@@ -19,6 +20,7 @@ class Flash
         }
     }
 
+    // If a key is given, any existing message with the same key+scope is replaced — prevents duplicate notices.
     public static function add(string $type, string $message, ?string $scope = null, ?string $key = null): string
     {
         self::ensureSession();
@@ -93,6 +95,7 @@ class Flash
         }
     }
 
+    // Prevents messages from being cleared on the next render — useful when a redirect chain crosses multiple pages.
     public static function keep(int $times = 1)
     {
         self::ensureSession();
diff --git a/lib/Support/Guard.php b/lib/Support/Guard.php
index 3b7fae9..4a1537a 100644
--- a/lib/Support/Guard.php
+++ b/lib/Support/Guard.php
@@ -9,8 +9,11 @@ use MintyPHP\Service\Access\AuthorizationService;
 use MintyPHP\Service\Auth\AuthService;
 use MintyPHP\Service\Tenant\TenantService;
 
+// Session-based web auth guard. Enforces login and RBAC for page actions.
+// For API token authentication, see ApiAuth instead.
 class Guard
 {
+    // Re-check tenant assignment at most once per minute to pick up permission changes without re-login.
     private const TENANT_REFRESH_INTERVAL = 60;
     /** @var (callable(): AuthService)|null */
     private static $authServiceResolver = null;
@@ -56,7 +59,7 @@ class Guard
             return;
         }
 
-        // Current tenant was deleted, refresh session data
+        // Current tenant was deleted — reload session so the user is switched to another active tenant or logged out.
         $userId = (int) ($_SESSION['user']['id'] ?? 0);
         if ($userId > 0) {
             self::authService()->loadTenantDataIntoSession($userId);
@@ -106,6 +109,7 @@ class Guard
             ...$context,
         ]);
         if (!$decision->isAllowed()) {
+            // JSON requests get a 403/404 response body; browser requests get a redirect to the forbidden page.
             if (Request::wantsJson()) {
                 http_response_code($decision->status());
                 header('Content-Type: application/json; charset=utf-8');
diff --git a/lib/Support/Search/SearchQueryNormalizer.php b/lib/Support/Search/SearchQueryNormalizer.php
index 7ff7bf7..773bd16 100644
--- a/lib/Support/Search/SearchQueryNormalizer.php
+++ b/lib/Support/Search/SearchQueryNormalizer.php
@@ -4,6 +4,8 @@ namespace MintyPHP\Support\Search;
 
 class SearchQueryNormalizer
 {
+    // Prepares a user query for SQL LIKE. Escapes \ and _ (LIKE special chars),
+    // converts * to %, and wraps with % wildcards if not already present.
     public static function normalizeLikeQuery(string $query): string
     {
         $query = trim($query);
@@ -25,6 +27,7 @@ class SearchQueryNormalizer
         return $query;
     }
 
+    // Strips wildcard chars for relevance scoring — score queries need a clean term, not a LIKE pattern.
     public static function normalizeScoreQuery(string $query): string
     {
         $query = trim($query);
diff --git a/lib/Support/Search/SearchSpecialResourceProvider.php b/lib/Support/Search/SearchSpecialResourceProvider.php
index 512ec9f..683a908 100644
--- a/lib/Support/Search/SearchSpecialResourceProvider.php
+++ b/lib/Support/Search/SearchSpecialResourceProvider.php
@@ -28,6 +28,8 @@ class SearchSpecialResourceProvider
         return $rows;
     }
 
+    // Two-tier match: first checks against the hotkey service's keyword list (e.g. "shortcut", "keyboard"),
+    // then falls back to substring matching against individual entry labels/key combos.
     private static function matchesHotkeyQueryWith(string $query, array $entries): bool
     {
         $query = trim(mb_strtolower($query));
@@ -222,6 +224,7 @@ class SearchSpecialResourceProvider
                 $descriptionParts[] = $snippet;
             }
 
+            // Map raw doc scores (0–1000+) to coarser search_score buckets for result ranking.
             $rawScore = (int) $match['score'];
             $searchScore = match (true) {
                 $rawScore >= 1000 => 400,
diff --git a/lib/Support/Search/SearchSqlResourceProvider.php b/lib/Support/Search/SearchSqlResourceProvider.php
index b573fc8..f5cd5d2 100644
--- a/lib/Support/Search/SearchSqlResourceProvider.php
+++ b/lib/Support/Search/SearchSqlResourceProvider.php
@@ -4,6 +4,8 @@ namespace MintyPHP\Support\Search;
 
 use MintyPHP\Service\Access\PermissionService;
 
+// Defines all SQL-backed search resources. Each resource declares count/preview/result queries
+// with a {{tenantFilter}} placeholder that is substituted at query time based on the user's tenant scope.
 class SearchSqlResourceProvider
 {
     public static function tenantScopeFilters(): array
@@ -25,6 +27,7 @@ class SearchSqlResourceProvider
                 'key' => 'address-book',
                 'label' => t('Address book'),
                 'permission' => PermissionService::ADDRESS_BOOK_VIEW,
+                // escape '\\\\' — four backslashes: PHP reduces to two, SQL reduces to one literal backslash escape char.
                 'countSql' => "select count(*) from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}}",
                 'countParams' => [$like, $like, $like],
                 'previewSql' => "select uuid, first_name, last_name, email from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}} order by last_name, first_name limit ?",
diff --git a/lib/Support/helpers/app.php b/lib/Support/helpers/app.php
index a2294a4..934e510 100644
--- a/lib/Support/helpers/app.php
+++ b/lib/Support/helpers/app.php
@@ -42,7 +42,7 @@ function setAppContainer(\MintyPHP\App\AppContainer $container): void
 
     \MintyPHP\Http\ApiBootstrap::configure(
         static fn (): \MintyPHP\Service\Audit\ApiAuditService => $container->get(\MintyPHP\Service\Audit\ApiAuditService::class),
-        static fn (): \MintyPHP\Service\Settings\SettingGateway => $container->get(\MintyPHP\Service\Settings\SettingGateway::class),
+        static fn (): \MintyPHP\Service\Settings\SettingsApiPolicyGateway => $container->get(\MintyPHP\Service\Settings\SettingsApiPolicyGateway::class),
         static fn (): \MintyPHP\Service\Security\RateLimiterService => $container->get(\MintyPHP\Service\Security\RateLimiterService::class),
         static fn (): \MintyPHP\Http\ApiSystemAuditReporter => $container->get(\MintyPHP\Http\ApiSystemAuditReporter::class)
     );
@@ -290,6 +290,66 @@ function allowRegistration(): bool
     return in_array(strtolower($value), ['1', 'true', 'yes', 'on'], true);
 }
 
+/**
+ * Feature flag: allow frontend telemetry events.
+ */
+function frontendTelemetryEnabled(): bool
+{
+    $value = appSetting('frontend_telemetry_enabled');
+    if ($value === null || $value === '') {
+        return false;
+    }
+    return in_array(strtolower(trim($value)), ['1', 'true', 'yes', 'on'], true);
+}
+
+/**
+ * Frontend telemetry sample rate normalized to 0..1.
+ */
+function frontendTelemetrySampleRate(): float
+{
+    $value = appSetting('frontend_telemetry_sample_rate');
+    if ($value === null || trim($value) === '') {
+        return 0.2;
+    }
+
+    $rate = is_numeric($value) ? (float) $value : NAN;
+    if (!is_finite($rate) || $rate < 0 || $rate > 1) {
+        return 0.2;
+    }
+
+    return $rate;
+}
+
+/**
+ * Allowed frontend telemetry events as canonical short keys.
+ *
+ * @return list<string>
+ */
+function frontendTelemetryAllowedEvents(): array
+{
+    $allowed = ['warn_once', 'ajax_error'];
+    $value = appSetting('frontend_telemetry_allowed_events');
+    if ($value === null || trim($value) === '') {
+        return $allowed;
+    }
+
+    $items = preg_split('/[\s,]+/', strtolower(trim($value))) ?: [];
+    $normalized = array_values(array_unique(array_filter(
+        array_map(
+            static fn ($entry): string => trim((string) $entry),
+            $items
+        ),
+        static fn ($entry): bool => in_array($entry, $allowed, true)
+    )));
+
+    if ($normalized === []) {
+        return $allowed;
+    }
+
+    sort($normalized, SORT_STRING);
+    return $normalized;
+}
+
 /**
  * Resolve active primary color (tenant override -> app setting).
  */
diff --git a/pages/admin/departments/data().php b/pages/admin/departments/data().php
index 4faaa30..3ff39ed 100644
--- a/pages/admin/departments/data().php
+++ b/pages/admin/departments/data().php
@@ -25,8 +25,8 @@ $result = app(\MintyPHP\Service\Org\DepartmentService::class)->listPaged([
     'tenantUserId' => $currentUserId,
 ]);
 
-$settingGateway = app(\MintyPHP\Service\Settings\SettingGateway::class);
-$defaultDepartmentId = $settingGateway->getDefaultDepartmentId();
+$settingsDefaultsGateway = app(\MintyPHP\Service\Settings\SettingsDefaultsGateway::class);
+$defaultDepartmentId = $settingsDefaultsGateway->getDefaultDepartmentId();
 $departmentIds = [];
 foreach ($result['rows'] as $departmentRow) {
     $departmentId = (int) ($departmentRow['id'] ?? 0);
diff --git a/pages/admin/frontend-telemetry/ingest().php b/pages/admin/frontend-telemetry/ingest().php
new file mode 100644
index 0000000..d0fe888
--- /dev/null
+++ b/pages/admin/frontend-telemetry/ingest().php
@@ -0,0 +1,107 @@
+<?php
+
+use MintyPHP\Http\RequestContext;
+use MintyPHP\Http\SessionStoreInterface;
+use MintyPHP\Router;
+use MintyPHP\Session;
+use MintyPHP\Service\Audit\FrontendTelemetryIngestService;
+
+if ((requestInput()->method()) !== 'POST') {
+    http_response_code(405);
+    Router::json(['ok' => false, 'error' => 'method_not_allowed']);
+    return;
+}
+
+$sessionStore = app(SessionStoreInterface::class);
+$session = $sessionStore->all();
+$currentUserId = (int) ($session['user']['id'] ?? 0);
+if ($currentUserId <= 0) {
+    http_response_code(403);
+    Router::json(['ok' => false, 'error' => 'forbidden']);
+    return;
+}
+
+if (!Session::checkCsrfToken()) {
+    http_response_code(403);
+    Router::json(['ok' => false, 'error' => 'csrf']);
+    return;
+}
+
+$body = requestInput()->bodyAll();
+if (!is_array($body)) {
+    http_response_code(204);
+    return;
+}
+
+$allowedKeys = ['event_type', 'severity', 'message', 'fingerprint', 'meta', 'occurred_at'];
+$csrfKey = Session::$csrfSessionKey;
+foreach ($body as $key => $value) {
+    if (!is_string($key)) {
+        continue;
+    }
+
+    if ($key === $csrfKey) {
+        continue;
+    }
+
+    if (!in_array($key, $allowedKeys, true)) {
+        http_response_code(204);
+        return;
+    }
+}
+
+$payload = [];
+foreach ($allowedKeys as $key) {
+    if (!array_key_exists($key, $body)) {
+        continue;
+    }
+    $payload[$key] = $body[$key];
+}
+
+$eventType = $payload['event_type'] ?? null;
+$severity = $payload['severity'] ?? null;
+$message = $payload['message'] ?? null;
+$fingerprint = $payload['fingerprint'] ?? null;
+$meta = $payload['meta'] ?? null;
+$occurredAt = $payload['occurred_at'] ?? null;
+
+if (($eventType !== null && is_array($eventType))
+    || ($severity !== null && is_array($severity))
+    || ($message !== null && is_array($message))
+    || ($fingerprint !== null && is_array($fingerprint))
+    || ($occurredAt !== null && is_array($occurredAt))
+    || ($meta !== null && !is_array($meta) && !is_string($meta))
+) {
+    http_response_code(204);
+    return;
+}
+
+$eventTypeLength = strlen((string) $eventType);
+$severityLength = strlen((string) $severity);
+$messageLength = strlen((string) $message);
+$fingerprintLength = strlen((string) $fingerprint);
+$occurredAtLength = strlen((string) $occurredAt);
+$metaLength = is_string($meta) ? strlen($meta) : 0;
+
+if ($eventTypeLength > 64
+    || $severityLength > 16
+    || $messageLength > 1000
+    || $fingerprintLength > 256
+    || $occurredAtLength > 64
+    || $metaLength > 2048
+) {
+    http_response_code(204);
+    return;
+}
+
+$payloadSize = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+if (is_string($payloadSize) && strlen($payloadSize) > 4096) {
+    http_response_code(204);
+    return;
+}
+
+$result = app(FrontendTelemetryIngestService::class)->ingest($payload);
+if (!(bool) ($result['accepted'] ?? false) && (string) ($result['reason'] ?? '') === 'record_failed') {
+    error_log('[frontend-telemetry] ingest record_failed request_id=' . RequestContext::id());
+}
+http_response_code(204);
diff --git a/pages/admin/roles/data().php b/pages/admin/roles/data().php
index 4de5d3b..294aa4c 100644
--- a/pages/admin/roles/data().php
+++ b/pages/admin/roles/data().php
@@ -19,8 +19,8 @@ $result = app(\MintyPHP\Service\Access\RoleService::class)->listPaged([
     'active' => $filters['active'],
 ]);
 
-$settingGateway = app(\MintyPHP\Service\Settings\SettingGateway::class);
-$defaultRoleId = $settingGateway->getDefaultRoleId();
+$settingsDefaultsGateway = app(\MintyPHP\Service\Settings\SettingsDefaultsGateway::class);
+$defaultRoleId = $settingsDefaultsGateway->getDefaultRoleId();
 $rolePermissionRepository = app(\MintyPHP\Repository\Access\RolePermissionRepository::class);
 $roleIds = [];
 foreach ($result['rows'] as $roleRow) {
diff --git a/pages/admin/settings/index(default).phtml b/pages/admin/settings/index(default).phtml
index abee107..74e66a2 100644
--- a/pages/admin/settings/index(default).phtml
+++ b/pages/admin/settings/index(default).phtml
@@ -29,6 +29,23 @@ $userInactivityDeleteDays = (int) ($values['user_inactivity_delete_days'] ?? 365
 $apiCorsAllowedOrigins = (string) ($values['api_cors_allowed_origins'] ?? '');
 $systemAuditEnabled = !empty($values['system_audit_enabled']);
 $systemAuditRetentionDays = (int) ($values['system_audit_retention_days'] ?? 365);
+$frontendTelemetryEnabled = !empty($values['frontend_telemetry_enabled']);
+$frontendTelemetrySampleRate = (string) ($values['frontend_telemetry_sample_rate'] ?? '0.2');
+$frontendTelemetrySampleRateOptions = ['0.1', '0.2', '0.5', '1'];
+if (!in_array($frontendTelemetrySampleRate, $frontendTelemetrySampleRateOptions, true)) {
+  $frontendTelemetrySampleRate = '0.2';
+}
+$frontendTelemetryAllowedEvents = $values['frontend_telemetry_allowed_events'] ?? ['warn_once', 'ajax_error'];
+if (!is_array($frontendTelemetryAllowedEvents)) {
+  $frontendTelemetryAllowedEvents = preg_split('/[\s,]+/', (string) $frontendTelemetryAllowedEvents) ?: [];
+}
+$frontendTelemetryAllowedEvents = array_values(array_unique(array_filter(array_map(
+  static fn($entry): string => strtolower(trim((string) $entry)),
+  $frontendTelemetryAllowedEvents
+))));
+if ($frontendTelemetryAllowedEvents === []) {
+  $frontendTelemetryAllowedEvents = ['warn_once', 'ajax_error'];
+}
 $appPrimaryColor = (string) ($values['app_primary_color'] ?? '');
 $microsoftSharedClientId = (string) ($values['microsoft_shared_client_id'] ?? '');
 $microsoftAuthority = (string) ($values['microsoft_authority'] ?? '');
@@ -108,6 +125,7 @@ $disabledAttr = $isReadOnly ? 'disabled' : '';
           <button type="button" data-tab="master-data" data-tab-default><?php e(t('Master data')); ?></button>
           <button type="button" data-tab="appearance"><?php e(t('Appearance')); ?></button>
           <button type="button" data-tab="security"><?php e(t('Security')); ?></button>
+          <button type="button" data-tab="telemetry"><?php e(t('Telemetry')); ?></button>
           <button type="button" data-tab="email"><?php e(t('Email')); ?></button>
           <button type="button" data-tab="api"><?php e(t('API')); ?></button>
           <button type="button" data-tab="integrations"><?php e(t('Microsoft SSO')); ?></button>
@@ -261,200 +279,255 @@ $disabledAttr = $isReadOnly ? 'disabled' : '';
 
         <div data-tab-panel="security">
           <fieldset>
-              <legend>
-                <small>
-                  <?php e(t($appRegistrationDesc)); ?>
-                </small>
-              </legend>
+            <legend>
+              <small>
+                <?php e(t($appRegistrationDesc)); ?>
+              </small>
+            </legend>
+            <label class="app-field">
+              <input type="checkbox" name="app_registration" value="1" <?php e($appRegistration ? 'checked' : ''); ?>
+                <?php e($disabledAttr); ?>>
+              <span><?php e(t('Allow registration')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
+            </label>
+          </fieldset>
+          <hr>
+          <fieldset>
+            <legend><small><?php e(t('User lifecycle policy')); ?></small></legend>
+            <div class="grid">
               <label class="app-field">
-                <input type="checkbox" name="app_registration" value="1" <?php e($appRegistration ? 'checked' : ''); ?>
-                  <?php e($disabledAttr); ?>>
-                <span><?php e(t('Allow registration')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
+                <span><?php e(t('Deactivate users after inactivity (days)')); ?></span>
+                <input type="number" name="user_inactivity_deactivate_days"
+                  value="<?php e((string) $userInactivityDeactivateDays); ?>" min="0" max="3650" step="1"
+                  <?php e($readonlyAttr); ?>>
+                <small><?php e(t($userInactivityDeactivateDaysDesc)); ?></small>
               </label>
-            </fieldset>
+              <label class="app-field">
+                <span><?php e(t('Delete inactive users after (days)')); ?></span>
+                <input type="number" name="user_inactivity_delete_days"
+                  value="<?php e((string) $userInactivityDeleteDays); ?>" min="0" max="3650" step="1"
+                  <?php e($readonlyAttr); ?>>
+                <small><?php e(t($userInactivityDeleteDaysDesc)); ?></small>
+              </label>
+            </div>
+            <small class="muted"><?php e(t('0 disables this rule')); ?></small>
+            <small class="muted"><?php e(t('Deletion starts after user was set inactive')); ?></small>
+            <small class="muted"><?php e(t('Privileged admins are excluded from automatic lifecycle actions')); ?></small>
+            <?php if ($canUpdateSettings): ?>
+              <hr>
+              <button type="submit" class="outline warning" formnovalidate
+                formaction="admin/settings/run-user-lifecycle"
+                formmethod="post"
+                data-detail-confirm-message="<?php e(t('Run user lifecycle now?')); ?>"
+                data-detail-action-kind="danger">
+                <?php e(t('Run user lifecycle now')); ?>
+              </button>
+            <?php endif; ?>
+          </fieldset>
+          <hr>
+          <fieldset>
+            <legend><small><?php e(t('System audit')); ?></small></legend>
+            <label class="app-field">
+              <input type="checkbox" name="system_audit_enabled" value="1" <?php e($systemAuditEnabled ? 'checked' : ''); ?> <?php e($disabledAttr); ?>>
+              <span><?php e(t('Enable system audit log')); ?></span>
+              <small><?php e(t($systemAuditEnabledDesc)); ?></small>
+            </label>
+            <label class="app-field">
+              <span><?php e(t('Retention (days)')); ?></span>
+              <input
+                type="number"
+                name="system_audit_retention_days"
+                value="<?php e((string) $systemAuditRetentionDays); ?>"
+                min="30"
+                max="1095"
+                step="1"
+                <?php e($readonlyAttr); ?>>
+              <small><?php e(t($systemAuditRetentionDaysDesc)); ?></small>
+            </label>
+          </fieldset>
+        </div>
+
+        <div data-tab-panel="telemetry">
+          <blockquote data-variant="info">
+            <?php e(t('Telemetry helps us find UI problems faster.')); ?>
+          </blockquote>
+          <fieldset>
+            <legend>
+              <small>
+                <?php e(t('Frontend telemetry')); ?>
+              </small>
+            </legend>
+            <label class="app-field">
+              <input
+                type="checkbox"
+                name="frontend_telemetry_enabled"
+                value="1"
+                data-telemetry-enabled-toggle
+                <?php e($frontendTelemetryEnabled ? 'checked' : ''); ?>
+                <?php e($disabledAttr); ?>>
+              <span><?php e(t('Enable frontend telemetry')); ?></span>
+            </label>
+          </fieldset>
+          <fieldset data-telemetry-sampling-fieldset <?php e($frontendTelemetryEnabled ? '' : 'hidden'); ?>>
+            <legend>
+              <small>
+                <?php e(t('Sampling rate')); ?>
+              </small>
+            </legend>
+            <label class="app-field" data-telemetry-sampling-row>
+              <span><?php e(t('Sampling rate')); ?></span>
+              <select name="frontend_telemetry_sample_rate" data-telemetry-sampling-select <?php e($disabledAttr); ?>>
+                <option value="0.1" <?php e($frontendTelemetrySampleRate === '0.1' ? 'selected' : ''); ?>>10%</option>
+                <option value="0.2" <?php e($frontendTelemetrySampleRate === '0.2' ? 'selected' : ''); ?>>20%</option>
+                <option value="0.5" <?php e($frontendTelemetrySampleRate === '0.5' ? 'selected' : ''); ?>>50%</option>
+                <option value="1" <?php e($frontendTelemetrySampleRate === '1' ? 'selected' : ''); ?>>100%</option>
+              </select>
+              <small><?php e(t('The percentage of users who will have telemetry enabled.')); ?></small>
+            </label>
+          </fieldset>
+          <hr>
+          <details name="telemetry-advanced" data-details-key="telemetry-advanced">
+            <summary><?php e(t('Advanced telemetry options')); ?></summary>
             <hr>
             <fieldset>
-              <legend><small><?php e(t('User lifecycle policy')); ?></small></legend>
-              <div class="grid">
-                <label class="app-field">
-                  <span><?php e(t('Deactivate users after inactivity (days)')); ?></span>
-                  <input type="number" name="user_inactivity_deactivate_days"
-                    value="<?php e((string) $userInactivityDeactivateDays); ?>" min="0" max="3650" step="1"
-                    <?php e($readonlyAttr); ?>>
-                  <small><?php e(t($userInactivityDeactivateDaysDesc)); ?></small>
-                </label>
-                <label class="app-field">
-                  <span><?php e(t('Delete inactive users after (days)')); ?></span>
-                  <input type="number" name="user_inactivity_delete_days"
-                    value="<?php e((string) $userInactivityDeleteDays); ?>" min="0" max="3650" step="1"
-                    <?php e($readonlyAttr); ?>>
-                  <small><?php e(t($userInactivityDeleteDaysDesc)); ?></small>
-                </label>
-              </div>
-              <small class="muted"><?php e(t('0 disables this rule')); ?></small>
-              <small class="muted"><?php e(t('Deletion starts after user was set inactive')); ?></small>
-              <small class="muted"><?php e(t('Privileged admins are excluded from automatic lifecycle actions')); ?></small>
-              <?php if ($canUpdateSettings): ?>
-                <hr>
-                <button type="submit" class="outline warning" formnovalidate
-                  formaction="admin/settings/run-user-lifecycle"
-                  formmethod="post"
-                  data-detail-confirm-message="<?php e(t('Run user lifecycle now?')); ?>"
-                  data-detail-action-kind="danger">
-                  <?php e(t('Run user lifecycle now')); ?>
-                </button>
-              <?php endif; ?>
-            </fieldset>
-            <hr>
-            <fieldset>
-              <legend><small><?php e(t('System audit')); ?></small></legend>
+              <legend><small><?php e(t('Allowed telemetry events')); ?></small></legend>
               <label class="app-field">
-                <input type="checkbox" name="system_audit_enabled" value="1" <?php e($systemAuditEnabled ? 'checked' : ''); ?> <?php e($disabledAttr); ?>>
-                <span><?php e(t('Enable system audit log')); ?></span>
-                <small><?php e(t($systemAuditEnabledDesc)); ?></small>
+                <input type="checkbox" name="frontend_telemetry_allowed_events[]" value="warn_once" <?php e(in_array('warn_once', $frontendTelemetryAllowedEvents, true) ? 'checked' : ''); ?> <?php e($disabledAttr); ?>>
+                <span><?php e(t('warnOnce warnings')); ?></span>
               </label>
               <label class="app-field">
-                <span><?php e(t('Retention (days)')); ?></span>
-                <input
-                  type="number"
-                  name="system_audit_retention_days"
-                  value="<?php e((string) $systemAuditRetentionDays); ?>"
-                  min="30"
-                  max="1095"
-                  step="1"
-                  <?php e($readonlyAttr); ?>
-                >
-                <small><?php e(t($systemAuditRetentionDaysDesc)); ?></small>
+                <input type="checkbox" name="frontend_telemetry_allowed_events[]" value="ajax_error" <?php e(in_array('ajax_error', $frontendTelemetryAllowedEvents, true) ? 'checked' : ''); ?> <?php e($disabledAttr); ?>>
+                <span><?php e(t('AJAX errors')); ?></span>
               </label>
             </fieldset>
+          </details>
         </div>
 
         <div data-tab-panel="email">
           <div class="grid">
-              <label class="app-field">
-                <span><?php e(t('SMTP host')); ?></span>
-                <input type="text" name="smtp_host" value="<?php e($smtpHost); ?>" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($smtpHostDesc)); ?></small>
-              </label>
-              <label class="app-field">
-                <span><?php e(t('SMTP port')); ?></span>
-                <input type="number" name="smtp_port" value="<?php e($smtpPort); ?>" min="1" max="65535" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($smtpPortDesc)); ?></small>
-              </label>
-            </div>
-            <div class="grid">
-              <label class="app-field">
-                <span><?php e(t('SMTP user')); ?></span>
-                <input type="text" name="smtp_user" value="<?php e($smtpUser); ?>" autocomplete="username" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($smtpUserDesc)); ?></small>
-              </label>
-              <label class="app-field">
-                <span><?php e(t('SMTP password')); ?></span>
-                <input type="password" name="smtp_password" value="" autocomplete="new-password" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($smtpPasswordDesc)); ?></small>
-              </label>
-            </div>
-            <div class="grid">
-              <label class="app-field">
-                <span><?php e(t('SMTP security')); ?></span>
-                <select name="smtp_secure" <?php e($disabledAttr); ?>>
-                  <option value=""><?php e(t('None')); ?></option>
-                  <option value="tls" <?php e($smtpSecure === 'tls' ? 'selected' : ''); ?>>TLS</option>
-                  <option value="ssl" <?php e($smtpSecure === 'ssl' ? 'selected' : ''); ?>>SSL</option>
-                </select>
-                <small><?php e(t($smtpSecureDesc)); ?></small>
-              </label>
-              <label class="app-field">
-                <span><?php e(t('SMTP from address')); ?></span>
-                <input type="email" name="smtp_from" value="<?php e($smtpFrom); ?>" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($smtpFromDesc)); ?></small>
-              </label>
-            </div>
             <label class="app-field">
-              <span><?php e(t('SMTP from name')); ?></span>
-              <input type="text" name="smtp_from_name" value="<?php e($smtpFromName); ?>" <?php e($readonlyAttr); ?>>
-              <small><?php e(t($smtpFromNameDesc)); ?></small>
+              <span><?php e(t('SMTP host')); ?></span>
+              <input type="text" name="smtp_host" value="<?php e($smtpHost); ?>" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($smtpHostDesc)); ?></small>
             </label>
+            <label class="app-field">
+              <span><?php e(t('SMTP port')); ?></span>
+              <input type="number" name="smtp_port" value="<?php e($smtpPort); ?>" min="1" max="65535" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($smtpPortDesc)); ?></small>
+            </label>
+          </div>
+          <div class="grid">
+            <label class="app-field">
+              <span><?php e(t('SMTP user')); ?></span>
+              <input type="text" name="smtp_user" value="<?php e($smtpUser); ?>" autocomplete="username" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($smtpUserDesc)); ?></small>
+            </label>
+            <label class="app-field">
+              <span><?php e(t('SMTP password')); ?></span>
+              <input type="password" name="smtp_password" value="" autocomplete="new-password" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($smtpPasswordDesc)); ?></small>
+            </label>
+          </div>
+          <div class="grid">
+            <label class="app-field">
+              <span><?php e(t('SMTP security')); ?></span>
+              <select name="smtp_secure" <?php e($disabledAttr); ?>>
+                <option value=""><?php e(t('None')); ?></option>
+                <option value="tls" <?php e($smtpSecure === 'tls' ? 'selected' : ''); ?>>TLS</option>
+                <option value="ssl" <?php e($smtpSecure === 'ssl' ? 'selected' : ''); ?>>SSL</option>
+              </select>
+              <small><?php e(t($smtpSecureDesc)); ?></small>
+            </label>
+            <label class="app-field">
+              <span><?php e(t('SMTP from address')); ?></span>
+              <input type="email" name="smtp_from" value="<?php e($smtpFrom); ?>" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($smtpFromDesc)); ?></small>
+            </label>
+          </div>
+          <label class="app-field">
+            <span><?php e(t('SMTP from name')); ?></span>
+            <input type="text" name="smtp_from_name" value="<?php e($smtpFromName); ?>" <?php e($readonlyAttr); ?>>
+            <small><?php e(t($smtpFromNameDesc)); ?></small>
+          </label>
         </div>
 
         <div data-tab-panel="api">
           <p class="muted"><?php e(t('API tokens and default lifetimes are managed here.')); ?></p>
-            <div class="grid">
-              <label class="app-field">
-                <span><?php e(t('API token default lifetime (days)')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
-                <input type="number" name="api_token_default_ttl_days" value="<?php e((string) $apiTokenDefaultTtlDays); ?>"
-                  min="1" max="3650" step="1" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($apiTokenDefaultTtlDaysDesc)); ?></small>
-              </label>
-              <label class="app-field">
-                <span><?php e(t('API token maximum lifetime (days)')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
-                <input type="number" name="api_token_max_ttl_days" value="<?php e((string) $apiTokenMaxTtlDays); ?>"
-                  min="1" max="3650" step="1" <?php e($readonlyAttr); ?>>
-                <small><?php e(t($apiTokenMaxTtlDaysDesc)); ?></small>
-              </label>
-            </div>
+          <div class="grid">
             <label class="app-field">
-              <span><?php e(t('Allowed CORS origins')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
-              <textarea name="api_cors_allowed_origins" rows="4" placeholder="https://app.example.com&#10;https://admin.example.com" <?php e($readonlyAttr); ?>><?php e($apiCorsAllowedOrigins); ?></textarea>
-              <small><?php e(t($apiCorsAllowedOriginsDesc)); ?></small>
+              <span><?php e(t('API token default lifetime (days)')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
+              <input type="number" name="api_token_default_ttl_days" value="<?php e((string) $apiTokenDefaultTtlDays); ?>"
+                min="1" max="3650" step="1" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($apiTokenDefaultTtlDaysDesc)); ?></small>
             </label>
-            <small class="muted"><?php e(t('One origin per line, e.g. https://app.example.com')); ?></small>
-            <?php if ($canUpdateSettings): ?>
-              <fieldset>
-                <legend><small><?php e(t('API tokens')); ?></small></legend>
-                <p class="muted"><?php e(t('All API tokens will be revoked immediately.')); ?></p>
-                <p class="muted"><?php e(sprintf(t('%d active API tokens'), $activeApiTokens)); ?></p>
-                <button type="submit" class="danger" formnovalidate
-                  formaction="admin/settings/revoke-api-tokens"
-                  formmethod="post"
-                  data-detail-confirm-message="<?php e(t('Revoke all API tokens?')); ?>"
-                  data-detail-action-kind="danger">
-                  <?php e(t('Revoke all API tokens')); ?>
-                </button>
-              </fieldset>
-            <?php endif; ?>
+            <label class="app-field">
+              <span><?php e(t('API token maximum lifetime (days)')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
+              <input type="number" name="api_token_max_ttl_days" value="<?php e((string) $apiTokenMaxTtlDays); ?>"
+                min="1" max="3650" step="1" <?php e($readonlyAttr); ?>>
+              <small><?php e(t($apiTokenMaxTtlDaysDesc)); ?></small>
+            </label>
+          </div>
+          <label class="app-field">
+            <span><?php e(t('Allowed CORS origins')); ?> <span class="badge" data-variant="info"><?php e(t('Cached')); ?></span></span>
+            <textarea name="api_cors_allowed_origins" rows="4" placeholder="https://app.example.com&#10;https://admin.example.com" <?php e($readonlyAttr); ?>><?php e($apiCorsAllowedOrigins); ?></textarea>
+            <small><?php e(t($apiCorsAllowedOriginsDesc)); ?></small>
+          </label>
+          <small class="muted"><?php e(t('One origin per line, e.g. https://app.example.com')); ?></small>
+          <?php if ($canUpdateSettings): ?>
+            <fieldset>
+              <legend><small><?php e(t('API tokens')); ?></small></legend>
+              <p class="muted"><?php e(t('All API tokens will be revoked immediately.')); ?></p>
+              <p class="muted"><?php e(sprintf(t('%d active API tokens'), $activeApiTokens)); ?></p>
+              <button type="submit" class="danger" formnovalidate
+                formaction="admin/settings/revoke-api-tokens"
+                formmethod="post"
+                data-detail-confirm-message="<?php e(t('Revoke all API tokens?')); ?>"
+                data-detail-action-kind="danger">
+                <?php e(t('Revoke all API tokens')); ?>
+              </button>
+            </fieldset>
+          <?php endif; ?>
         </div>
 
         <div data-tab-panel="integrations">
           <blockquote data-variant="info">
-              <?php e(t('Shared Microsoft app credentials are used by tenants that enable "Use shared app credentials".')); ?>
-            </blockquote>
-            <label class="app-field">
-              <span><?php e(t('Shared client ID')); ?></span>
-              <input type="text" name="microsoft_shared_client_id" value="<?php e($microsoftSharedClientId); ?>" <?php e($readonlyAttr); ?>>
-              <small><?php e(t($microsoftSharedClientIdDesc)); ?></small>
-            </label>
-            <label class="app-field">
-              <span><?php e(t('Shared client secret')); ?></span>
-              <input type="password" name="microsoft_shared_client_secret" value="" autocomplete="new-password" <?php e($readonlyAttr); ?>>
-              <small><?php e(t($microsoftSharedClientSecretDesc)); ?></small>
-            </label>
-            <label class="app-field">
-              <span><?php e(t('Authority URL')); ?></span>
-              <input type="url" name="microsoft_authority" value="<?php e($microsoftAuthority); ?>" placeholder="https://login.microsoftonline.com/common/v2.0" <?php e($readonlyAttr); ?>>
-              <small><?php e(t($microsoftAuthorityDesc)); ?></small>
-            </label>
+            <?php e(t('Shared Microsoft app credentials are used by tenants that enable "Use shared app credentials".')); ?>
+          </blockquote>
+          <label class="app-field">
+            <span><?php e(t('Shared client ID')); ?></span>
+            <input type="text" name="microsoft_shared_client_id" value="<?php e($microsoftSharedClientId); ?>" <?php e($readonlyAttr); ?>>
+            <small><?php e(t($microsoftSharedClientIdDesc)); ?></small>
+          </label>
+          <label class="app-field">
+            <span><?php e(t('Shared client secret')); ?></span>
+            <input type="password" name="microsoft_shared_client_secret" value="" autocomplete="new-password" <?php e($readonlyAttr); ?>>
+            <small><?php e(t($microsoftSharedClientSecretDesc)); ?></small>
+          </label>
+          <label class="app-field">
+            <span><?php e(t('Authority URL')); ?></span>
+            <input type="url" name="microsoft_authority" value="<?php e($microsoftAuthority); ?>" placeholder="https://login.microsoftonline.com/common/v2.0" <?php e($readonlyAttr); ?>>
+            <small><?php e(t($microsoftAuthorityDesc)); ?></small>
+          </label>
         </div>
 
         <?php if ($canUpdateSettings): ?>
           <div data-tab-panel="danger">
             <fieldset>
-                <legend><small><?php e(t('Login tokens')); ?></small></legend>
-                <p class="muted">
-                  <?php e(t('This will mark all remember-me tokens as expired. Users will need to sign in again.')); ?>
-                </p>
-                <p class="muted">
-                  <?php e(sprintf(t('%d active login tokens'), $activeLoginTokens)); ?>
-                </p>
-                <form method="post" action="admin/settings/expire-remember-tokens"
-                  data-detail-confirm-message="<?php e(t('Expire all login tokens?')); ?>"
-                  data-detail-action-kind="danger">
-                  <button type="submit" class="danger">
-                    <?php e(t('Expire all login tokens')); ?>
-                  </button>
-                  <?php Session::getCsrfInput(); ?>
-                </form>
-              </fieldset>
+              <legend><small><?php e(t('Login tokens')); ?></small></legend>
+              <p class="muted">
+                <?php e(t('This will mark all remember-me tokens as expired. Users will need to sign in again.')); ?>
+              </p>
+              <p class="muted">
+                <?php e(sprintf(t('%d active login tokens'), $activeLoginTokens)); ?>
+              </p>
+              <form method="post" action="admin/settings/expire-remember-tokens"
+                data-detail-confirm-message="<?php e(t('Expire all login tokens?')); ?>"
+                data-detail-action-kind="danger">
+                <button type="submit" class="danger">
+                  <?php e(t('Expire all login tokens')); ?>
+                </button>
+                <?php Session::getCsrfInput(); ?>
+              </form>
+            </fieldset>
           </div>
         <?php endif; ?>
       </div>
diff --git a/pages/admin/tenants/data().php b/pages/admin/tenants/data().php
index fc077c4..0255562 100644
--- a/pages/admin/tenants/data().php
+++ b/pages/admin/tenants/data().php
@@ -22,13 +22,14 @@ $computedOrderKeys = ['theme', 'sso', 'active_users', 'inactive_users'];
 $userTenantRepository = app(\MintyPHP\Repository\Tenant\UserTenantRepository::class);
 $tenantMicrosoftAuthRepository = app(TenantMicrosoftAuthRepository::class);
 $tenantAvatarService = app(\MintyPHP\Service\Tenant\TenantAvatarService::class);
-$settingGateway = app(\MintyPHP\Service\Settings\SettingGateway::class);
+$settingsDefaultsGateway = app(\MintyPHP\Service\Settings\SettingsDefaultsGateway::class);
+$settingsAppGateway = app(\MintyPHP\Service\Settings\SettingsAppGateway::class);
 
 $fetchRows = static function (
     array $tenantRows,
     array $themes,
     string $globalDefaultTheme
-) use ($userTenantRepository, $tenantMicrosoftAuthRepository, $tenantAvatarService, $settingGateway): array {
+) use ($userTenantRepository, $tenantMicrosoftAuthRepository, $tenantAvatarService, $settingsDefaultsGateway): array {
     $tenantIds = [];
     foreach ($tenantRows as $tenantRow) {
         $tenantId = (int) ($tenantRow['id'] ?? 0);
@@ -42,7 +43,7 @@ $fetchRows = static function (
     $tenantUserCounts = $userTenantRepository->countUsersByTenantIds($tenantIds);
     $tenantActiveUserCounts = $userTenantRepository->countActiveUsersByTenantIds($tenantIds);
 
-    $defaultTenantId = $settingGateway->getDefaultTenantId();
+    $defaultTenantId = $settingsDefaultsGateway->getDefaultTenantId();
     $rows = [];
 
     foreach ($tenantRows as $row) {
@@ -102,7 +103,7 @@ $fetchRows = static function (
 };
 
 $themes = appThemes();
-$globalDefaultTheme = $settingGateway->getAppTheme();
+$globalDefaultTheme = $settingsAppGateway->getAppTheme();
 if ($globalDefaultTheme === null || !isset($themes[$globalDefaultTheme])) {
     $envTheme = strtolower(trim((string) (getenv('APP_THEME') ?: 'light')));
     $globalDefaultTheme = isset($themes[$envTheme]) ? $envTheme : 'light';
diff --git a/pages/admin/users/create().php b/pages/admin/users/create().php
index 38ebf18..043e22f 100644
--- a/pages/admin/users/create().php
+++ b/pages/admin/users/create().php
@@ -32,7 +32,7 @@ $userPasswordPolicyService = app(\MintyPHP\Service\User\UserPasswordPolicyServic
 $userCustomFieldValueService = app(UserCustomFieldValueService::class);
 $passwordMinLength = $userPasswordPolicyService->minLength();
 $passwordHints = $userPasswordPolicyService->hints();
-$settingGateway = app(\MintyPHP\Service\Settings\SettingGateway::class);
+$settingsDefaultsGateway = app(\MintyPHP\Service\Settings\SettingsDefaultsGateway::class);
 $directoryScopeGateway = app(\MintyPHP\Service\Directory\DirectoryScopeGateway::class);
 $tenantService = app(\MintyPHP\Service\Tenant\TenantService::class);
 $roleService = app(\MintyPHP\Service\Access\RoleService::class);
@@ -98,7 +98,7 @@ if ($request->hasBody('email')) {
     } elseif ($directoryScopeGateway->isStrict()) {
         $tenantIds = [];
     }
-    $defaultTenantId = $settingGateway->getDefaultTenantId();
+    $defaultTenantId = $settingsDefaultsGateway->getDefaultTenantId();
     if (
         $canManageAssignments
         && $directoryScopeGateway->isStrict()
diff --git a/pages/api/v1/settings/index().php b/pages/api/v1/settings/index().php
index 954a1e5..09d29e2 100644
--- a/pages/api/v1/settings/index().php
+++ b/pages/api/v1/settings/index().php
@@ -4,19 +4,42 @@ use MintyPHP\Http\ApiAuth;
 use MintyPHP\Http\ApiBootstrap;
 use MintyPHP\Http\ApiResponse;
 use MintyPHP\Service\Audit\SystemAuditService;
-use MintyPHP\Service\Settings\SettingServicesFactory;
+use MintyPHP\Service\Settings\SettingsApiPolicyGateway;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsFrontendTelemetryGateway;
+use MintyPHP\Service\Settings\SettingsMicrosoftGateway;
+use MintyPHP\Service\Settings\SettingsSmtpGateway;
+use MintyPHP\Service\Settings\SettingsSystemAuditGateway;
+use MintyPHP\Service\Settings\SettingsUserLifecycleGateway;
 
 ApiBootstrap::init();
 
 $request = requestInput();
 $method = $request->method();
-$settingService = (app(SettingServicesFactory::class))->createSettingService();
+$settingsAppGateway = app(SettingsAppGateway::class);
+$settingsDefaultsGateway = app(SettingsDefaultsGateway::class);
+$settingsApiPolicyGateway = app(SettingsApiPolicyGateway::class);
+$settingsUserLifecycleGateway = app(SettingsUserLifecycleGateway::class);
+$settingsSystemAuditGateway = app(SettingsSystemAuditGateway::class);
+$settingsFrontendTelemetryGateway = app(SettingsFrontendTelemetryGateway::class);
+$settingsMicrosoftGateway = app(SettingsMicrosoftGateway::class);
+$settingsSmtpGateway = app(SettingsSmtpGateway::class);
 
 if ($method === 'GET') {
     ApiResponse::requireAbility(\MintyPHP\Service\Access\OperationsAuthorizationPolicy::ABILITY_API_SETTINGS_VIEW);
 
     ApiResponse::success([
-        'data' => buildSettingsResponse($settingService),
+        'data' => buildSettingsResponse(
+            $settingsAppGateway,
+            $settingsDefaultsGateway,
+            $settingsApiPolicyGateway,
+            $settingsUserLifecycleGateway,
+            $settingsSystemAuditGateway,
+            $settingsFrontendTelemetryGateway,
+            $settingsMicrosoftGateway,
+            $settingsSmtpGateway,
+        ),
     ]);
 }
 
@@ -25,34 +48,48 @@ if ($method === 'PUT' || $method === 'PATCH') {
 
     $input = $request->bodyAll();
     $errors = formErrors();
-    $beforeSettings = buildSettingsResponse($settingService);
+    $beforeSettings = buildSettingsResponse(
+        $settingsAppGateway,
+        $settingsDefaultsGateway,
+        $settingsApiPolicyGateway,
+        $settingsUserLifecycleGateway,
+        $settingsSystemAuditGateway,
+        $settingsFrontendTelemetryGateway,
+        $settingsMicrosoftGateway,
+        $settingsSmtpGateway,
+    );
 
     $setters = [
-        'app_title' => static fn (?string $v) => $settingService->setAppTitle($v),
-        'app_locale' => static fn (?string $v) => $settingService->setAppLocale($v),
-        'app_theme' => static fn (?string $v) => $settingService->setAppTheme($v),
-        'app_theme_user_allowed' => static fn ($v) => $settingService->setUserThemeAllowed((bool) $v),
-        'app_registration_enabled' => static fn ($v) => $settingService->setRegistrationEnabled((bool) $v),
-        'app_primary_color' => static fn (?string $v) => $settingService->setAppPrimaryColor($v),
-        'api_token_default_ttl_days' => static fn ($v) => $settingService->setApiTokenDefaultTtlDays($v !== null ? (int) $v : null),
-        'api_token_max_ttl_days' => static fn ($v) => $settingService->setApiTokenMaxTtlDays($v !== null ? (int) $v : null),
-        'api_cors_allowed_origins' => static fn (?string $v) => $settingService->setApiCorsAllowedOrigins($v),
-        'default_tenant_id' => static fn ($v) => $settingService->setDefaultTenantId($v !== null ? (int) $v : null),
-        'default_role_id' => static fn ($v) => $settingService->setDefaultRoleId($v !== null ? (int) $v : null),
-        'default_department_id' => static fn ($v) => $settingService->setDefaultDepartmentId($v !== null ? (int) $v : null),
-        'user_inactivity_deactivate_days' => static fn ($v) => $settingService->setUserInactivityDeactivateDays($v !== null ? (int) $v : null),
-        'user_inactivity_delete_days' => static fn ($v) => $settingService->setUserInactivityDeleteDays($v !== null ? (int) $v : null),
-        'system_audit_enabled' => static fn ($v) => $settingService->setSystemAuditEnabled((bool) $v),
-        'system_audit_retention_days' => static fn ($v) => $settingService->setSystemAuditRetentionDays($v !== null ? (int) $v : null),
-        'microsoft_shared_client_id' => static fn (?string $v) => $settingService->setMicrosoftSharedClientId($v),
-        'microsoft_authority' => static fn (?string $v) => $settingService->setMicrosoftAuthority($v),
-        'smtp_host' => static fn (?string $v) => $settingService->setSmtpHost($v),
-        'smtp_port' => static fn ($v) => $settingService->setSmtpPort($v !== null ? (int) $v : null),
-        'smtp_user' => static fn (?string $v) => $settingService->setSmtpUser($v),
-        'smtp_password' => static fn (?string $v) => $settingService->setSmtpPassword($v),
-        'smtp_secure' => static fn (?string $v) => $settingService->setSmtpSecure($v),
-        'smtp_from' => static fn (?string $v) => $settingService->setSmtpFrom($v),
-        'smtp_from_name' => static fn (?string $v) => $settingService->setSmtpFromName($v),
+        'app_title' => static fn (?string $v) => $settingsAppGateway->setAppTitle($v),
+        'app_locale' => static fn (?string $v) => $settingsAppGateway->setAppLocale($v),
+        'app_theme' => static fn (?string $v) => $settingsAppGateway->setAppTheme($v),
+        'app_theme_user_allowed' => static fn ($v) => $settingsAppGateway->setUserThemeAllowed((bool) $v),
+        'app_registration_enabled' => static fn ($v) => $settingsAppGateway->setRegistrationEnabled((bool) $v),
+        'app_primary_color' => static fn (?string $v) => $settingsAppGateway->setAppPrimaryColor($v),
+        'api_token_default_ttl_days' => static fn ($v) => $settingsApiPolicyGateway->setApiTokenDefaultTtlDays($v !== null ? (int) $v : null),
+        'api_token_max_ttl_days' => static fn ($v) => $settingsApiPolicyGateway->setApiTokenMaxTtlDays($v !== null ? (int) $v : null),
+        'api_cors_allowed_origins' => static fn (?string $v) => $settingsApiPolicyGateway->setApiCorsAllowedOrigins($v),
+        'default_tenant_id' => static fn ($v) => $settingsDefaultsGateway->setDefaultTenantId($v !== null ? (int) $v : null),
+        'default_role_id' => static fn ($v) => $settingsDefaultsGateway->setDefaultRoleId($v !== null ? (int) $v : null),
+        'default_department_id' => static fn ($v) => $settingsDefaultsGateway->setDefaultDepartmentId($v !== null ? (int) $v : null),
+        'user_inactivity_deactivate_days' => static fn ($v) => $settingsUserLifecycleGateway->setUserInactivityDeactivateDays($v !== null ? (int) $v : null),
+        'user_inactivity_delete_days' => static fn ($v) => $settingsUserLifecycleGateway->setUserInactivityDeleteDays($v !== null ? (int) $v : null),
+        'system_audit_enabled' => static fn ($v) => $settingsSystemAuditGateway->setSystemAuditEnabled((bool) $v),
+        'system_audit_retention_days' => static fn ($v) => $settingsSystemAuditGateway->setSystemAuditRetentionDays($v !== null ? (int) $v : null),
+        'frontend_telemetry_enabled' => static fn ($v) => $settingsFrontendTelemetryGateway->setFrontendTelemetryEnabled((bool) $v),
+        'frontend_telemetry_sample_rate' => static fn ($v) => $settingsFrontendTelemetryGateway->setFrontendTelemetrySampleRate(
+            $v === null ? null : (is_numeric((string) $v) ? (float) $v : NAN)
+        ),
+        'frontend_telemetry_allowed_events' => static fn ($v) => $settingsFrontendTelemetryGateway->setFrontendTelemetryAllowedEvents($v),
+        'microsoft_shared_client_id' => static fn (?string $v) => $settingsMicrosoftGateway->setMicrosoftSharedClientId($v),
+        'microsoft_authority' => static fn (?string $v) => $settingsMicrosoftGateway->setMicrosoftAuthority($v),
+        'smtp_host' => static fn (?string $v) => $settingsSmtpGateway->setSmtpHost($v),
+        'smtp_port' => static fn ($v) => $settingsSmtpGateway->setSmtpPort($v !== null ? (int) $v : null),
+        'smtp_user' => static fn (?string $v) => $settingsSmtpGateway->setSmtpUser($v),
+        'smtp_password' => static fn (?string $v) => $settingsSmtpGateway->setSmtpPassword($v),
+        'smtp_secure' => static fn (?string $v) => $settingsSmtpGateway->setSmtpSecure($v),
+        'smtp_from' => static fn (?string $v) => $settingsSmtpGateway->setSmtpFrom($v),
+        'smtp_from_name' => static fn (?string $v) => $settingsSmtpGateway->setSmtpFromName($v),
     ];
 
     foreach ($input as $key => $value) {
@@ -74,7 +111,16 @@ if ($method === 'PUT' || $method === 'PATCH') {
         ApiResponse::validationFromFormErrors($errors);
     }
 
-    $afterSettings = buildSettingsResponse($settingService);
+    $afterSettings = buildSettingsResponse(
+        $settingsAppGateway,
+        $settingsDefaultsGateway,
+        $settingsApiPolicyGateway,
+        $settingsUserLifecycleGateway,
+        $settingsSystemAuditGateway,
+        $settingsFrontendTelemetryGateway,
+        $settingsMicrosoftGateway,
+        $settingsSmtpGateway,
+    );
     app(SystemAuditService::class)->record('admin.settings.update', 'success', [
         'actor_user_id' => ApiAuth::userId(),
         'before' => $beforeSettings,
@@ -89,35 +135,45 @@ if ($method === 'PUT' || $method === 'PATCH') {
 ApiResponse::methodNotAllowed();
 
 /**
- * @param \MintyPHP\Service\Settings\SettingService $s
  * @return array<string, mixed>
  */
-function buildSettingsResponse(\MintyPHP\Service\Settings\SettingService $s): array
-{
+function buildSettingsResponse(
+    SettingsAppGateway $settingsAppGateway,
+    SettingsDefaultsGateway $settingsDefaultsGateway,
+    SettingsApiPolicyGateway $settingsApiPolicyGateway,
+    SettingsUserLifecycleGateway $settingsUserLifecycleGateway,
+    SettingsSystemAuditGateway $settingsSystemAuditGateway,
+    SettingsFrontendTelemetryGateway $settingsFrontendTelemetryGateway,
+    SettingsMicrosoftGateway $settingsMicrosoftGateway,
+    SettingsSmtpGateway $settingsSmtpGateway
+): array {
     return [
-        'app_title' => $s->getAppTitle(),
-        'app_locale' => $s->getAppLocale(),
-        'app_theme' => $s->getAppTheme(),
-        'app_theme_user_allowed' => $s->isUserThemeAllowed(),
-        'app_registration_enabled' => $s->isRegistrationEnabled(),
-        'app_primary_color' => $s->getAppPrimaryColor(),
-        'api_token_default_ttl_days' => $s->getApiTokenDefaultTtlDays(),
-        'api_token_max_ttl_days' => $s->getApiTokenMaxTtlDays(),
-        'api_cors_allowed_origins' => $s->getApiCorsAllowedOrigins(),
-        'default_tenant_id' => $s->getDefaultTenantId(),
-        'default_role_id' => $s->getDefaultRoleId(),
-        'default_department_id' => $s->getDefaultDepartmentId(),
-        'user_inactivity_deactivate_days' => $s->getUserInactivityDeactivateDays(),
-        'user_inactivity_delete_days' => $s->getUserInactivityDeleteDays(),
-        'system_audit_enabled' => $s->isSystemAuditEnabled(),
-        'system_audit_retention_days' => $s->getSystemAuditRetentionDays(),
-        'microsoft_shared_client_id' => $s->getMicrosoftSharedClientId(),
-        'microsoft_authority' => $s->getMicrosoftAuthority(),
-        'smtp_host' => $s->getSmtpHost(),
-        'smtp_port' => $s->getSmtpPort(),
-        'smtp_user' => $s->getSmtpUser(),
-        'smtp_secure' => $s->getSmtpSecure(),
-        'smtp_from' => $s->getSmtpFrom(),
-        'smtp_from_name' => $s->getSmtpFromName(),
+        'app_title' => $settingsAppGateway->getAppTitle(),
+        'app_locale' => $settingsAppGateway->getAppLocale(),
+        'app_theme' => $settingsAppGateway->getAppTheme(),
+        'app_theme_user_allowed' => $settingsAppGateway->isUserThemeAllowed(),
+        'app_registration_enabled' => $settingsAppGateway->isRegistrationEnabled(),
+        'app_primary_color' => $settingsAppGateway->getAppPrimaryColor(),
+        'api_token_default_ttl_days' => $settingsApiPolicyGateway->getApiTokenDefaultTtlDays(),
+        'api_token_max_ttl_days' => $settingsApiPolicyGateway->getApiTokenMaxTtlDays(),
+        'api_cors_allowed_origins' => $settingsApiPolicyGateway->getApiCorsAllowedOrigins(),
+        'default_tenant_id' => $settingsDefaultsGateway->getDefaultTenantId(),
+        'default_role_id' => $settingsDefaultsGateway->getDefaultRoleId(),
+        'default_department_id' => $settingsDefaultsGateway->getDefaultDepartmentId(),
+        'user_inactivity_deactivate_days' => $settingsUserLifecycleGateway->getUserInactivityDeactivateDays(),
+        'user_inactivity_delete_days' => $settingsUserLifecycleGateway->getUserInactivityDeleteDays(),
+        'system_audit_enabled' => $settingsSystemAuditGateway->isSystemAuditEnabled(),
+        'system_audit_retention_days' => $settingsSystemAuditGateway->getSystemAuditRetentionDays(),
+        'frontend_telemetry_enabled' => $settingsFrontendTelemetryGateway->isFrontendTelemetryEnabled(),
+        'frontend_telemetry_sample_rate' => $settingsFrontendTelemetryGateway->getFrontendTelemetrySampleRate(),
+        'frontend_telemetry_allowed_events' => $settingsFrontendTelemetryGateway->getFrontendTelemetryAllowedEvents(),
+        'microsoft_shared_client_id' => $settingsMicrosoftGateway->getMicrosoftSharedClientId(),
+        'microsoft_authority' => $settingsMicrosoftGateway->getMicrosoftAuthority(),
+        'smtp_host' => $settingsSmtpGateway->getSmtpHost(),
+        'smtp_port' => $settingsSmtpGateway->getSmtpPort(),
+        'smtp_user' => $settingsSmtpGateway->getSmtpUser(),
+        'smtp_secure' => $settingsSmtpGateway->getSmtpSecure(),
+        'smtp_from' => $settingsSmtpGateway->getSmtpFrom(),
+        'smtp_from_name' => $settingsSmtpGateway->getSmtpFromName(),
     ];
 }
diff --git a/pages/api/v1/settings/public().php b/pages/api/v1/settings/public().php
index 7eb1188..d79ad30 100644
--- a/pages/api/v1/settings/public().php
+++ b/pages/api/v1/settings/public().php
@@ -2,19 +2,20 @@
 
 use MintyPHP\Http\ApiBootstrap;
 use MintyPHP\Http\ApiResponse;
+use MintyPHP\Service\Settings\SettingsAppGateway;
 
 ApiBootstrap::init(requireAuth: false);
 ApiResponse::requireMethod('GET');
 
-$settingService = app(\MintyPHP\Service\Settings\SettingService::class);
+$settingsAppGateway = app(SettingsAppGateway::class);
 
 header('Cache-Control: public, max-age=60');
 
 ApiResponse::success([
     'data' => [
-        'app_title' => $settingService->getAppTitle(),
-        'app_primary_color' => $settingService->getAppPrimaryColor(),
-        'default_theme' => $settingService->getAppTheme(),
-        'registration_enabled' => $settingService->isRegistrationEnabled(),
+        'app_title' => $settingsAppGateway->getAppTitle(),
+        'app_primary_color' => $settingsAppGateway->getAppPrimaryColor(),
+        'default_theme' => $settingsAppGateway->getAppTheme(),
+        'registration_enabled' => $settingsAppGateway->isRegistrationEnabled(),
     ],
 ]);
diff --git a/pages/lang().php b/pages/lang().php
index 4149720..3ad49e0 100644
--- a/pages/lang().php
+++ b/pages/lang().php
@@ -6,7 +6,11 @@ use MintyPHP\Router;
 use MintyPHP\Service\User\UserServicesFactory;
 use MintyPHP\Support\Flash;
 
-$rawLocale = (string) ($_REQUEST['locale'] ?? (requestInput()->queryAll()['lang'] ?? ''));
+$request = requestInput();
+$rawLocale = (string) $request->body(
+    'locale',
+    $request->query('locale', $request->query('lang', ''))
+);
 $locale = strtolower(trim($rawLocale));
 if ($locale !== '' && strpos($locale, '-') !== false) {
     $locale = explode('-', $locale, 2)[0];
@@ -29,7 +33,7 @@ if (isset($_SESSION['user']['id'])) {
     setcookie('locale', $locale, time() + 31536000, '/', '', false, true);
 }
 
-$target = Request::safeReturnTarget(requestInput()->queryAll()['return'] ?? '');
+$target = Request::safeReturnTarget($request->query('return', ''));
 $target = Request::stripLocale($target);
 $target = Request::withLocale($target, $locale);
 Router::redirect($target);
diff --git a/templates/default.phtml b/templates/default.phtml
index d43891a..8aeb4b2 100644
--- a/templates/default.phtml
+++ b/templates/default.phtml
@@ -1,11 +1,20 @@
 <?php
 
 use MintyPHP\Buffer;
+use MintyPHP\Http\RequestContext;
+use MintyPHP\Session;
 
 $defaultTitle = appTitle();
 $user = $_SESSION['user'] ?? [];
 $theme = currentTheme();
 $primaryVars = appPrimaryCssVars();
+$csrfKey = Session::$csrfSessionKey;
+$csrfToken = (string) ($_SESSION[$csrfKey] ?? '');
+$telemetryEnabled = frontendTelemetryEnabled();
+$telemetrySampleRate = frontendTelemetrySampleRate();
+$telemetryAllowedEvents = implode(',', frontendTelemetryAllowedEvents());
+$telemetryUrl = lurl('admin/frontend-telemetry/ingest');
+$pageRequestId = RequestContext::id();
 $viewAuth = is_array($viewAuth ?? null) ? $viewAuth : [];
 $viewAuth['layout'] = is_array($viewAuth['layout'] ?? null) ? $viewAuth['layout'] : [];
 $pageTitle = $defaultTitle;
@@ -18,7 +27,20 @@ if ($bufferTitle !== '') {
 
 ?>
 <!DOCTYPE html>
-<html data-theme="<?php e($theme); ?>" data-contrast="normal" data-asset-base="<?php e(asset('')); ?>" class="no-js" <?php if ($primaryVars !== ''): ?>style="<?php e($primaryVars); ?>" <?php endif; ?>>
+<html
+  data-theme="<?php e($theme); ?>"
+  data-contrast="normal"
+  data-asset-base="<?php e(asset('')); ?>"
+  data-request-id="<?php e($pageRequestId); ?>"
+  data-telemetry-url="<?php e($telemetryUrl); ?>"
+  data-telemetry-enabled="<?php e($telemetryEnabled ? '1' : '0'); ?>"
+  data-telemetry-sample-rate="<?php e((string) $telemetrySampleRate); ?>"
+  data-telemetry-allowed-events="<?php e($telemetryAllowedEvents); ?>"
+  data-telemetry-csrf-key="<?php e($csrfKey); ?>"
+  data-telemetry-csrf-token="<?php e($csrfToken); ?>"
+  class="no-js"
+  <?php if ($primaryVars !== ''): ?>style="<?php e($primaryVars); ?>" <?php endif; ?>
+>
 
 <head>
   <script src="<?php e(assetVersion('js/app-boot.js')); ?>"></script>
@@ -53,6 +75,7 @@ if ($bufferTitle !== '') {
   </div>
 
   <script src="<?php e(assetVersion('vendor/fslightbox/fslightbox.js')); ?>"></script>
+  <?php require __DIR__ . '/partials/app-confirm-dialog.phtml'; ?>
   <script type="module" src="<?php e(assetVersion('js/app-init.js')); ?>"></script>
 </body>
 
diff --git a/templates/partials/app-confirm-dialog.phtml b/templates/partials/app-confirm-dialog.phtml
new file mode 100644
index 0000000..efeb1fb
--- /dev/null
+++ b/templates/partials/app-confirm-dialog.phtml
@@ -0,0 +1,22 @@
+<dialog
+  data-app-confirm-dialog
+  data-default-title="<?php e(t('Please confirm')); ?>"
+  data-default-confirm-label="<?php e(t('Confirm')); ?>"
+  data-default-cancel-label="<?php e(t('Cancel')); ?>"
+  data-default-danger-note="<?php e(t('This action cannot be undone.')); ?>"
+  aria-labelledby="app-confirm-dialog-title"
+  aria-describedby="app-confirm-dialog-message"
+>
+  <article class="app-confirm-dialog">
+    <header>
+      <h2 id="app-confirm-dialog-title" data-app-confirm-title><?php e(t('Please confirm')); ?></h2>
+      <button type="button" class="close" data-app-confirm-close aria-label="<?php e(t('Close')); ?>" title="<?php e(t('Close')); ?>"></button>
+    </header>
+    <p id="app-confirm-dialog-message" data-app-confirm-message></p>
+    <p id="app-confirm-dialog-note" data-app-confirm-note class="muted" hidden></p>
+    <footer>
+      <button type="button" class="secondary outline" data-app-confirm-cancel><?php e(t('Cancel')); ?></button>
+      <button type="button" class="primary" data-app-confirm-confirm><?php e(t('Confirm')); ?></button>
+    </footer>
+  </article>
+</dialog>
diff --git a/templates/partials/app-details-aside-actions.phtml b/templates/partials/app-details-aside-actions.phtml
index 49a88a3..5a8cd87 100644
--- a/templates/partials/app-details-aside-actions.phtml
+++ b/templates/partials/app-details-aside-actions.phtml
@@ -32,6 +32,11 @@ if (!$asideActions) {
         $itemMethod = strtoupper((string) ($item['method'] ?? 'POST'));
         $itemAction = (string) ($item['action'] ?? '');
         $itemConfirm = (string) ($item['confirm'] ?? '');
+        $itemConfirmTitle = (string) ($item['confirmTitle'] ?? '');
+        $itemConfirmConfirmLabel = (string) ($item['confirmConfirmLabel'] ?? '');
+        $itemConfirmCancelLabel = (string) ($item['confirmCancelLabel'] ?? '');
+        $itemConfirmVariant = strtolower(trim((string) ($item['confirmVariant'] ?? '')));
+        $itemConfirmFocus = strtolower(trim((string) ($item['confirmFocus'] ?? '')));
         $itemButtonClass = (string) ($item['class'] ?? 'secondary outline small');
         $itemNeedsCsrf = !array_key_exists('csrf', $item) ? true : !empty($item['csrf']);
         $itemTarget = (string) ($item['target'] ?? '');
@@ -45,6 +50,11 @@ if (!$asideActions) {
             action="<?php e($itemAction); ?>"
             <?php if ($itemTarget !== ''): ?>target="<?php e($itemTarget); ?>"<?php endif; ?>
             <?php if ($itemConfirm !== ''): ?>data-detail-confirm-message="<?php e($itemConfirm); ?>"<?php endif; ?>
+            <?php if ($itemConfirmTitle !== ''): ?>data-detail-confirm-title="<?php e($itemConfirmTitle); ?>"<?php endif; ?>
+            <?php if ($itemConfirmConfirmLabel !== ''): ?>data-detail-confirm-confirm-label="<?php e($itemConfirmConfirmLabel); ?>"<?php endif; ?>
+            <?php if ($itemConfirmCancelLabel !== ''): ?>data-detail-confirm-cancel-label="<?php e($itemConfirmCancelLabel); ?>"<?php endif; ?>
+            <?php if ($itemConfirmVariant !== ''): ?>data-detail-confirm-variant="<?php e($itemConfirmVariant); ?>"<?php endif; ?>
+            <?php if ($itemConfirmFocus !== ''): ?>data-detail-confirm-focus="<?php e($itemConfirmFocus); ?>"<?php endif; ?>
             <?php if ($itemDetailActionKind !== ''): ?>data-detail-action-kind="<?php e($itemDetailActionKind); ?>"<?php endif; ?>
             <?php if ($itemDetailSubmitLock !== ''): ?>data-detail-submit-lock="<?php e($itemDetailSubmitLock); ?>"<?php endif; ?>
           >
diff --git a/templates/partials/app-details-titlebar.phtml b/templates/partials/app-details-titlebar.phtml
index 5229667..6d10b48 100644
--- a/templates/partials/app-details-titlebar.phtml
+++ b/templates/partials/app-details-titlebar.phtml
@@ -55,6 +55,11 @@ $menuItems = is_array($titlebar['menuItems'] ?? null) ? $titlebar['menuItems'] :
                 $itemMethod = strtoupper((string) ($item['method'] ?? 'POST'));
                 $itemAction = (string) ($item['action'] ?? '');
                 $itemConfirm = (string) ($item['confirm'] ?? '');
+                $itemConfirmTitle = (string) ($item['confirmTitle'] ?? '');
+                $itemConfirmConfirmLabel = (string) ($item['confirmConfirmLabel'] ?? '');
+                $itemConfirmCancelLabel = (string) ($item['confirmCancelLabel'] ?? '');
+                $itemConfirmVariant = strtolower(trim((string) ($item['confirmVariant'] ?? '')));
+                $itemConfirmFocus = strtolower(trim((string) ($item['confirmFocus'] ?? '')));
                 $itemButtonClass = (string) ($item['class'] ?? 'transparent');
                 $itemNeedsCsrf = !array_key_exists('csrf', $item) ? true : !empty($item['csrf']);
                 $itemTarget = (string) ($item['target'] ?? '');
@@ -68,6 +73,11 @@ $menuItems = is_array($titlebar['menuItems'] ?? null) ? $titlebar['menuItems'] :
                     action="<?php e($itemAction); ?>"
                     <?php if ($itemTarget !== ''): ?>target="<?php e($itemTarget); ?>"<?php endif; ?>
                     <?php if ($itemConfirm !== ''): ?>data-detail-confirm-message="<?php e($itemConfirm); ?>"<?php endif; ?>
+                    <?php if ($itemConfirmTitle !== ''): ?>data-detail-confirm-title="<?php e($itemConfirmTitle); ?>"<?php endif; ?>
+                    <?php if ($itemConfirmConfirmLabel !== ''): ?>data-detail-confirm-confirm-label="<?php e($itemConfirmConfirmLabel); ?>"<?php endif; ?>
+                    <?php if ($itemConfirmCancelLabel !== ''): ?>data-detail-confirm-cancel-label="<?php e($itemConfirmCancelLabel); ?>"<?php endif; ?>
+                    <?php if ($itemConfirmVariant !== ''): ?>data-detail-confirm-variant="<?php e($itemConfirmVariant); ?>"<?php endif; ?>
+                    <?php if ($itemConfirmFocus !== ''): ?>data-detail-confirm-focus="<?php e($itemConfirmFocus); ?>"<?php endif; ?>
                     <?php if ($itemDetailActionKind !== ''): ?>data-detail-action-kind="<?php e($itemDetailActionKind); ?>"<?php endif; ?>
                     <?php if ($itemDetailSubmitLock !== ''): ?>data-detail-submit-lock="<?php e($itemDetailSubmitLock); ?>"<?php endif; ?>
                   >
@@ -118,6 +128,11 @@ $menuItems = is_array($titlebar['menuItems'] ?? null) ? $titlebar['menuItems'] :
       $itemName = (string) ($item['name'] ?? '');
       $itemValue = (string) ($item['value'] ?? '');
       $itemConfirm = (string) ($item['confirm'] ?? '');
+      $itemConfirmTitle = (string) ($item['confirmTitle'] ?? '');
+      $itemConfirmConfirmLabel = (string) ($item['confirmConfirmLabel'] ?? '');
+      $itemConfirmCancelLabel = (string) ($item['confirmCancelLabel'] ?? '');
+      $itemConfirmVariant = strtolower(trim((string) ($item['confirmVariant'] ?? '')));
+      $itemConfirmFocus = strtolower(trim((string) ($item['confirmFocus'] ?? '')));
       $itemDetailActionKind = strtolower(trim((string) ($item['detailActionKind'] ?? '')));
       $itemDetailSubmitLock = strtolower(trim((string) ($item['detailSubmitLock'] ?? '')));
       $itemDisabled = !empty($item['disabled']);
@@ -144,6 +159,11 @@ $menuItems = is_array($titlebar['menuItems'] ?? null) ? $titlebar['menuItems'] :
         <?php if ($itemName !== ''): ?>name="<?php e($itemName); ?>"<?php endif; ?>
         <?php if ($itemValue !== ''): ?>value="<?php e($itemValue); ?>"<?php endif; ?>
         <?php if ($itemConfirm !== ''): ?>data-detail-confirm-message="<?php e($itemConfirm); ?>"<?php endif; ?>
+        <?php if ($itemConfirmTitle !== ''): ?>data-detail-confirm-title="<?php e($itemConfirmTitle); ?>"<?php endif; ?>
+        <?php if ($itemConfirmConfirmLabel !== ''): ?>data-detail-confirm-confirm-label="<?php e($itemConfirmConfirmLabel); ?>"<?php endif; ?>
+        <?php if ($itemConfirmCancelLabel !== ''): ?>data-detail-confirm-cancel-label="<?php e($itemConfirmCancelLabel); ?>"<?php endif; ?>
+        <?php if ($itemConfirmVariant !== ''): ?>data-detail-confirm-variant="<?php e($itemConfirmVariant); ?>"<?php endif; ?>
+        <?php if ($itemConfirmFocus !== ''): ?>data-detail-confirm-focus="<?php e($itemConfirmFocus); ?>"<?php endif; ?>
         <?php if ($itemDetailActionKind !== ''): ?>data-detail-action-kind="<?php e($itemDetailActionKind); ?>"<?php endif; ?>
         <?php if ($itemDetailSubmitLock !== ''): ?>data-detail-submit-lock="<?php e($itemDetailSubmitLock); ?>"<?php endif; ?>
         <?php if ($itemDetailSavePrimary): ?>data-detail-save-primary="1"<?php endif; ?>
diff --git a/templates/partials/app-footer.phtml b/templates/partials/app-footer.phtml
index a1c0dee..02063d5 100644
--- a/templates/partials/app-footer.phtml
+++ b/templates/partials/app-footer.phtml
@@ -1,5 +1,5 @@
 <footer class="site-footer">
-  <nav>
+  <nav aria-label="<?php e(t('Footer navigation')); ?>">
     <ul>
       <li>
         <a href="<?php e(lurl('')); ?>">
diff --git a/templates/partials/app-language-switcher.phtml b/templates/partials/app-language-switcher.phtml
index d78c40a..9abf713 100644
--- a/templates/partials/app-language-switcher.phtml
+++ b/templates/partials/app-language-switcher.phtml
@@ -14,31 +14,7 @@ $base = rtrim($base, '/');
 $publicTarget = ltrim($publicTarget, '/');
 ?>
 
-<?php if ($variant === 'dropdown'): ?>
-    <details class="dropdown">
-        <summary aria-label="<?php e(t('Language switcher')); ?>">
-            <i class="bi bi-translate"></i>
-        </summary>
-        <ul dir="rtl">
-            <?php foreach ($locales as $locale): ?>
-                <?php
-                $isActive = $locale === I18n::$locale;
-                $label = strtoupper((string) $locale);
-                $publicUrl = $base . '/' . $locale . ($publicTarget !== '' ? '/' . $publicTarget : '');
-                $switchUrl = $isLoggedIn
-                    ? ($baseUrl . '?locale=' . $locale . '&return=' . urlencode($returnTarget))
-                    : $publicUrl;
-                ?>
-                <li dir="ltr">
-                    <a href="<?php e($switchUrl); ?>"
-                       <?php if ($isActive) { ?>aria-current="true"<?php } ?>>
-                        <?php e($label); ?>
-                    </a>
-                </li>
-            <?php endforeach; ?>
-        </ul>
-    </details>
-<?php elseif ($variant === 'menu-items'): ?>
+<?php if ($variant === 'menu-items'): ?>
     <?php foreach ($locales as $locale): ?>
         <?php
         $isActive = $locale === I18n::$locale;
@@ -66,7 +42,7 @@ $publicTarget = ltrim($publicTarget, '/');
     <?php endforeach; ?>
 <?php else: ?>
     <?php if ($isLoggedIn): ?>
-        <form class="nav nav--lang" method="get" action="<?php e($baseUrl); ?>" aria-label="Language switcher">
+        <form class="nav nav--lang" method="get" action="<?php e($baseUrl); ?>" aria-label="<?php e(t('Language switcher')); ?>">
             <input type="hidden" name="return" value="<?php e($returnTarget); ?>">
             <select class="lang-select" name="locale" onchange="this.form.submit()">
                 <?php foreach ($locales as $locale): ?>
@@ -77,7 +53,7 @@ $publicTarget = ltrim($publicTarget, '/');
             </select>
         </form>
     <?php else: ?>
-        <div class="nav nav--lang" role="listbox" aria-label="Language switcher">
+        <div class="nav nav--lang" role="listbox" aria-label="<?php e(t('Language switcher')); ?>">
             <?php foreach ($locales as $locale): ?>
                 <?php
                 $publicUrl = $base . '/' . $locale . ($publicTarget !== '' ? '/' . $publicTarget : '');
diff --git a/tests/Architecture/AgentSystemContractTest.php b/tests/Architecture/AgentSystemContractTest.php
new file mode 100644
index 0000000..a149558
--- /dev/null
+++ b/tests/Architecture/AgentSystemContractTest.php
@@ -0,0 +1,137 @@
+<?php
+
+namespace MintyPHP\Tests\Architecture;
+
+use PHPUnit\Framework\TestCase;
+
+class AgentSystemContractTest extends TestCase
+{
+    use ProjectFileAssertionSupport;
+
+    public function testAgentSystemJsonFilesAreValidJson(): void
+    {
+        $jsonFiles = [
+            'agent-system/checks/guard-catalog.json',
+            'agent-system/checks/quality-gates.json',
+            'agent-system/contracts/planner.schema.json',
+            'agent-system/contracts/executor.schema.json',
+            'agent-system/contracts/reviewer-guards.schema.json',
+            'agent-system/contracts/reviewer-acceptance.schema.json',
+            'agent-system/contracts/finalizer.schema.json',
+            'agent-system/templates/plan.template.json',
+            'agent-system/templates/execution-report.template.json',
+            'agent-system/templates/review-guards.template.json',
+            'agent-system/templates/review-acceptance.template.json',
+            'agent-system/templates/finalize.template.json',
+        ];
+
+        foreach ($jsonFiles as $file) {
+            $decoded = json_decode($this->readProjectFile($file), true);
+            $this->assertIsArray($decoded, 'Invalid JSON: ' . $file);
+        }
+    }
+
+    public function testGuardCatalogIdsAreUniqueAndWellFormed(): void
+    {
+        $catalog = $this->decodeJson('agent-system/checks/guard-catalog.json');
+        $guards = is_array($catalog['guards'] ?? null) ? $catalog['guards'] : [];
+        $this->assertNotSame([], $guards, 'Guard catalog must not be empty.');
+
+        $ids = [];
+        foreach ($guards as $guard) {
+            $id = (string) ($guard['id'] ?? '');
+            $source = (string) ($guard['source'] ?? '');
+            $this->assertMatchesRegularExpression('/^GR-[A-Z]+-[0-9]{3}$/', $id, 'Invalid guard id: ' . $id);
+            $this->assertNotSame('', $source, 'Missing guard source for ' . $id);
+            $sourcePath = explode('#', $source)[0];
+            $this->readProjectFile($sourcePath);
+            $ids[] = $id;
+        }
+
+        $this->assertSame($ids, array_values(array_unique($ids)), 'Duplicate guard IDs found.');
+    }
+
+    public function testQualityGateIdsAreUniqueAndWellFormed(): void
+    {
+        $gates = $this->decodeJson('agent-system/checks/quality-gates.json');
+        $items = is_array($gates['gates'] ?? null) ? $gates['gates'] : [];
+        $this->assertNotSame([], $items, 'Quality gates must not be empty.');
+
+        $ids = [];
+        foreach ($items as $gate) {
+            $id = (string) ($gate['id'] ?? '');
+            $command = (string) ($gate['command'] ?? '');
+            $this->assertMatchesRegularExpression('/^QG-[0-9]{3}$/', $id, 'Invalid quality gate id: ' . $id);
+            $this->assertNotSame('', trim($command), 'Missing command for ' . $id);
+            $ids[] = $id;
+        }
+
+        $this->assertSame($ids, array_values(array_unique($ids)), 'Duplicate quality gate IDs found.');
+    }
+
+    public function testTemplatesReferenceKnownGuardAndGateIds(): void
+    {
+        $catalog = $this->decodeJson('agent-system/checks/guard-catalog.json');
+        $gates = $this->decodeJson('agent-system/checks/quality-gates.json');
+        $guardIds = array_map(
+            static fn (array $guard): string => (string) ($guard['id'] ?? ''),
+            is_array($catalog['guards'] ?? null) ? $catalog['guards'] : []
+        );
+        $gateIds = array_map(
+            static fn (array $gate): string => (string) ($gate['id'] ?? ''),
+            is_array($gates['gates'] ?? null) ? $gates['gates'] : []
+        );
+
+        $planTemplate = $this->decodeJson('agent-system/templates/plan.template.json');
+        $planGuardIds = is_array($planTemplate['guardrails']['required_guard_ids'] ?? null)
+            ? $planTemplate['guardrails']['required_guard_ids']
+            : [];
+        $planGateIds = is_array($planTemplate['guardrails']['required_quality_gate_ids'] ?? null)
+            ? $planTemplate['guardrails']['required_quality_gate_ids']
+            : [];
+        foreach ($planGuardIds as $id) {
+            $this->assertContains($id, $guardIds, 'Unknown guard id in plan template: ' . (string) $id);
+        }
+        foreach ($planGateIds as $id) {
+            $this->assertContains($id, $gateIds, 'Unknown gate id in plan template: ' . (string) $id);
+        }
+
+        $reviewGuardsTemplate = $this->decodeJson('agent-system/templates/review-guards.template.json');
+        $reviewGuardIds = is_array($reviewGuardsTemplate['checked_guard_ids'] ?? null)
+            ? $reviewGuardsTemplate['checked_guard_ids']
+            : [];
+        $reviewGateIds = is_array($reviewGuardsTemplate['checked_quality_gate_ids'] ?? null)
+            ? $reviewGuardsTemplate['checked_quality_gate_ids']
+            : [];
+        foreach ($reviewGuardIds as $id) {
+            $this->assertContains($id, $guardIds, 'Unknown guard id in review template: ' . (string) $id);
+        }
+        foreach ($reviewGateIds as $id) {
+            $this->assertContains($id, $gateIds, 'Unknown gate id in review template: ' . (string) $id);
+        }
+    }
+
+    public function testRolePromptsReferenceGuardCatalogAndQualityGates(): void
+    {
+        $plannerPrompt = $this->readProjectFile('agent-system/prompts/planner.md');
+        $executorPrompt = $this->readProjectFile('agent-system/prompts/executor.md');
+        $reviewerPrompt = $this->readProjectFile('agent-system/prompts/reviewer-guards.md');
+
+        $this->assertStringContainsString('agent-system/checks/guard-catalog.json', $plannerPrompt);
+        $this->assertStringContainsString('agent-system/checks/quality-gates.json', $plannerPrompt);
+        $this->assertStringContainsString('agent-system/checks/guard-catalog.json', $executorPrompt);
+        $this->assertStringContainsString('agent-system/checks/quality-gates.json', $executorPrompt);
+        $this->assertStringContainsString('agent-system/checks/guard-catalog.json', $reviewerPrompt);
+        $this->assertStringContainsString('agent-system/checks/quality-gates.json', $reviewerPrompt);
+    }
+
+    /**
+     * @return array<string,mixed>
+     */
+    private function decodeJson(string $path): array
+    {
+        $decoded = json_decode($this->readProjectFile($path), true);
+        $this->assertIsArray($decoded, 'Invalid JSON in ' . $path);
+        return $decoded;
+    }
+}
diff --git a/tests/Architecture/CodexSkillsContractTest.php b/tests/Architecture/CodexSkillsContractTest.php
index dad37d7..199f209 100644
--- a/tests/Architecture/CodexSkillsContractTest.php
+++ b/tests/Architecture/CodexSkillsContractTest.php
@@ -12,9 +12,6 @@ class CodexSkillsContractTest extends TestCase
     {
         $skill = $this->readProjectFile('tools/codex-skills/core-guardrails/SKILL.md');
         $this->assertStringContainsString('name: core-guardrails', $skill);
-        $this->assertStringContainsString('MUST', $skill);
-        $this->assertStringContainsString('MUST NOT', $skill);
-        $this->assertStringContainsString('Out of Scope', $skill);
 
         $this->readProjectFile('tools/codex-skills/core-guardrails/references/boundaries-core.md');
         $this->readProjectFile('tools/codex-skills/core-guardrails/references/boundaries-ui.md');
@@ -22,22 +19,36 @@ class CodexSkillsContractTest extends TestCase
         $this->readProjectFile('tools/codex-skills/core-guardrails/references/source-map.md');
     }
 
-    public function testStarterkitPlannerSkillContainsDecisionCompleteTemplateContract(): void
+    public function testStarterkitPlannerSkillAndReferencesExist(): void
     {
         $skill = $this->readProjectFile('tools/codex-skills/starterkit-planner/SKILL.md');
         $this->assertStringContainsString('name: starterkit-planner', $skill);
-        $this->assertStringContainsString('Decision-complete Implementierungsplan', $skill);
 
         $this->readProjectFile('tools/codex-skills/starterkit-planner/references/plan-template.md');
         $this->readProjectFile('tools/codex-skills/starterkit-planner/references/tradeoff-matrix.md');
     }
 
-    public function testCodexPromptsDocumentationReferencesBothSkillsAndExtensionScope(): void
+    public function testStarterkitGridStandardsSkillAndReferencesExist(): void
+    {
+        $skill = $this->readProjectFile('tools/codex-skills/starterkit-grid-standards/SKILL.md');
+        $this->assertStringContainsString('name: starterkit-grid-standards', $skill);
+
+        $this->readProjectFile('tools/codex-skills/starterkit-grid-standards/references/list-checklist.md');
+        $this->readProjectFile('tools/codex-skills/starterkit-grid-standards/references/row-interaction-standard.md');
+        $this->readProjectFile('tools/codex-skills/starterkit-grid-standards/references/page-size-standard.md');
+    }
+
+    public function testStarterkitPhpStyleCiSkillExists(): void
+    {
+        $skill = $this->readProjectFile('tools/codex-skills/starterkit-php-style-ci/SKILL.md');
+        $this->assertStringContainsString('name: starterkit-php-style-ci', $skill);
+    }
+
+    public function testCodexPromptsDocumentationReferencesBothSkills(): void
     {
         $prompts = $this->readProjectFile('docs/codex-prompts.md');
         $this->assertStringContainsString('core-guardrails', $prompts);
         $this->assertStringContainsString('starterkit-planner', $prompts);
-        $this->assertStringContainsString('Out of Scope: Extensions', $prompts);
     }
 
     public function testDocsIndexReferencesCodexPrompts(): void
@@ -52,7 +63,5 @@ class CodexSkillsContractTest extends TestCase
         $this->assertStringContainsString('--check', $script);
         $this->assertStringContainsString('--apply', $script);
         $this->assertStringContainsString('mode="check"', $script);
-        $this->assertStringContainsString('core-guardrails', $script);
-        $this->assertStringContainsString('starterkit-planner', $script);
     }
 }
diff --git a/tests/Architecture/CoreStarterkitContractTest.php b/tests/Architecture/CoreStarterkitContractTest.php
index 0533293..b11ff47 100644
--- a/tests/Architecture/CoreStarterkitContractTest.php
+++ b/tests/Architecture/CoreStarterkitContractTest.php
@@ -41,6 +41,9 @@ class CoreStarterkitContractTest extends TestCase
             '/\$_GET/' => '$_GET',
             '/\$_FILES/' => '$_FILES',
             '/REQUEST_METHOD/' => 'REQUEST_METHOD',
+            '/\$_SESSION/' => '$_SESSION',
+            '/\$_SERVER/' => '$_SERVER',
+            '/\$_COOKIE/' => '$_COOKIE',
         ];
 
         foreach ($patterns as $pattern => $label) {
@@ -49,29 +52,30 @@ class CoreStarterkitContractTest extends TestCase
         }
     }
 
+    public function testServicesDoNotUseSuperglobals(): void
+    {
+        $patterns = [
+            '/\$_POST/' => '$_POST',
+            '/\$_GET/' => '$_GET',
+            '/\$_FILES/' => '$_FILES',
+            '/\$_SERVER/' => '$_SERVER',
+            '/\$_COOKIE/' => '$_COOKIE',
+            '/\$_SESSION/' => '$_SESSION',
+            '/\$_REQUEST/' => '$_REQUEST',
+        ];
+
+        foreach ($patterns as $pattern => $label) {
+            $violations = $this->findPatternMatchesInPhpFiles('lib/Service', $pattern);
+            $this->assertSame([], $violations, "Superglobal {$label} usage found in lib/Service/:\n" . implode("\n", $violations));
+        }
+    }
+
     public function testApiPagesDoNotReadJsonBodyDirectly(): void
     {
         $violations = $this->findPatternMatchesInPhpFiles('pages/api/v1', '/ApiResponse::readJsonBody\s*\(/');
         $this->assertSame([], $violations, "ApiResponse::readJsonBody usage found in pages/api/v1/:\n" . implode("\n", $violations));
     }
 
-    public function testLegacyAndTemplateModulesAreRemoved(): void
-    {
-        $root = $this->projectRootPath();
-        $this->assertFileDoesNotExist(
-            $root . '/web/js/components/app-filter-overflow.js',
-            'Legacy filter overflow module must remain removed.'
-        );
-        $this->assertFileDoesNotExist(
-            $root . '/web/js/components/app-toggle-toolbar.js',
-            'Legacy toolbar toggle module must remain removed.'
-        );
-        $this->assertFileDoesNotExist(
-            $root . '/web/js/components/_template.js',
-            'Component template module must remain removed from production JS path.'
-        );
-    }
-
     public function testTemplatesDoNotUseLegacyFilterToggleMarkup(): void
     {
         $pattern = '/data-(?:toolbar-toggle|filter-overflow|filter-toggle)/';
@@ -108,6 +112,34 @@ class CoreStarterkitContractTest extends TestCase
         $this->assertSame([], $violations, "asset(...) JS URLs found in templates/pages:\n" . implode("\n", $violations));
     }
 
+    public function testNoLegacySettingsGatewayOrServiceReferencesExist(): void
+    {
+        $patterns = [
+            '/\bSettingService::class\b/' => 'SettingService::class',
+            '/\bSettingGateway::class\b/' => 'SettingGateway::class',
+            '/\bnew\s+SettingService\s*\(/' => 'new SettingService(...)',
+            '/\bnew\s+SettingGateway\s*\(/' => 'new SettingGateway(...)',
+            '/use\s+[^;]*\\\\SettingService;/' => 'use ...\\SettingService',
+            '/use\s+[^;]*\\\\SettingGateway;/' => 'use ...\\SettingGateway',
+        ];
+
+        foreach ($patterns as $pattern => $label) {
+            $violations = array_merge(
+                $this->findPatternMatchesInPhpFiles('lib', $pattern),
+                $this->findPatternMatchesInPhpFiles('pages', $pattern),
+                $this->findPatternMatchesInPhpFiles('tests', $pattern),
+            );
+            $violations = array_values(array_filter(
+                $violations,
+                static fn (string $path): bool => $path !== 'tests/Architecture/CoreStarterkitContractTest.php'
+            ));
+            $violations = array_values(array_unique($violations));
+            sort($violations);
+
+            $this->assertSame([], $violations, "Legacy settings reference {$label} found:\n" . implode("\n", $violations));
+        }
+    }
+
     /**
      * @return list<string>
      */
diff --git a/tests/Architecture/FrontendTelemetryContractTest.php b/tests/Architecture/FrontendTelemetryContractTest.php
new file mode 100644
index 0000000..f0c0b21
--- /dev/null
+++ b/tests/Architecture/FrontendTelemetryContractTest.php
@@ -0,0 +1,173 @@
+<?php
+
+namespace MintyPHP\Tests\Architecture;
+
+use PHPUnit\Framework\TestCase;
+
+class FrontendTelemetryContractTest extends TestCase
+{
+    use ProjectFileAssertionSupport;
+
+    public function testEventTypeMappingsStayInSyncAcrossFrontendAndBackend(): void
+    {
+        $js = $this->readProjectFile('web/js/core/app-telemetry.js');
+        $ingest = $this->readProjectFile('lib/Service/Audit/FrontendTelemetryIngestService.php');
+        $settings = $this->readProjectFile('lib/Service/Settings/SettingsFrontendTelemetryGateway.php');
+
+        $jsMap = $this->parseJsEventKeyToTypeMap($js);
+        $phpMap = $this->parsePhpEventTypeToKeyMap($ingest);
+
+        $expectedPhpMap = array_flip($jsMap);
+        ksort($expectedPhpMap);
+        ksort($phpMap);
+        $this->assertSame($expectedPhpMap, $phpMap);
+
+        $settingsAllowedEvents = $this->parsePhpStringArrayConstant(
+            $settings,
+            'FRONTEND_TELEMETRY_ALLOWED_EVENTS'
+        );
+        sort($settingsAllowedEvents, SORT_STRING);
+        $expectedAllowedEvents = array_keys($jsMap);
+        sort($expectedAllowedEvents, SORT_STRING);
+        $this->assertSame($expectedAllowedEvents, $settingsAllowedEvents);
+    }
+
+    public function testAllowedMetaKeysStayInSyncAcrossFrontendAndBackend(): void
+    {
+        $js = $this->readProjectFile('web/js/core/app-telemetry.js');
+        $ingest = $this->readProjectFile('lib/Service/Audit/FrontendTelemetryIngestService.php');
+
+        $jsKeys = $this->parseJsStringSet($js, 'ALLOWED_META_KEYS');
+        $phpKeys = $this->parsePhpStringArrayConstant($ingest, 'ALLOWED_META_KEYS');
+
+        sort($jsKeys, SORT_STRING);
+        sort($phpKeys, SORT_STRING);
+        $this->assertSame($jsKeys, $phpKeys);
+    }
+
+    public function testLengthLimitsStayInSyncAcrossFrontendAndBackend(): void
+    {
+        $js = $this->readProjectFile('web/js/core/app-telemetry.js');
+        $ingest = $this->readProjectFile('lib/Service/Audit/FrontendTelemetryIngestService.php');
+
+        $this->assertSame(
+            $this->parseJsIntConstant($js, 'MAX_MESSAGE_LENGTH'),
+            $this->parsePhpIntConstant($ingest, 'MESSAGE_MAX_LENGTH')
+        );
+        $this->assertSame(
+            $this->parseJsIntConstant($js, 'MAX_FINGERPRINT_LENGTH'),
+            $this->parsePhpIntConstant($ingest, 'FINGERPRINT_MAX_LENGTH')
+        );
+        $this->assertSame(
+            $this->parseJsIntConstant($js, 'MAX_META_ENTRIES'),
+            $this->parsePhpIntConstant($ingest, 'META_MAX_ENTRIES')
+        );
+        $this->assertSame(
+            $this->parseJsIntConstant($js, 'MAX_META_VALUE_LENGTH'),
+            $this->parsePhpIntConstant($ingest, 'META_VALUE_MAX_LENGTH')
+        );
+    }
+
+    /**
+     * @return array<string,string>
+     */
+    private function parseJsEventKeyToTypeMap(string $content): array
+    {
+        if (preg_match('/const\s+EVENT_KEY_TO_TYPE\s*=\s*Object\.freeze\(\{(.*?)\}\);/s', $content, $match) !== 1) {
+            $this->fail('Could not parse EVENT_KEY_TO_TYPE from JS telemetry module.');
+        }
+
+        $map = [];
+        preg_match_all('/([a-z_]+)\s*:\s*\'([^\']+)\'/', $match[1], $pairs, PREG_SET_ORDER);
+        foreach ($pairs as $pair) {
+            $map[$pair[1]] = $pair[2];
+        }
+
+        $this->assertNotSame([], $map, 'EVENT_KEY_TO_TYPE map is empty.');
+        return $map;
+    }
+
+    /**
+     * @return array<string,string>
+     */
+    private function parsePhpEventTypeToKeyMap(string $content): array
+    {
+        $constValues = [];
+        preg_match_all('/private const\s+([A-Z0-9_]+)\s*=\s*\'([^\']+)\';/', $content, $constants, PREG_SET_ORDER);
+        foreach ($constants as $constant) {
+            $constValues[$constant[1]] = $constant[2];
+        }
+
+        if (preg_match('/private const EVENT_KEY_MAP = \[(.*?)\];/s', $content, $match) !== 1) {
+            $this->fail('Could not parse EVENT_KEY_MAP from ingest service.');
+        }
+
+        $map = [];
+        preg_match_all('/self::([A-Z0-9_]+)\s*=>\s*\'([a-z_]+)\'/', $match[1], $pairs, PREG_SET_ORDER);
+        foreach ($pairs as $pair) {
+            $eventConstant = $pair[1];
+            $eventType = $constValues[$eventConstant] ?? '';
+            $this->assertNotSame('', $eventType, 'Missing event constant for EVENT_KEY_MAP entry: ' . $eventConstant);
+            $map[$eventType] = $pair[2];
+        }
+
+        $this->assertNotSame([], $map, 'EVENT_KEY_MAP is empty.');
+        return $map;
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function parseJsStringSet(string $content, string $constantName): array
+    {
+        $pattern = '/const\s+' . preg_quote($constantName, '/') . '\s*=\s*new Set\(\[(.*?)\]\);/s';
+        if (preg_match($pattern, $content, $match) !== 1) {
+            $this->fail('Could not parse JS Set constant: ' . $constantName);
+        }
+
+        $values = [];
+        preg_match_all('/\'([^\']+)\'/', $match[1], $items, PREG_SET_ORDER);
+        foreach ($items as $item) {
+            $values[] = $item[1];
+        }
+
+        return array_values(array_unique($values));
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function parsePhpStringArrayConstant(string $content, string $constantName): array
+    {
+        $pattern = '/private const\s+' . preg_quote($constantName, '/') . '\s*=\s*\[(.*?)\];/s';
+        if (preg_match($pattern, $content, $match) !== 1) {
+            $this->fail('Could not parse PHP array constant: ' . $constantName);
+        }
+
+        $values = [];
+        preg_match_all('/\'([^\']+)\'/', $match[1], $items, PREG_SET_ORDER);
+        foreach ($items as $item) {
+            $values[] = $item[1];
+        }
+
+        return array_values(array_unique($values));
+    }
+
+    private function parseJsIntConstant(string $content, string $constantName): int
+    {
+        $pattern = '/const\s+' . preg_quote($constantName, '/') . '\s*=\s*([0-9]+)\s*;/';
+        if (preg_match($pattern, $content, $match) !== 1) {
+            $this->fail('Could not parse JS integer constant: ' . $constantName);
+        }
+        return (int) $match[1];
+    }
+
+    private function parsePhpIntConstant(string $content, string $constantName): int
+    {
+        $pattern = '/private const\s+' . preg_quote($constantName, '/') . '\s*=\s*([0-9]+)\s*;/';
+        if (preg_match($pattern, $content, $match) !== 1) {
+            $this->fail('Could not parse PHP integer constant: ' . $constantName);
+        }
+        return (int) $match[1];
+    }
+}
diff --git a/tests/Service/Audit/ApiAuditServiceTest.php b/tests/Service/Audit/ApiAuditServiceTest.php
index 51fd12d..c033ae6 100644
--- a/tests/Service/Audit/ApiAuditServiceTest.php
+++ b/tests/Service/Audit/ApiAuditServiceTest.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Tests\Service\Audit;
 
+use MintyPHP\Http\RequestRuntime;
 use MintyPHP\Http\RequestContext;
 use MintyPHP\Repository\Audit\ApiAuditLogRepositoryInterface;
 use MintyPHP\Service\Audit\ApiAuditService;
@@ -28,7 +29,10 @@ class ApiAuditServiceTest extends TestCase
 
     public function testCurrentRequestIdIsNullBeforeStart(): void
     {
-        $service = new ApiAuditService($this->createMock(ApiAuditLogRepositoryInterface::class));
+        $service = new ApiAuditService(
+            $this->createMock(ApiAuditLogRepositoryInterface::class),
+            new RequestRuntime()
+        );
         $this->assertNull($service->currentRequestId());
     }
 
@@ -38,7 +42,10 @@ class ApiAuditServiceTest extends TestCase
         $_SERVER['REQUEST_URI'] = '/api/v1/me?x=1';
         $_GET = ['x' => '1'];
 
-        $service = new ApiAuditService($this->createMock(ApiAuditLogRepositoryInterface::class));
+        $service = new ApiAuditService(
+            $this->createMock(ApiAuditLogRepositoryInterface::class),
+            new RequestRuntime()
+        );
         $service->startRequestContext();
 
         $requestId = $service->currentRequestId();
@@ -58,7 +65,10 @@ class ApiAuditServiceTest extends TestCase
         $_SERVER['REQUEST_URI'] = '/api/v1/me';
         $_GET = [];
 
-        $service = new ApiAuditService($this->createMock(ApiAuditLogRepositoryInterface::class));
+        $service = new ApiAuditService(
+            $this->createMock(ApiAuditLogRepositoryInterface::class),
+            new RequestRuntime()
+        );
         $service->startRequestContext();
 
         $this->assertNull($service->currentRequestId());
diff --git a/tests/Service/Audit/FrontendTelemetryIngestServiceTest.php b/tests/Service/Audit/FrontendTelemetryIngestServiceTest.php
new file mode 100644
index 0000000..617798d
--- /dev/null
+++ b/tests/Service/Audit/FrontendTelemetryIngestServiceTest.php
@@ -0,0 +1,332 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Audit;
+
+use MintyPHP\Http\RequestContext;
+use MintyPHP\Http\SessionStoreInterface;
+use MintyPHP\Service\Audit\FrontendTelemetryIngestService;
+use MintyPHP\Service\Audit\SystemAuditService;
+use MintyPHP\Service\Security\RateLimiterService;
+use MintyPHP\Service\Settings\SettingsFrontendTelemetryGateway;
+use PHPUnit\Framework\TestCase;
+
+class FrontendTelemetryIngestServiceTest extends TestCase
+{
+    protected function tearDown(): void
+    {
+        RequestContext::resetForTests();
+        $_SESSION = [];
+    }
+
+    public function testIngestSkipsWhenDisabled(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->never())->method('record');
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(false);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturn([]);
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $result = $service->ingest([
+            'event_type' => 'frontend.warn_once',
+            'message' => 'warn',
+        ]);
+
+        $this->assertSame(['accepted' => false, 'reason' => 'disabled'], $result);
+    }
+
+    public function testIngestRejectsInvalidPayload(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->never())->method('record');
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturn([]);
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $result = $service->ingest([
+            'event_type' => 'unknown',
+            'message' => '',
+        ]);
+
+        $this->assertSame(['accepted' => false, 'reason' => 'invalid'], $result);
+    }
+
+    public function testIngestRecordsSanitizedPayload(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->once())
+            ->method('record')
+            ->with(
+                'frontend.warn_once',
+                'success',
+                $this->callback(function (array $context): bool {
+                    $metadata = $context['metadata'] ?? [];
+                    $message = (string) ($metadata['message'] ?? '');
+                    if (!str_contains($message, '[REDACTED_EMAIL]')) {
+                        return false;
+                    }
+
+                    if (!str_contains($message, 'token=[REDACTED]')) {
+                        return false;
+                    }
+
+                    $meta = is_array($metadata['meta'] ?? null) ? $metadata['meta'] : [];
+                    $requestPath = (string) ($meta['request_path'] ?? '');
+                    return $requestPath === '/admin/users/:id';
+                })
+            )
+            ->willReturn(5);
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+        $gateway->method('getFrontendTelemetryAllowedEvents')->willReturn(['warn_once', 'ajax_error']);
+        $gateway->method('getFrontendTelemetrySampleRate')->willReturn(1.0);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $rateLimiter->method('hit')->willReturn(['allowed' => true, 'retry_after' => 0]);
+
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturn(['user' => ['id' => 7]]);
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $result = $service->ingest([
+            'event_type' => 'frontend.warn_once',
+            'severity' => 'warning',
+            'message' => 'Problem for user test@example.com token=supersecret1234567890',
+            'fingerprint' => 'v1_warn_once_123',
+            'meta' => ['request_path' => '/admin/users/123?email=a@b.de'],
+            'occurred_at' => '2026-03-05T12:00:00+01:00',
+        ]);
+
+        $this->assertSame(['accepted' => true, 'reason' => 'logged'], $result);
+    }
+
+    public function testIngestBuildsFallbackFingerprintUsingRouteBeforeMessage(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->once())
+            ->method('record')
+            ->with(
+                'frontend.warn_once',
+                'success',
+                $this->callback(static function (array $context): bool {
+                    $metadata = is_array($context['metadata'] ?? null) ? $context['metadata'] : [];
+                    $fingerprintHash = (string) ($metadata['fingerprint_hash'] ?? '');
+                    $expectedFingerprint = 'v1_' . substr(hash('sha256', 'frontend.warn_once|/admin/users/:id|Grid init failed'), 0, 24);
+                    return $fingerprintHash === RequestContext::hashValue($expectedFingerprint);
+                })
+            )
+            ->willReturn(6);
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+        $gateway->method('getFrontendTelemetryAllowedEvents')->willReturn(['warn_once', 'ajax_error']);
+        $gateway->method('getFrontendTelemetrySampleRate')->willReturn(1.0);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $rateLimiter->method('hit')->willReturn(['allowed' => true, 'retry_after' => 0]);
+
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturn(['user' => ['id' => 7]]);
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $result = $service->ingest([
+            'event_type' => 'frontend.warn_once',
+            'severity' => 'warning',
+            'message' => 'Grid init failed',
+            'meta' => ['location' => '/admin/users/123'],
+            'occurred_at' => '2026-03-05T12:00:00+01:00',
+        ]);
+
+        $this->assertSame(['accepted' => true, 'reason' => 'logged'], $result);
+    }
+
+    public function testIngestRejectsInvalidPageRequestIdPattern(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->once())
+            ->method('record')
+            ->with(
+                'frontend.warn_once',
+                'success',
+                $this->callback(static function (array $context): bool {
+                    $metadata = is_array($context['metadata'] ?? null) ? $context['metadata'] : [];
+                    $meta = is_array($metadata['meta'] ?? null) ? $metadata['meta'] : [];
+                    return !array_key_exists('page_request_id', $meta);
+                })
+            )
+            ->willReturn(8);
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+        $gateway->method('getFrontendTelemetryAllowedEvents')->willReturn(['warn_once', 'ajax_error']);
+        $gateway->method('getFrontendTelemetrySampleRate')->willReturn(1.0);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $rateLimiter->method('hit')->willReturn(['allowed' => true, 'retry_after' => 0]);
+
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturn(['user' => ['id' => 7]]);
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $result = $service->ingest([
+            'event_type' => 'frontend.warn_once',
+            'severity' => 'warning',
+            'message' => 'Invalid request id should be dropped',
+            'fingerprint' => 'v1_invalid_request_id',
+            'meta' => ['page_request_id' => '------------------------------------'],
+        ]);
+
+        $this->assertSame(['accepted' => true, 'reason' => 'logged'], $result);
+    }
+
+    public function testIngestUsesSingleSessionStateReadWriteForGuards(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->once())
+            ->method('record')
+            ->willReturn(7);
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+        $gateway->method('getFrontendTelemetryAllowedEvents')->willReturn(['warn_once', 'ajax_error']);
+        $gateway->method('getFrontendTelemetrySampleRate')->willReturn(1.0);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $rateLimiter->expects($this->once())
+            ->method('hit')
+            ->willReturn(['allowed' => true, 'retry_after' => 0]);
+
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->expects($this->once())->method('all')->willReturn(['user' => ['id' => 7]]);
+        $sessionStore->expects($this->once())
+            ->method('get')
+            ->with('frontend_telemetry_state', [])
+            ->willReturn([]);
+        $sessionStore->expects($this->once())
+            ->method('set')
+            ->with(
+                'frontend_telemetry_state',
+                $this->callback(static function (mixed $value): bool {
+                    if (!is_array($value)) {
+                        return false;
+                    }
+                    if (!is_array($value['dedupe'] ?? null)) {
+                        return false;
+                    }
+                    if (!is_array($value['burst'] ?? null)) {
+                        return false;
+                    }
+                    return true;
+                })
+            );
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $result = $service->ingest([
+            'event_type' => 'frontend.warn_once',
+            'severity' => 'warning',
+            'message' => 'single state write',
+            'fingerprint' => 'v1_single_state_write',
+            'meta' => ['location' => '/admin/test'],
+        ]);
+
+        $this->assertSame(['accepted' => true, 'reason' => 'logged'], $result);
+    }
+
+    public function testIngestDropsDuplicateFingerprint(): void
+    {
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->expects($this->once())->method('record')->willReturn(9);
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+        $gateway->method('getFrontendTelemetryAllowedEvents')->willReturn(['warn_once', 'ajax_error']);
+        $gateway->method('getFrontendTelemetrySampleRate')->willReturn(1.0);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $rateLimiter->method('hit')->willReturn(['allowed' => true, 'retry_after' => 0]);
+
+        $sessionData = ['user' => ['id' => 7]];
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturnCallback(static fn (): array => $sessionData);
+        $sessionStore->method('get')->willReturnCallback(static function (string $key, mixed $default = null) use (&$sessionData): mixed {
+            return $sessionData[$key] ?? $default;
+        });
+        $sessionStore->method('set')->willReturnCallback(static function (string $key, mixed $value) use (&$sessionData): void {
+            $sessionData[$key] = $value;
+        });
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+        $first = $service->ingest([
+            'event_type' => 'frontend.ajax_error',
+            'message' => 'AJAX request failed',
+            'fingerprint' => 'v1_ajax_error_1',
+        ]);
+        $second = $service->ingest([
+            'event_type' => 'frontend.ajax_error',
+            'message' => 'AJAX request failed',
+            'fingerprint' => 'v1_ajax_error_1',
+        ]);
+
+        $this->assertSame(['accepted' => true, 'reason' => 'logged'], $first);
+        $this->assertSame(['accepted' => false, 'reason' => 'duplicate'], $second);
+    }
+
+    public function testIngestAppliesSessionBurstFastDropBeforeGlobalRateLimit(): void
+    {
+        $recordCalls = 0;
+        $rateLimiterCalls = 0;
+
+        $audit = $this->createMock(SystemAuditService::class);
+        $audit->method('record')->willReturnCallback(static function () use (&$recordCalls): int {
+            $recordCalls++;
+            return $recordCalls;
+        });
+
+        $gateway = $this->createMock(SettingsFrontendTelemetryGateway::class);
+        $gateway->method('isFrontendTelemetryEnabled')->willReturn(true);
+        $gateway->method('getFrontendTelemetryAllowedEvents')->willReturn(['warn_once', 'ajax_error']);
+        $gateway->method('getFrontendTelemetrySampleRate')->willReturn(1.0);
+
+        $rateLimiter = $this->createMock(RateLimiterService::class);
+        $rateLimiter->method('hit')->willReturnCallback(static function () use (&$rateLimiterCalls): array {
+            $rateLimiterCalls++;
+            return ['allowed' => true, 'retry_after' => 0];
+        });
+
+        $sessionData = ['user' => ['id' => 7]];
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('all')->willReturnCallback(static fn (): array => $sessionData);
+        $sessionStore->method('get')->willReturnCallback(static function (string $key, mixed $default = null) use (&$sessionData): mixed {
+            return $sessionData[$key] ?? $default;
+        });
+        $sessionStore->method('set')->willReturnCallback(static function (string $key, mixed $value) use (&$sessionData): void {
+            $sessionData[$key] = $value;
+        });
+
+        $service = new FrontendTelemetryIngestService($audit, $gateway, $rateLimiter, $sessionStore);
+
+        $lastResult = ['accepted' => true, 'reason' => 'logged'];
+        for ($index = 0; $index < 120; $index++) {
+            $lastResult = $service->ingest([
+                'event_type' => 'frontend.ajax_error',
+                'message' => 'AJAX request failed',
+                'fingerprint' => 'v1_ajax_error_' . $index,
+            ]);
+        }
+
+        $this->assertSame(['accepted' => false, 'reason' => 'burst_limited'], $lastResult);
+        $this->assertGreaterThan(0, $recordCalls);
+        $this->assertLessThan(120, $recordCalls);
+        $this->assertSame($recordCalls, $rateLimiterCalls);
+    }
+}
diff --git a/tests/Service/Audit/SystemAuditServiceTest.php b/tests/Service/Audit/SystemAuditServiceTest.php
index db78272..5a1c2da 100644
--- a/tests/Service/Audit/SystemAuditServiceTest.php
+++ b/tests/Service/Audit/SystemAuditServiceTest.php
@@ -2,11 +2,12 @@
 
 namespace MintyPHP\Tests\Service\Audit;
 
+use MintyPHP\Http\SessionStore;
 use MintyPHP\Http\RequestContext;
 use MintyPHP\Repository\Audit\SystemAuditLogRepository;
 use MintyPHP\Service\Audit\SystemAuditRedactionService;
 use MintyPHP\Service\Audit\SystemAuditService;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsSystemAuditGateway;
 use PHPUnit\Framework\TestCase;
 
 class SystemAuditServiceTest extends TestCase
@@ -14,6 +15,7 @@ class SystemAuditServiceTest extends TestCase
     protected function tearDown(): void
     {
         RequestContext::resetForTests();
+        $_SESSION = [];
     }
 
     public function testRecordReturnsNullWhenDisabled(): void
@@ -21,10 +23,10 @@ class SystemAuditServiceTest extends TestCase
         $repo = $this->createMock(SystemAuditLogRepository::class);
         $repo->expects($this->never())->method('create');
 
-        $settings = $this->createMock(SettingGateway::class);
+        $settings = $this->createMock(SettingsSystemAuditGateway::class);
         $settings->expects($this->once())->method('isSystemAuditEnabled')->willReturn(false);
 
-        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings);
+        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings, new SessionStore());
 
         $this->assertNull($service->record('admin.users.update', 'success'));
     }
@@ -39,10 +41,10 @@ class SystemAuditServiceTest extends TestCase
         $repo = $this->createMock(SystemAuditLogRepository::class);
         $repo->expects($this->once())->method('create')->willReturn(5);
 
-        $settings = $this->createMock(SettingGateway::class);
+        $settings = $this->createMock(SettingsSystemAuditGateway::class);
         $settings->method('isSystemAuditEnabled')->willReturn(true);
 
-        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings);
+        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings, new SessionStore());
 
         $id = $service->record('admin.users.update', 'success', [
             'target_type' => 'user',
@@ -59,10 +61,10 @@ class SystemAuditServiceTest extends TestCase
         $repo = $this->createMock(SystemAuditLogRepository::class);
         $repo->method('create')->willThrowException(new \RuntimeException('db down'));
 
-        $settings = $this->createMock(SettingGateway::class);
+        $settings = $this->createMock(SettingsSystemAuditGateway::class);
         $settings->method('isSystemAuditEnabled')->willReturn(true);
 
-        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings);
+        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings, new SessionStore());
 
         $this->assertNull($service->record('admin.users.update', 'success'));
     }
@@ -72,10 +74,10 @@ class SystemAuditServiceTest extends TestCase
         $repo = $this->createMock(SystemAuditLogRepository::class);
         $repo->expects($this->once())->method('purgeOlderThanDays')->with(120)->willReturn(3);
 
-        $settings = $this->createMock(SettingGateway::class);
+        $settings = $this->createMock(SettingsSystemAuditGateway::class);
         $settings->method('getSystemAuditRetentionDays')->willReturn(120);
 
-        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings);
+        $service = new SystemAuditService($repo, new SystemAuditRedactionService(), $settings, new SessionStore());
 
         $this->assertSame(3, $service->purgeExpired());
     }
diff --git a/tests/Service/Auth/AuthSessionTenantContextServiceTest.php b/tests/Service/Auth/AuthSessionTenantContextServiceTest.php
new file mode 100644
index 0000000..31de054
--- /dev/null
+++ b/tests/Service/Auth/AuthSessionTenantContextServiceTest.php
@@ -0,0 +1,76 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Auth;
+
+use MintyPHP\Http\SessionStore;
+use MintyPHP\Service\Auth\AuthSavedFilterGateway;
+use MintyPHP\Service\Auth\AuthSessionTenantContextService;
+use MintyPHP\Service\User\UserTenantContextService;
+use PHPUnit\Framework\TestCase;
+
+class AuthSessionTenantContextServiceTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        $_SESSION = [];
+    }
+
+    public function testHydrateMarksNoActiveTenantWhenUserHasNoTenants(): void
+    {
+        $_SESSION['current_tenant'] = ['id' => 9];
+
+        $userTenantContextService = $this->createMock(UserTenantContextService::class);
+        $userTenantContextService->method('getAvailableTenants')->willReturn([]);
+        $userTenantContextService->method('getAvailableDepartmentsByTenant')->willReturn([]);
+        $userTenantContextService->expects($this->never())->method('getCurrentTenant');
+
+        $savedFilterGateway = $this->createMock(AuthSavedFilterGateway::class);
+        $savedFilterGateway->method('listAddressBookFilters')->willReturn([]);
+
+        $service = new AuthSessionTenantContextService(
+            $userTenantContextService,
+            $savedFilterGateway,
+            new SessionStore()
+        );
+
+        $service->hydrateForUser(5);
+
+        $this->assertSame([], $_SESSION['available_tenants']);
+        $this->assertSame([], $_SESSION['available_departments_by_tenant']);
+        $this->assertSame([], $_SESSION['address_book_saved_filters']);
+        $this->assertTrue((bool) $_SESSION['no_active_tenant']);
+        $this->assertArrayNotHasKey('current_tenant', $_SESSION);
+    }
+
+    public function testHydrateUsesFirstAvailableTenantAsFallback(): void
+    {
+        $availableTenants = [
+            ['id' => 7, 'uuid' => 'tenant-7'],
+            ['id' => 8, 'uuid' => 'tenant-8'],
+        ];
+        $availableDepartments = ['7' => [['id' => 11]]];
+        $savedFilters = [['name' => 'Favorites']];
+
+        $userTenantContextService = $this->createMock(UserTenantContextService::class);
+        $userTenantContextService->method('getAvailableTenants')->willReturn($availableTenants);
+        $userTenantContextService->method('getAvailableDepartmentsByTenant')->willReturn($availableDepartments);
+        $userTenantContextService->method('getCurrentTenant')->willReturn(null);
+
+        $savedFilterGateway = $this->createMock(AuthSavedFilterGateway::class);
+        $savedFilterGateway->method('listAddressBookFilters')->willReturn($savedFilters);
+
+        $service = new AuthSessionTenantContextService(
+            $userTenantContextService,
+            $savedFilterGateway,
+            new SessionStore()
+        );
+
+        $service->hydrateForUser(5);
+
+        $this->assertSame($availableTenants, $_SESSION['available_tenants']);
+        $this->assertSame($availableDepartments, $_SESSION['available_departments_by_tenant']);
+        $this->assertSame($savedFilters, $_SESSION['address_book_saved_filters']);
+        $this->assertFalse((bool) $_SESSION['no_active_tenant']);
+        $this->assertSame(7, (int) ($_SESSION['current_tenant']['id'] ?? 0));
+    }
+}
diff --git a/tests/Service/Auth/MicrosoftOidcServiceTest.php b/tests/Service/Auth/MicrosoftOidcServiceTest.php
new file mode 100644
index 0000000..cfbac6d
--- /dev/null
+++ b/tests/Service/Auth/MicrosoftOidcServiceTest.php
@@ -0,0 +1,567 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Auth;
+
+use MintyPHP\Service\Auth\AuthTenantGateway;
+use MintyPHP\Service\Auth\MicrosoftOidcService;
+use MintyPHP\Service\Auth\MicrosoftOidcStateStoreService;
+use MintyPHP\Service\Auth\OidcHttpGateway;
+use MintyPHP\Service\Auth\TenantSsoService;
+use PHPUnit\Framework\TestCase;
+
+class MicrosoftOidcServiceTest extends TestCase
+{
+    public function testStartAuthorizationReturnsTenantNotFoundForInvalidTenant(): void
+    {
+        $service = $this->newService();
+
+        $result = $service->startAuthorization(['id' => 0], ['authority' => 'https://login.microsoftonline.com/common/v2.0']);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('tenant_not_found', $result['error']);
+    }
+
+    public function testStartAuthorizationReturnsDiscoveryFailedWhenMetadataLookupFails(): void
+    {
+        $oidcGateway = $this->createMock(OidcHttpGateway::class);
+        $oidcGateway->expects($this->once())
+            ->method('call')
+            ->willReturn(['status' => 500, 'data' => '']);
+
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->expects($this->never())->method('prune');
+        $stateStore->expects($this->never())->method('store');
+
+        $service = $this->newService(null, null, $oidcGateway, $stateStore);
+        $result = $service->startAuthorization(
+            ['id' => 7],
+            ['authority' => 'https://login.microsoftonline.com/common/v2.0']
+        );
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('oidc_discovery_failed', $result['error']);
+    }
+
+    public function testStartAuthorizationReturnsAuthorizeEndpointMissingWhenMetadataIsIncomplete(): void
+    {
+        $oidcGateway = $this->createMock(OidcHttpGateway::class);
+        $oidcGateway->method('call')->willReturn([
+            'status' => 200,
+            'data' => json_encode(['issuer' => 'https://issuer.example']) ?: '{}',
+        ]);
+
+        $storedState = '';
+        $storedPayload = [];
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->expects($this->once())->method('prune');
+        $stateStore->expects($this->once())
+            ->method('store')
+            ->willReturnCallback(function (string $state, array $payload) use (&$storedState, &$storedPayload): void {
+                $storedState = $state;
+                $storedPayload = $payload;
+            });
+
+        $service = $this->newService(null, null, $oidcGateway, $stateStore);
+        $result = $service->startAuthorization(
+            ['id' => 7],
+            ['authority' => 'https://login.microsoftonline.com/common/v2.0', 'client_id' => 'client-id']
+        );
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('authorize_endpoint_missing', $result['error']);
+        $this->assertNotSame('', $storedState);
+        $this->assertSame(7, (int) ($storedPayload['tenant_id'] ?? 0));
+    }
+
+    public function testStartAuthorizationBuildsPkceAuthorizationUrlAndStoresState(): void
+    {
+        $tenantSsoService = $this->createMock(TenantSsoService::class);
+        $tenantSsoService->method('normalizeProfileSyncFields')->willReturn(['avatar']);
+        $tenantSsoService->method('profileSyncFieldsRequireGraph')->willReturn(true);
+
+        $oidcGateway = $this->createMock(OidcHttpGateway::class);
+        $oidcGateway->expects($this->once())
+            ->method('call')
+            ->willReturn([
+                'status' => 200,
+                'data' => json_encode([
+                    'authorization_endpoint' => 'https://login.microsoftonline.com/tenant/oauth2/v2.0/authorize',
+                ]) ?: '{}',
+            ]);
+
+        $storedState = '';
+        $storedPayload = [];
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->expects($this->once())->method('prune');
+        $stateStore->expects($this->once())
+            ->method('store')
+            ->willReturnCallback(function (string $state, array $payload) use (&$storedState, &$storedPayload): void {
+                $storedState = $state;
+                $storedPayload = $payload;
+            });
+
+        $service = $this->newService($tenantSsoService, null, $oidcGateway, $stateStore);
+        $result = $service->startAuthorization(
+            ['id' => 9],
+            [
+                'authority' => 'https://login.microsoftonline.com/tenant/v2.0',
+                'client_id' => 'client-id',
+                'sync_profile_on_login' => 1,
+                'sync_profile_fields' => ['avatar'],
+            ]
+        );
+
+        $this->assertTrue($result['ok']);
+        $this->assertNotSame('', $storedState);
+        $this->assertSame(9, (int) ($storedPayload['tenant_id'] ?? 0));
+        $this->assertNotSame('', (string) ($storedPayload['redirect_uri'] ?? ''));
+
+        $query = $this->queryFromUrl((string) ($result['url'] ?? ''));
+        $this->assertSame('client-id', (string) ($query['client_id'] ?? ''));
+        $this->assertSame('code', (string) ($query['response_type'] ?? ''));
+        $this->assertSame('query', (string) ($query['response_mode'] ?? ''));
+        $this->assertSame('S256', (string) ($query['code_challenge_method'] ?? ''));
+        $this->assertSame($storedState, (string) ($query['state'] ?? ''));
+        $this->assertSame((string) ($storedPayload['nonce'] ?? ''), (string) ($query['nonce'] ?? ''));
+        $this->assertSame((string) ($storedPayload['redirect_uri'] ?? ''), (string) ($query['redirect_uri'] ?? ''));
+        $this->assertStringContainsString('openid', (string) ($query['scope'] ?? ''));
+        $this->assertStringContainsString('User.Read', (string) ($query['scope'] ?? ''));
+    }
+
+    public function testHandleCallbackReturnsCallbackInvalidWhenInputIsEmpty(): void
+    {
+        $service = $this->newService();
+
+        $result = $service->handleCallback(' ', '');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('callback_invalid', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsStateErrorWhenStateCannotBeConsumed(): void
+    {
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->expects($this->once())
+            ->method('consume')
+            ->with('state-x')
+            ->willReturn(['ok' => false, 'error' => 'state_invalid']);
+
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->expects($this->never())->method('findById');
+
+        $service = $this->newService(null, $tenantGateway, null, $stateStore);
+        $result = $service->handleCallback('state-x', 'code-x');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('state_invalid', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsTenantNotFoundForInactiveTenant(): void
+    {
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->method('consume')->willReturn([
+            'ok' => true,
+            'entry' => [
+                'tenant_id' => 5,
+                'nonce' => 'nonce',
+                'code_verifier' => 'verifier',
+                'redirect_uri' => 'https://app.example/auth/microsoft/callback',
+            ],
+        ]);
+
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->expects($this->once())
+            ->method('findById')
+            ->with(5)
+            ->willReturn(['id' => 5, 'status' => 'inactive']);
+
+        $service = $this->newService(null, $tenantGateway, null, $stateStore);
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('tenant_not_found', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsConfigErrorFromTenantSsoService(): void
+    {
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->method('consume')->willReturn([
+            'ok' => true,
+            'entry' => [
+                'tenant_id' => 8,
+                'nonce' => 'nonce',
+                'code_verifier' => 'verifier',
+                'redirect_uri' => 'https://app.example/auth/microsoft/callback',
+            ],
+        ]);
+
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->expects($this->once())
+            ->method('findById')
+            ->with(8)
+            ->willReturn(['id' => 8, 'status' => 'active']);
+
+        $tenantSsoService = $this->createMock(TenantSsoService::class);
+        $tenantSsoService->method('getEffectiveMicrosoftProviderConfig')->willReturn([
+            'ok' => false,
+            'error' => 'sso_disabled',
+        ]);
+
+        $service = $this->newService($tenantSsoService, $tenantGateway, null, $stateStore);
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('sso_disabled', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsTokenEndpointMissingWhenDiscoveryMetadataIsIncomplete(): void
+    {
+        $service = $this->newServiceForTokenFlow([
+            'status' => 200,
+            'data' => json_encode(['issuer' => 'https://issuer.example']) ?: '{}',
+        ]);
+
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('token_endpoint_missing', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsTokenExchangeFailedWhenTokenCallIsNotSuccessful(): void
+    {
+        $service = $this->newServiceForTokenFlow(
+            [
+                'status' => 200,
+                'data' => json_encode([
+                    'token_endpoint' => 'https://login.microsoftonline.com/tenant/oauth2/v2.0/token',
+                    'issuer' => 'https://login.microsoftonline.com/{tenantid}/v2.0',
+                    'jwks_uri' => 'https://login.microsoftonline.com/tenant/discovery/v2.0/keys',
+                ]) ?: '{}',
+            ],
+            [
+                'status' => 401,
+                'data' => json_encode(['error' => 'invalid_grant']) ?: '{}',
+            ]
+        );
+
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('token_exchange_failed', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsTokenResponseInvalidWhenBodyIsNotJson(): void
+    {
+        $service = $this->newServiceForTokenFlow(
+            [
+                'status' => 200,
+                'data' => json_encode([
+                    'token_endpoint' => 'https://login.microsoftonline.com/tenant/oauth2/v2.0/token',
+                    'issuer' => 'https://login.microsoftonline.com/{tenantid}/v2.0',
+                    'jwks_uri' => 'https://login.microsoftonline.com/tenant/discovery/v2.0/keys',
+                ]) ?: '{}',
+            ],
+            [
+                'status' => 200,
+                'data' => 'not-json',
+            ]
+        );
+
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('token_response_invalid', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsIdTokenMissingWhenTokenPayloadHasNoIdToken(): void
+    {
+        $service = $this->newServiceForTokenFlow(
+            [
+                'status' => 200,
+                'data' => json_encode([
+                    'token_endpoint' => 'https://login.microsoftonline.com/tenant/oauth2/v2.0/token',
+                    'issuer' => 'https://login.microsoftonline.com/{tenantid}/v2.0',
+                    'jwks_uri' => 'https://login.microsoftonline.com/tenant/discovery/v2.0/keys',
+                ]) ?: '{}',
+            ],
+            [
+                'status' => 200,
+                'data' => json_encode(['access_token' => 'access']) ?: '{}',
+            ]
+        );
+
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('id_token_missing', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsValidationErrorWhenIdTokenIsMalformed(): void
+    {
+        $service = $this->newServiceForTokenFlow(
+            [
+                'status' => 200,
+                'data' => json_encode([
+                    'token_endpoint' => 'https://login.microsoftonline.com/tenant/oauth2/v2.0/token',
+                    'issuer' => 'https://login.microsoftonline.com/{tenantid}/v2.0',
+                    'jwks_uri' => 'https://login.microsoftonline.com/tenant/discovery/v2.0/keys',
+                ]) ?: '{}',
+            ],
+            [
+                'status' => 200,
+                'data' => json_encode(['id_token' => 'not-a-jwt']) ?: '{}',
+            ]
+        );
+
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('id_token_format_invalid', $result['error']);
+    }
+
+    public function testHandleCallbackReturnsClaimsForValidToken(): void
+    {
+        [$idToken, $jwk] = $this->buildValidIdToken('client-id', 'tenant-id-123', 'nonce-123');
+
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->method('consume')->willReturn([
+            'ok' => true,
+            'entry' => [
+                'tenant_id' => 12,
+                'nonce' => 'nonce-123',
+                'code_verifier' => 'verifier-123',
+                'redirect_uri' => 'https://app.example/auth/microsoft/callback',
+                'locale' => 'de',
+            ],
+        ]);
+
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->expects($this->once())
+            ->method('findById')
+            ->with(12)
+            ->willReturn([
+                'id' => 12,
+                'status' => 'active',
+                'uuid' => 'tenant-uuid',
+            ]);
+
+        $tenantSsoService = $this->createMock(TenantSsoService::class);
+        $tenantSsoService->method('getEffectiveMicrosoftProviderConfig')->willReturn([
+            'ok' => true,
+            'config' => [
+                'authority' => 'https://login.microsoftonline.com/tenant-id-123/v2.0',
+                'client_id' => 'client-id',
+                'client_secret' => 'client-secret',
+                'tenant_id' => 'tenant-id-123',
+                'allowed_domains' => 'example.com',
+                'sync_profile_on_login' => 0,
+                'sync_profile_fields' => [],
+            ],
+        ]);
+        $tenantSsoService->method('isEmailDomainAllowed')->willReturn(true);
+        $tenantSsoService->method('normalizeProfileSyncFields')->willReturn([]);
+
+        $oidcGateway = $this->createMock(OidcHttpGateway::class);
+        $oidcGateway->expects($this->exactly(3))
+            ->method('call')
+            ->willReturnOnConsecutiveCalls(
+                [
+                    'status' => 200,
+                    'data' => json_encode([
+                        'token_endpoint' => 'https://login.microsoftonline.com/tenant-id-123/oauth2/v2.0/token',
+                        'issuer' => 'https://login.microsoftonline.com/{tenantid}/v2.0',
+                        'jwks_uri' => 'https://login.microsoftonline.com/tenant-id-123/discovery/v2.0/keys',
+                    ]) ?: '{}',
+                ],
+                [
+                    'status' => 200,
+                    'data' => json_encode([
+                        'id_token' => $idToken,
+                        'access_token' => '',
+                    ]) ?: '{}',
+                ],
+                [
+                    'status' => 200,
+                    'data' => json_encode(['keys' => [$jwk]]) ?: '{}',
+                ],
+            );
+
+        $service = $this->newService($tenantSsoService, $tenantGateway, $oidcGateway, $stateStore);
+        $result = $service->handleCallback('state-ok', 'code-ok');
+
+        $this->assertTrue($result['ok']);
+        $this->assertSame('de', (string) ($result['locale'] ?? ''));
+        $this->assertSame('user@example.com', (string) (($result['claims'] ?? [])['email'] ?? ''));
+        $this->assertSame('oid-123', (string) (($result['claims'] ?? [])['oid'] ?? ''));
+        $this->assertSame('sub-123', (string) (($result['claims'] ?? [])['subject'] ?? ''));
+        $this->assertSame('tenant-id-123', (string) (($result['claims'] ?? [])['tid'] ?? ''));
+    }
+
+    private function newServiceForTokenFlow(array $discoveryResponse, ?array $tokenResponse = null): MicrosoftOidcService
+    {
+        $stateStore = $this->createMock(MicrosoftOidcStateStoreService::class);
+        $stateStore->method('consume')->willReturn([
+            'ok' => true,
+            'entry' => [
+                'tenant_id' => 8,
+                'nonce' => 'nonce-1',
+                'code_verifier' => 'verifier-1',
+                'redirect_uri' => 'https://app.example/auth/microsoft/callback',
+                'locale' => 'de',
+            ],
+        ]);
+
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn([
+            'id' => 8,
+            'status' => 'active',
+        ]);
+
+        $tenantSsoService = $this->createMock(TenantSsoService::class);
+        $tenantSsoService->method('getEffectiveMicrosoftProviderConfig')->willReturn([
+            'ok' => true,
+            'config' => [
+                'authority' => 'https://login.microsoftonline.com/tenant/v2.0',
+                'client_id' => 'client-id',
+                'client_secret' => 'client-secret',
+                'tenant_id' => 'tenant-id-123',
+                'allowed_domains' => 'example.com',
+                'sync_profile_on_login' => 0,
+                'sync_profile_fields' => [],
+            ],
+        ]);
+        $tenantSsoService->method('normalizeProfileSyncFields')->willReturn([]);
+
+        $oidcGateway = $this->createMock(OidcHttpGateway::class);
+        if ($tokenResponse === null) {
+            $oidcGateway->method('call')->willReturn($discoveryResponse);
+        } else {
+            $oidcGateway->method('call')->willReturnOnConsecutiveCalls($discoveryResponse, $tokenResponse);
+        }
+
+        return $this->newService($tenantSsoService, $tenantGateway, $oidcGateway, $stateStore);
+    }
+
+    private function newService(
+        ?TenantSsoService $tenantSsoService = null,
+        ?AuthTenantGateway $tenantGateway = null,
+        ?OidcHttpGateway $oidcGateway = null,
+        ?MicrosoftOidcStateStoreService $stateStore = null
+    ): MicrosoftOidcService {
+        if ($tenantSsoService === null) {
+            $tenantSsoService = $this->createMock(TenantSsoService::class);
+            $tenantSsoService->method('normalizeProfileSyncFields')->willReturn([]);
+            $tenantSsoService->method('profileSyncFieldsRequireGraph')->willReturn(false);
+            $tenantSsoService->method('defaultProfileSyncFields')->willReturn(['first_name', 'last_name']);
+            $tenantSsoService->method('isEmailDomainAllowed')->willReturn(true);
+            $tenantSsoService->method('getEffectiveMicrosoftProviderConfig')->willReturn([
+                'ok' => true,
+                'config' => [
+                    'authority' => 'https://login.microsoftonline.com/common/v2.0',
+                    'client_id' => 'client-id',
+                    'client_secret' => 'client-secret',
+                    'tenant_id' => 'tenant-id-123',
+                    'allowed_domains' => 'example.com',
+                    'sync_profile_on_login' => 0,
+                    'sync_profile_fields' => [],
+                ],
+            ]);
+        }
+
+        $tenantGateway = $tenantGateway ?? $this->createMock(AuthTenantGateway::class);
+        $oidcGateway = $oidcGateway ?? $this->createMock(OidcHttpGateway::class);
+        $stateStore = $stateStore ?? $this->createMock(MicrosoftOidcStateStoreService::class);
+
+        return new MicrosoftOidcService(
+            $tenantSsoService,
+            $tenantGateway,
+            $oidcGateway,
+            $stateStore
+        );
+    }
+
+    /**
+     * @return array{0:string,1:array<string,string>}
+     */
+    private function buildValidIdToken(string $clientId, string $tenantId, string $nonce): array
+    {
+        $key = openssl_pkey_new([
+            'private_key_type' => OPENSSL_KEYTYPE_RSA,
+            'private_key_bits' => 2048,
+        ]);
+        if ($key === false) {
+            $this->fail('Unable to generate RSA key for OIDC token test');
+        }
+
+        $details = openssl_pkey_get_details($key);
+        if (!is_array($details) || !is_array($details['rsa'] ?? null)) {
+            $this->fail('Unable to read RSA key details');
+        }
+
+        $header = ['alg' => 'RS256', 'kid' => 'kid-123', 'typ' => 'JWT'];
+        $claims = [
+            'aud' => $clientId,
+            'nonce' => $nonce,
+            'tid' => $tenantId,
+            'iss' => 'https://login.microsoftonline.com/' . $tenantId . '/v2.0',
+            'exp' => time() + 300,
+            'nbf' => time() - 10,
+            'oid' => 'oid-123',
+            'sub' => 'sub-123',
+            'email' => 'user@example.com',
+            'name' => 'Example User',
+        ];
+
+        $headerJson = json_encode($header);
+        $claimsJson = json_encode($claims);
+        if (!is_string($headerJson) || !is_string($claimsJson)) {
+            $this->fail('Unable to encode token payload');
+        }
+
+        $encodedHeader = self::base64UrlEncode($headerJson);
+        $encodedClaims = self::base64UrlEncode($claimsJson);
+        $signingInput = $encodedHeader . '.' . $encodedClaims;
+
+        $signature = '';
+        $signed = openssl_sign($signingInput, $signature, $key, OPENSSL_ALGO_SHA256);
+        if (!$signed) {
+            $this->fail('Unable to sign token payload');
+        }
+
+        $rsa = $details['rsa'];
+        $modulus = is_string($rsa['n'] ?? null) ? $rsa['n'] : '';
+        $exponent = is_string($rsa['e'] ?? null) ? $rsa['e'] : '';
+        if ($modulus === '' || $exponent === '') {
+            $this->fail('Missing RSA modulus/exponent');
+        }
+
+        return [
+            $signingInput . '.' . self::base64UrlEncode($signature),
+            [
+                'kid' => 'kid-123',
+                'n' => self::base64UrlEncode($modulus),
+                'e' => self::base64UrlEncode($exponent),
+            ],
+        ];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function queryFromUrl(string $url): array
+    {
+        $parts = parse_url($url);
+        if (!is_array($parts)) {
+            return [];
+        }
+
+        $query = [];
+        parse_str((string) ($parts['query'] ?? ''), $query);
+        return array_map(static fn ($value): string => (string) $value, $query);
+    }
+
+    private static function base64UrlEncode(string $value): string
+    {
+        return rtrim(strtr(base64_encode($value), '+/', '-_'), '=');
+    }
+}
diff --git a/tests/Service/Auth/MicrosoftOidcStateStoreServiceTest.php b/tests/Service/Auth/MicrosoftOidcStateStoreServiceTest.php
index 85684af..ac363f8 100644
--- a/tests/Service/Auth/MicrosoftOidcStateStoreServiceTest.php
+++ b/tests/Service/Auth/MicrosoftOidcStateStoreServiceTest.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Tests\Service\Auth;
 
+use MintyPHP\Http\SessionStore;
 use MintyPHP\Service\Auth\MicrosoftOidcStateStoreService;
 use PHPUnit\Framework\TestCase;
 
@@ -24,7 +25,7 @@ class MicrosoftOidcStateStoreServiceTest extends TestCase
 
     public function testStoreAndConsumeIsSingleUse(): void
     {
-        $store = new MicrosoftOidcStateStoreService(600, 50);
+        $store = new MicrosoftOidcStateStoreService(new SessionStore(), 600, 50);
         $store->store('state-a', ['tenant_id' => 5, 'nonce' => 'n1']);
 
         $first = $store->consume('state-a');
@@ -38,7 +39,7 @@ class MicrosoftOidcStateStoreServiceTest extends TestCase
 
     public function testConsumeReturnsExpiredForOldState(): void
     {
-        $store = new MicrosoftOidcStateStoreService(1, 50);
+        $store = new MicrosoftOidcStateStoreService(new SessionStore(), 1, 50);
         $store->store('state-old', [
             'tenant_id' => 9,
             'created_at' => time() - 120,
@@ -51,7 +52,7 @@ class MicrosoftOidcStateStoreServiceTest extends TestCase
 
     public function testStoreRespectsMaxEntriesAndPrunesOldStates(): void
     {
-        $store = new MicrosoftOidcStateStoreService(600, 2);
+        $store = new MicrosoftOidcStateStoreService(new SessionStore(), 600, 2);
 
         $store->store('state-1', ['created_at' => time() - 3]);
         $store->store('state-2', ['created_at' => time() - 2]);
diff --git a/tests/Service/Auth/TenantSsoServiceTest.php b/tests/Service/Auth/TenantSsoServiceTest.php
new file mode 100644
index 0000000..5d98083
--- /dev/null
+++ b/tests/Service/Auth/TenantSsoServiceTest.php
@@ -0,0 +1,309 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Auth;
+
+use MintyPHP\Repository\Tenant\TenantMicrosoftAuthRepositoryInterface;
+use MintyPHP\Service\Auth\AuthCryptoGateway;
+use MintyPHP\Service\Auth\AuthSettingsGateway;
+use MintyPHP\Service\Auth\AuthTenantGateway;
+use MintyPHP\Service\Auth\TenantSsoService;
+use PHPUnit\Framework\TestCase;
+
+class TenantSsoServiceTest extends TestCase
+{
+    public function testGetEffectiveMicrosoftProviderConfigReturnsSsoDisabledWhenTenantAuthDisabled(): void
+    {
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn(['enabled' => 0]);
+
+        $service = $this->newService($repository);
+        $result = $service->getEffectiveMicrosoftProviderConfig(['id' => 5]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('sso_disabled', $result['error']);
+    }
+
+    public function testGetEffectiveMicrosoftProviderConfigRejectsInvalidTenantId(): void
+    {
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 1,
+            'entra_tenant_id' => 'invalid',
+            'use_shared_app' => 1,
+        ]);
+
+        $service = $this->newService($repository);
+        $result = $service->getEffectiveMicrosoftProviderConfig(['id' => 5]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('tenant_id_invalid', $result['error']);
+    }
+
+    public function testGetEffectiveMicrosoftProviderConfigRequiresSharedCredentials(): void
+    {
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 1,
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'use_shared_app' => 1,
+        ]);
+
+        $settingsGateway = $this->createMock(AuthSettingsGateway::class);
+        $settingsGateway->method('getMicrosoftSharedClientId')->willReturn('');
+        $settingsGateway->method('getMicrosoftSharedClientSecret')->willReturn('');
+
+        $service = $this->newService($repository, null, $settingsGateway);
+        $result = $service->getEffectiveMicrosoftProviderConfig(['id' => 5]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('shared_credentials_missing', $result['error']);
+    }
+
+    public function testGetEffectiveMicrosoftProviderConfigRequiresOverrideClientId(): void
+    {
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 1,
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'use_shared_app' => 0,
+            'client_id_override' => '',
+            'client_secret_override_enc' => 'enc',
+        ]);
+
+        $service = $this->newService($repository);
+        $result = $service->getEffectiveMicrosoftProviderConfig(['id' => 5]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('client_id_override_required', $result['error']);
+    }
+
+    public function testGetEffectiveMicrosoftProviderConfigRejectsInvalidOverrideSecret(): void
+    {
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 1,
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'use_shared_app' => 0,
+            'client_id_override' => 'client-id',
+            'client_secret_override_enc' => 'enc',
+        ]);
+
+        $cryptoGateway = $this->createMock(AuthCryptoGateway::class);
+        $cryptoGateway->method('decryptString')->willThrowException(new \RuntimeException('invalid secret'));
+
+        $service = $this->newService($repository, null, null, $cryptoGateway);
+        $result = $service->getEffectiveMicrosoftProviderConfig(['id' => 5]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('secret_invalid', $result['error']);
+    }
+
+    public function testGetEffectiveMicrosoftProviderConfigReturnsConfigForOverrideCredentials(): void
+    {
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 1,
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'allowed_domains' => 'example.com',
+            'enforce_microsoft_login' => 1,
+            'sync_profile_on_login' => 1,
+            'sync_profile_fields' => 'first_name,avatar',
+            'use_shared_app' => 0,
+            'client_id_override' => 'client-id',
+            'client_secret_override_enc' => 'enc',
+        ]);
+
+        $settingsGateway = $this->createMock(AuthSettingsGateway::class);
+        $settingsGateway->method('getMicrosoftAuthority')->willReturn('https://login.microsoftonline.com/common/v2.0');
+
+        $cryptoGateway = $this->createMock(AuthCryptoGateway::class);
+        $cryptoGateway->method('decryptString')->willReturn('secret-value');
+
+        $service = $this->newService($repository, null, $settingsGateway, $cryptoGateway);
+        $result = $service->getEffectiveMicrosoftProviderConfig(['id' => 5]);
+
+        $this->assertTrue($result['ok']);
+        $this->assertSame('client-id', $result['config']['client_id']);
+        $this->assertSame('secret-value', $result['config']['client_secret']);
+        $this->assertTrue((bool) $result['config']['sync_profile_needs_graph']);
+        $this->assertSame('https://login.microsoftonline.com/common/v2.0', $result['config']['authority']);
+        $this->assertFalse((bool) $result['config']['use_shared_app']);
+    }
+
+    public function testResolveTenantLoginMethodsReturnsTenantNotFoundForInactiveTenant(): void
+    {
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn(['id' => 5, 'status' => 'inactive']);
+
+        $service = $this->newService(null, $tenantGateway);
+        $result = $service->resolveTenantLoginMethods(5);
+
+        $this->assertFalse($result['local']);
+        $this->assertFalse($result['microsoft']);
+        $this->assertSame('tenant_not_found', $result['microsoft_reason']);
+    }
+
+    public function testResolveTenantLoginMethodsReturnsLocalOnlyWhenSsoDisabled(): void
+    {
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn(['id' => 5, 'status' => 'active']);
+
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn(['enabled' => 0]);
+
+        $service = $this->newService($repository, $tenantGateway);
+        $result = $service->resolveTenantLoginMethods(5);
+
+        $this->assertTrue($result['local']);
+        $this->assertFalse($result['microsoft']);
+        $this->assertSame('sso_disabled', $result['microsoft_reason']);
+    }
+
+    public function testResolveTenantLoginMethodsReturnsMicrosoftOnlyWhenEnforcedAndConfigured(): void
+    {
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn(['id' => 5, 'status' => 'active']);
+
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 1,
+            'enforce_microsoft_login' => 1,
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'use_shared_app' => 1,
+        ]);
+
+        $settingsGateway = $this->createMock(AuthSettingsGateway::class);
+        $settingsGateway->method('getMicrosoftSharedClientId')->willReturn('shared-client');
+        $settingsGateway->method('getMicrosoftSharedClientSecret')->willReturn('shared-secret');
+        $settingsGateway->method('getMicrosoftAuthority')->willReturn('https://login.microsoftonline.com/common/v2.0');
+
+        $service = $this->newService($repository, $tenantGateway, $settingsGateway);
+        $result = $service->resolveTenantLoginMethods(5);
+
+        $this->assertFalse($result['local']);
+        $this->assertTrue($result['microsoft']);
+        $this->assertSame('', $result['microsoft_reason']);
+    }
+
+    public function testSaveTenantMicrosoftAuthReturnsErrorWhenTenantDoesNotExist(): void
+    {
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn(null);
+
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->expects($this->never())->method('upsertByTenantId');
+
+        $service = $this->newService($repository, $tenantGateway);
+        $result = $service->saveTenantMicrosoftAuth(5, ['microsoft_enabled' => '1']);
+
+        $this->assertFalse($result['ok']);
+        $this->assertNotEmpty($result['errors']);
+    }
+
+    public function testSaveTenantMicrosoftAuthValidatesCryptoWhenOverrideSecretIsProvided(): void
+    {
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn(['id' => 5, 'status' => 'active']);
+
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 0,
+            'use_shared_app' => 0,
+            'client_secret_override_enc' => '',
+        ]);
+        $repository->expects($this->never())->method('upsertByTenantId');
+
+        $cryptoGateway = $this->createMock(AuthCryptoGateway::class);
+        $cryptoGateway->method('isConfigured')->willReturn(false);
+
+        $service = $this->newService($repository, $tenantGateway, null, $cryptoGateway);
+        $result = $service->saveTenantMicrosoftAuth(5, [
+            'microsoft_enabled' => '1',
+            'use_shared_app' => '',
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'client_id_override' => 'client-id',
+            'client_secret_override' => 'new-secret',
+        ]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertNotEmpty($result['errors']);
+    }
+
+    public function testSaveTenantMicrosoftAuthPersistsNormalizedSharedAppPayload(): void
+    {
+        $tenantGateway = $this->createMock(AuthTenantGateway::class);
+        $tenantGateway->method('findById')->willReturn(['id' => 5, 'status' => 'active']);
+
+        $repository = $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $repository->method('findByTenantId')->willReturn([
+            'enabled' => 0,
+            'use_shared_app' => 1,
+            'client_secret_override_enc' => '',
+        ]);
+        $repository->expects($this->once())
+            ->method('upsertByTenantId')
+            ->with(
+                5,
+                $this->callback(static function (array $data): bool {
+                    return $data['enabled'] === true
+                        && $data['enforce_microsoft_login'] === true
+                        && $data['sync_profile_on_login'] === true
+                        && $data['sync_profile_fields'] === 'first_name,last_name'
+                        && $data['entra_tenant_id'] === '11111111-1111-1111-1111-111111111111'
+                        && $data['allowed_domains'] === 'example.com,test.org'
+                        && $data['use_shared_app'] === true
+                        && $data['client_id_override'] === null
+                        && $data['client_secret_override_enc'] === null;
+                })
+            )
+            ->willReturn(true);
+
+        $settingsGateway = $this->createMock(AuthSettingsGateway::class);
+        $settingsGateway->method('getMicrosoftSharedClientId')->willReturn('shared-client');
+        $settingsGateway->method('getMicrosoftSharedClientSecret')->willReturn('shared-secret');
+
+        $service = $this->newService($repository, $tenantGateway, $settingsGateway);
+        $result = $service->saveTenantMicrosoftAuth(5, [
+            'microsoft_enabled' => '1',
+            'enforce_microsoft_login' => '1',
+            'sync_profile_on_login' => '1',
+            'sync_profile_fields' => [],
+            'entra_tenant_id' => '11111111-1111-1111-1111-111111111111',
+            'allowed_domains' => "example.com, invalid, test.org\nexample.com",
+            'use_shared_app' => '1',
+            'client_id_override' => 'ignored',
+            'client_secret_override' => '',
+        ]);
+
+        $this->assertTrue($result['ok']);
+    }
+
+    private function newService(
+        ?TenantMicrosoftAuthRepositoryInterface $repository = null,
+        ?AuthTenantGateway $tenantGateway = null,
+        ?AuthSettingsGateway $settingsGateway = null,
+        ?AuthCryptoGateway $cryptoGateway = null
+    ): TenantSsoService {
+        $repository = $repository ?? $this->createMock(TenantMicrosoftAuthRepositoryInterface::class);
+        $tenantGateway = $tenantGateway ?? $this->createMock(AuthTenantGateway::class);
+        if ($settingsGateway === null) {
+            $settingsGateway = $this->createMock(AuthSettingsGateway::class);
+            $settingsGateway->method('getMicrosoftSharedClientId')->willReturn('');
+            $settingsGateway->method('getMicrosoftSharedClientSecret')->willReturn('');
+            $settingsGateway->method('getMicrosoftAuthority')->willReturn('');
+        }
+        if ($cryptoGateway === null) {
+            $cryptoGateway = $this->createMock(AuthCryptoGateway::class);
+            $cryptoGateway->method('isConfigured')->willReturn(true);
+            $cryptoGateway->method('decryptString')->willReturn('decrypted-secret');
+            $cryptoGateway->method('encryptString')->willReturn('encrypted-secret');
+        }
+
+        return new TenantSsoService(
+            $tenantGateway,
+            $repository,
+            $settingsGateway,
+            $cryptoGateway
+        );
+    }
+}
diff --git a/tests/Service/Import/ImportServiceTest.php b/tests/Service/Import/ImportServiceTest.php
index a73e679..19a331f 100644
--- a/tests/Service/Import/ImportServiceTest.php
+++ b/tests/Service/Import/ImportServiceTest.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Tests\Service\Import;
 
+use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Service\Access\PermissionGateway;
 use MintyPHP\Service\Audit\ImportAuditService;
 use MintyPHP\Service\Import\CsvReaderService;
@@ -9,7 +10,7 @@ use MintyPHP\Service\Import\ImportService;
 use MintyPHP\Service\Import\ImportStateStoreService;
 use MintyPHP\Service\Import\ImportTempFileService;
 use MintyPHP\Service\Import\Profile\ImportProfileInterface;
-use MintyPHP\Service\Settings\SettingGateway;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
 use MintyPHP\Service\User\UserScopeGateway;
 use PHPUnit\Framework\TestCase;
 
@@ -120,10 +121,12 @@ class ImportServiceTest extends TestCase
         $stateStore = $stateStore ?? $this->createMock(ImportStateStoreService::class);
         $permissionGateway = $this->createMock(PermissionGateway::class);
         $permissionGateway->method('userHas')->willReturn(false);
-        $settingGateway = $this->createMock(SettingGateway::class);
+        $settingsDefaultsGateway = $this->createMock(SettingsDefaultsGateway::class);
         $userScopeGateway = $this->createMock(UserScopeGateway::class);
         $userScopeGateway->method('hasGlobalAccess')->willReturn(false);
         $userScopeGateway->method('getUserTenantIds')->willReturn([]);
+        $sessionStore = $this->createMock(SessionStoreInterface::class);
+        $sessionStore->method('get')->willReturn([]);
 
         return new ImportService(
             $csvReader,
@@ -132,8 +135,9 @@ class ImportServiceTest extends TestCase
             $stateStore,
             [$profile->key() => $profile],
             $permissionGateway,
-            $settingGateway,
-            $userScopeGateway
+            $settingsDefaultsGateway,
+            $userScopeGateway,
+            $sessionStore
         );
     }
 }
diff --git a/tests/Service/Import/ImportStateStoreServiceTest.php b/tests/Service/Import/ImportStateStoreServiceTest.php
index 1b1fc9f..4841fcf 100644
--- a/tests/Service/Import/ImportStateStoreServiceTest.php
+++ b/tests/Service/Import/ImportStateStoreServiceTest.php
@@ -2,6 +2,7 @@
 
 namespace MintyPHP\Tests\Service\Import;
 
+use MintyPHP\Http\SessionStore;
 use MintyPHP\Service\Import\ImportStateStoreService;
 use MintyPHP\Service\Import\ImportTempFileService;
 use PHPUnit\Framework\TestCase;
@@ -16,7 +17,7 @@ class ImportStateStoreServiceTest extends TestCase
     public function testSetGetAndClearState(): void
     {
         $tempFileService = $this->createMock(ImportTempFileService::class);
-        $stateStore = new ImportStateStoreService($tempFileService);
+        $stateStore = new ImportStateStoreService($tempFileService, new SessionStore());
 
         $stateStore->setState('token_a', ['token' => 'token_a', 'created_at' => time(), 'path' => '/tmp/a.csv']);
         $loaded = $stateStore->getState('token_a');
@@ -34,7 +35,7 @@ class ImportStateStoreServiceTest extends TestCase
             ->method('delete')
             ->with('/tmp/expired.csv');
 
-        $stateStore = new ImportStateStoreService($tempFileService);
+        $stateStore = new ImportStateStoreService($tempFileService, new SessionStore());
         $stateStore->setState('token_b', [
             'token' => 'token_b',
             'created_at' => time() - 7201,
diff --git a/tests/Service/Settings/SettingServiceTest.php b/tests/Service/Settings/SettingServiceTest.php
deleted file mode 100644
index e2ceab3..0000000
--- a/tests/Service/Settings/SettingServiceTest.php
+++ /dev/null
@@ -1,144 +0,0 @@
-<?php
-
-namespace MintyPHP\Tests\Service\Settings;
-
-use MintyPHP\Repository\Access\RoleRepository;
-use MintyPHP\Repository\Org\DepartmentRepository;
-use MintyPHP\Repository\Settings\SettingRepository;
-use MintyPHP\Repository\Tenant\TenantRepository;
-use MintyPHP\Service\Settings\SettingService;
-use MintyPHP\Service\Settings\ThemeConfigService;
-use PHPUnit\Framework\TestCase;
-
-class SettingServiceTest extends TestCase
-{
-    public function testSetDefaultTenantIdRejectsUnknownTenant(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->expects($this->never())->method('set');
-
-        $tenantRepository = $this->createMock(TenantRepository::class);
-        $tenantRepository->expects($this->once())->method('find')->with(99)->willReturn(null);
-
-        $service = $this->newService($settingRepository, $tenantRepository);
-        $this->assertFalse($service->setDefaultTenantId(99));
-    }
-
-    public function testSetApiTokenDefaultTtlDaysRejectsAboveCurrentMax(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->method('getValue')->willReturnCallback(
-            static function (string $key): ?string {
-                if ($key === SettingService::API_TOKEN_MAX_TTL_DAYS_KEY) {
-                    return '30';
-                }
-                return null;
-            }
-        );
-        $settingRepository->expects($this->never())->method('set');
-
-        $service = $this->newService($settingRepository);
-        $this->assertFalse($service->setApiTokenDefaultTtlDays(31));
-    }
-
-    public function testSetApiTokenMaxTtlDaysUpdatesDefaultWhenNeeded(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->method('getValue')->willReturnCallback(
-            static function (string $key): ?string {
-                if ($key === SettingService::API_TOKEN_DEFAULT_TTL_DAYS_KEY) {
-                    return '365';
-                }
-                return null;
-            }
-        );
-
-        $calls = [];
-        $settingRepository->expects($this->exactly(2))
-            ->method('set')
-            ->willReturnCallback(
-                static function (string $key, ?string $value, ?string $description) use (&$calls): bool {
-                    $calls[] = [$key, $value, $description];
-                    return true;
-                }
-            );
-
-        $service = $this->newService($settingRepository);
-        $this->assertTrue($service->setApiTokenMaxTtlDays(120));
-        $this->assertSame(
-            [
-                [SettingService::API_TOKEN_DEFAULT_TTL_DAYS_KEY, '120', 'setting.api_token_default_ttl_days'],
-                [SettingService::API_TOKEN_MAX_TTL_DAYS_KEY, '120', 'setting.api_token_max_ttl_days'],
-            ],
-            $calls
-        );
-    }
-
-    public function testSetUserInactivityDeleteDaysRequiresDeactivatePolicy(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->method('getValue')->willReturnCallback(
-            static function (string $key): ?string {
-                if ($key === SettingService::USER_INACTIVITY_DEACTIVATE_DAYS_KEY) {
-                    return '0';
-                }
-                return null;
-            }
-        );
-        $settingRepository->expects($this->never())->method('set');
-
-        $service = $this->newService($settingRepository);
-        $this->assertFalse($service->setUserInactivityDeleteDays(30));
-    }
-
-    public function testSetApiCorsAllowedOriginsRejectsInvalidOrigins(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->expects($this->never())->method('set');
-
-        $service = $this->newService($settingRepository);
-        $this->assertFalse($service->setApiCorsAllowedOrigins("https://ok.example\njavascript:alert(1)"));
-    }
-
-    public function testSetMicrosoftAuthorityRequiresHttps(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->expects($this->never())->method('set');
-
-        $service = $this->newService($settingRepository);
-        $this->assertFalse($service->setMicrosoftAuthority('http://login.microsoftonline.com/common/v2.0'));
-    }
-
-    public function testSetAppPrimaryColorNormalizesHexWithoutHash(): void
-    {
-        $settingRepository = $this->createMock(SettingRepository::class);
-        $settingRepository->expects($this->once())
-            ->method('set')
-            ->with(SettingService::APP_PRIMARY_COLOR_KEY, '#abc', 'setting.app_primary_color')
-            ->willReturn(true);
-
-        $service = $this->newService($settingRepository);
-        $this->assertTrue($service->setAppPrimaryColor('abc'));
-    }
-
-    private function newService(
-        SettingRepository $settingRepository,
-        ?TenantRepository $tenantRepository = null,
-        ?RoleRepository $roleRepository = null,
-        ?DepartmentRepository $departmentRepository = null
-    ): SettingService {
-        $tenantRepository = $tenantRepository ?? $this->createMock(TenantRepository::class);
-        $roleRepository = $roleRepository ?? $this->createMock(RoleRepository::class);
-        $departmentRepository = $departmentRepository ?? $this->createMock(DepartmentRepository::class);
-        $themeConfigService = $this->createMock(ThemeConfigService::class);
-        $themeConfigService->method('all')->willReturn(['light' => 'Light', 'dark' => 'Dark']);
-
-        return new SettingService(
-            $settingRepository,
-            $tenantRepository,
-            $roleRepository,
-            $departmentRepository,
-            $themeConfigService
-        );
-    }
-}
diff --git a/tests/Service/Settings/SettingsApiPolicyGatewayTest.php b/tests/Service/Settings/SettingsApiPolicyGatewayTest.php
new file mode 100644
index 0000000..9818b0c
--- /dev/null
+++ b/tests/Service/Settings/SettingsApiPolicyGatewayTest.php
@@ -0,0 +1,89 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsApiPolicyGateway;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsApiPolicyGatewayTest extends TestCase
+{
+    public function testSetApiTokenDefaultTtlDaysRejectsAboveCurrentMax(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturnCallback(static function (string $key): ?string {
+            if ($key === 'api_token_max_ttl_days') {
+                return '30';
+            }
+            return null;
+        });
+        $settings->expects($this->never())->method('set');
+
+        $gateway = new SettingsApiPolicyGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->setApiTokenDefaultTtlDays(31));
+    }
+
+    public function testSetApiTokenMaxTtlDaysUpdatesDefaultWhenNeeded(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturnCallback(static function (string $key): ?string {
+            if ($key === 'api_token_default_ttl_days') {
+                return '365';
+            }
+            return null;
+        });
+
+        $calls = [];
+        $settings->expects($this->exactly(2))
+            ->method('set')
+            ->willReturnCallback(static function (string $key, ?string $value, ?string $description) use (&$calls): bool {
+                $calls[] = [$key, $value, $description];
+                return true;
+            });
+
+        $gateway = new SettingsApiPolicyGateway(new SettingsMetadataGateway($settings));
+        $this->assertTrue($gateway->setApiTokenMaxTtlDays(120));
+        $this->assertSame(
+            [
+                ['api_token_default_ttl_days', '120', 'setting.api_token_default_ttl_days'],
+                ['api_token_max_ttl_days', '120', 'setting.api_token_max_ttl_days'],
+            ],
+            $calls
+        );
+    }
+
+    public function testSetApiCorsAllowedOriginsRejectsInvalidOrigins(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $gateway = new SettingsApiPolicyGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->setApiCorsAllowedOrigins("https://ok.example\njavascript:alert(1)"));
+    }
+
+    public function testCorsOriginsRoundtripNormalizesAndDeduplicates(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $stored = null;
+        $settings->expects($this->once())
+            ->method('set')
+            ->willReturnCallback(static function (string $key, ?string $value) use (&$stored): bool {
+                if ($key === 'api_cors_allowed_origins') {
+                    $stored = $value;
+                }
+                return true;
+            });
+        $settings->method('getValue')->willReturnCallback(static function (string $key) use (&$stored): ?string {
+            if ($key === 'api_cors_allowed_origins') {
+                return $stored;
+            }
+            return null;
+        });
+
+        $gateway = new SettingsApiPolicyGateway(new SettingsMetadataGateway($settings));
+        $this->assertTrue($gateway->setApiCorsAllowedOrigins("https://a.example,https://a.example/\nhttps://b.example:443"));
+        $this->assertSame(['https://a.example', 'https://b.example'], $gateway->getApiCorsAllowedOrigins());
+        $this->assertSame("https://a.example\nhttps://b.example", $gateway->getApiCorsAllowedOriginsText());
+    }
+}
diff --git a/tests/Service/Settings/SettingsAppGatewayTest.php b/tests/Service/Settings/SettingsAppGatewayTest.php
new file mode 100644
index 0000000..67c6465
--- /dev/null
+++ b/tests/Service/Settings/SettingsAppGatewayTest.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsAppGateway;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use MintyPHP\Service\Settings\ThemeConfigService;
+use PHPUnit\Framework\TestCase;
+
+class SettingsAppGatewayTest extends TestCase
+{
+    public function testSetAppLocaleStoresNullForEmptyValue(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->once())->method('set')->with('app_locale', null, 'setting.app_locale')->willReturn(true);
+
+        $gateway = $this->newGateway($settings);
+        $this->assertTrue($gateway->setAppLocale(' '));
+    }
+
+    public function testSetAppThemeStoresNullForUnknownTheme(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->once())->method('set')->with('app_theme', null, 'setting.app_theme')->willReturn(true);
+
+        $gateway = $this->newGateway($settings);
+        $this->assertTrue($gateway->setAppTheme('unknown'));
+    }
+
+    public function testBooleanFlagsUseExpectedDefaults(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturnMap([
+            ['app_theme_user', null],
+            ['app_registration', null],
+        ]);
+
+        $gateway = $this->newGateway($settings);
+        $this->assertTrue($gateway->isUserThemeAllowed());
+        $this->assertTrue($gateway->isRegistrationEnabled());
+    }
+
+    public function testSetAppPrimaryColorNormalizesHexWithoutHash(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->once())
+            ->method('set')
+            ->with('app_primary_color', '#abc', 'setting.app_primary_color')
+            ->willReturn(true);
+
+        $gateway = $this->newGateway($settings);
+        $this->assertTrue($gateway->setAppPrimaryColor('abc'));
+    }
+
+    public function testSetAppPrimaryColorRejectsInvalidValue(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $gateway = $this->newGateway($settings);
+        $this->assertFalse($gateway->setAppPrimaryColor('not-a-color'));
+    }
+
+    private function newGateway(SettingRepositoryInterface $settingRepository): SettingsAppGateway
+    {
+        $themeConfigService = $this->createMock(ThemeConfigService::class);
+        $themeConfigService->method('all')->willReturn(['light' => 'Light', 'dark' => 'Dark']);
+
+        return new SettingsAppGateway(new SettingsMetadataGateway($settingRepository), $themeConfigService);
+    }
+}
diff --git a/tests/Service/Settings/SettingsDefaultsGatewayTest.php b/tests/Service/Settings/SettingsDefaultsGatewayTest.php
new file mode 100644
index 0000000..87a33b5
--- /dev/null
+++ b/tests/Service/Settings/SettingsDefaultsGatewayTest.php
@@ -0,0 +1,101 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Access\RoleRepositoryInterface;
+use MintyPHP\Repository\Org\DepartmentRepositoryInterface;
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Repository\Tenant\TenantRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsDefaultsGateway;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsDefaultsGatewayTest extends TestCase
+{
+    public function testSetDefaultTenantIdRejectsUnknownTenant(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $tenantRepository = $this->createMock(TenantRepositoryInterface::class);
+        $tenantRepository->expects($this->once())->method('find')->with(99)->willReturn(null);
+
+        $gateway = $this->newGateway($settings, $tenantRepository);
+        $this->assertFalse($gateway->setDefaultTenantId(99));
+    }
+
+    public function testSetDefaultRoleIdRejectsUnknownRole(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $roleRepository = $this->createMock(RoleRepositoryInterface::class);
+        $roleRepository->expects($this->once())->method('find')->with(55)->willReturn(null);
+
+        $gateway = $this->newGateway($settings, null, $roleRepository);
+        $this->assertFalse($gateway->setDefaultRoleId(55));
+    }
+
+    public function testSetDefaultDepartmentIdRejectsUnknownDepartment(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $departmentRepository = $this->createMock(DepartmentRepositoryInterface::class);
+        $departmentRepository->expects($this->once())->method('find')->with(77)->willReturn(null);
+
+        $gateway = $this->newGateway($settings, null, null, $departmentRepository);
+        $this->assertFalse($gateway->setDefaultDepartmentId(77));
+    }
+
+    public function testSettersPersistValidIds(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->exactly(3))
+            ->method('set')
+            ->willReturn(true);
+
+        $tenantRepository = $this->createMock(TenantRepositoryInterface::class);
+        $tenantRepository->method('find')->willReturn(['id' => 5]);
+
+        $roleRepository = $this->createMock(RoleRepositoryInterface::class);
+        $roleRepository->method('find')->willReturn(['id' => 6]);
+
+        $departmentRepository = $this->createMock(DepartmentRepositoryInterface::class);
+        $departmentRepository->method('find')->willReturn(['id' => 7]);
+
+        $gateway = $this->newGateway($settings, $tenantRepository, $roleRepository, $departmentRepository);
+        $this->assertTrue($gateway->setDefaultTenantId(5));
+        $this->assertTrue($gateway->setDefaultRoleId(6));
+        $this->assertTrue($gateway->setDefaultDepartmentId(7));
+    }
+
+    public function testSettersAllowResetToNull(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->exactly(3))->method('set')->willReturn(true);
+
+        $gateway = $this->newGateway($settings);
+        $this->assertTrue($gateway->setDefaultTenantId(null));
+        $this->assertTrue($gateway->setDefaultRoleId(null));
+        $this->assertTrue($gateway->setDefaultDepartmentId(null));
+    }
+
+    private function newGateway(
+        SettingRepositoryInterface $settingRepository,
+        ?TenantRepositoryInterface $tenantRepository = null,
+        ?RoleRepositoryInterface $roleRepository = null,
+        ?DepartmentRepositoryInterface $departmentRepository = null
+    ): SettingsDefaultsGateway {
+        $tenantRepository = $tenantRepository ?? $this->createMock(TenantRepositoryInterface::class);
+        $roleRepository = $roleRepository ?? $this->createMock(RoleRepositoryInterface::class);
+        $departmentRepository = $departmentRepository ?? $this->createMock(DepartmentRepositoryInterface::class);
+
+        return new SettingsDefaultsGateway(
+            new SettingsMetadataGateway($settingRepository),
+            $tenantRepository,
+            $roleRepository,
+            $departmentRepository
+        );
+    }
+}
diff --git a/tests/Service/Settings/SettingsFrontendTelemetryGatewayTest.php b/tests/Service/Settings/SettingsFrontendTelemetryGatewayTest.php
new file mode 100644
index 0000000..85f931f
--- /dev/null
+++ b/tests/Service/Settings/SettingsFrontendTelemetryGatewayTest.php
@@ -0,0 +1,47 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsFrontendTelemetryGateway;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsFrontendTelemetryGatewayTest extends TestCase
+{
+    public function testDefaultsAreUsedWhenSettingsMissing(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturn(null);
+
+        $gateway = new SettingsFrontendTelemetryGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->isFrontendTelemetryEnabled());
+        $this->assertSame(0.2, $gateway->getFrontendTelemetrySampleRate());
+        $this->assertSame(['warn_once', 'ajax_error'], $gateway->getFrontendTelemetryAllowedEvents());
+    }
+
+    public function testSetSampleRateRejectsOutOfRangeValues(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $gateway = new SettingsFrontendTelemetryGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->setFrontendTelemetrySampleRate(1.5));
+    }
+
+    public function testSetAllowedEventsNormalizesValues(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->once())
+            ->method('set')
+            ->with(
+                'frontend_telemetry_allowed_events',
+                'ajax_error,warn_once',
+                'setting.frontend_telemetry_allowed_events'
+            )
+            ->willReturn(true);
+
+        $gateway = new SettingsFrontendTelemetryGateway(new SettingsMetadataGateway($settings));
+        $this->assertTrue($gateway->setFrontendTelemetryAllowedEvents(['frontend.warn_once', 'ajax_error', 'invalid']));
+    }
+}
diff --git a/tests/Service/Settings/SettingsMicrosoftGatewayTest.php b/tests/Service/Settings/SettingsMicrosoftGatewayTest.php
new file mode 100644
index 0000000..eaad597
--- /dev/null
+++ b/tests/Service/Settings/SettingsMicrosoftGatewayTest.php
@@ -0,0 +1,53 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsCryptoGatewayInterface;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use MintyPHP\Service\Settings\SettingsMicrosoftGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsMicrosoftGatewayTest extends TestCase
+{
+    public function testSetMicrosoftAuthorityRequiresHttps(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $crypto = $this->createMock(SettingsCryptoGatewayInterface::class);
+        $gateway = new SettingsMicrosoftGateway(new SettingsMetadataGateway($settings), $crypto);
+
+        $this->assertFalse($gateway->setMicrosoftAuthority('http://login.microsoftonline.com/common/v2.0'));
+    }
+
+    public function testGetMicrosoftSharedClientSecretReturnsNullWhenDecryptFails(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturn('encrypted');
+
+        $crypto = $this->createMock(SettingsCryptoGatewayInterface::class);
+        $crypto->method('decryptString')->willThrowException(new \RuntimeException('bad secret'));
+
+        $gateway = new SettingsMicrosoftGateway(new SettingsMetadataGateway($settings), $crypto);
+        $this->assertNull($gateway->getMicrosoftSharedClientSecret());
+    }
+
+    public function testSetMicrosoftSharedClientSecretEncryptsAndPersists(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->once())
+            ->method('set')
+            ->with('microsoft_shared_client_secret_enc', 'enc-value', 'setting.microsoft_shared_client_secret_enc')
+            ->willReturn(true);
+
+        $crypto = $this->createMock(SettingsCryptoGatewayInterface::class);
+        $crypto->expects($this->once())
+            ->method('encryptString')
+            ->with('secret-value')
+            ->willReturn('enc-value');
+
+        $gateway = new SettingsMicrosoftGateway(new SettingsMetadataGateway($settings), $crypto);
+        $this->assertTrue($gateway->setMicrosoftSharedClientSecret('secret-value'));
+    }
+}
diff --git a/tests/Service/Settings/SettingsSmtpGatewayTest.php b/tests/Service/Settings/SettingsSmtpGatewayTest.php
new file mode 100644
index 0000000..16b1eca
--- /dev/null
+++ b/tests/Service/Settings/SettingsSmtpGatewayTest.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use MintyPHP\Service\Settings\SettingsSmtpGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsSmtpGatewayTest extends TestCase
+{
+    public function testGetSmtpSecureReturnsNullForNone(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturnCallback(static function (string $key): ?string {
+            if ($key === 'smtp_secure') {
+                return 'none';
+            }
+            return null;
+        });
+
+        $gateway = new SettingsSmtpGateway(new SettingsMetadataGateway($settings));
+        $this->assertNull($gateway->getSmtpSecure());
+    }
+
+    public function testSetSmtpSecureRejectsInvalidValue(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $gateway = new SettingsSmtpGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->setSmtpSecure('starttls'));
+    }
+
+    public function testSetSmtpHostPersistsNullForEmptyString(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->once())
+            ->method('set')
+            ->with('smtp_host', null, 'setting.smtp_host')
+            ->willReturn(true);
+
+        $gateway = new SettingsSmtpGateway(new SettingsMetadataGateway($settings));
+        $this->assertTrue($gateway->setSmtpHost('  '));
+    }
+}
diff --git a/tests/Service/Settings/SettingsSystemAuditGatewayTest.php b/tests/Service/Settings/SettingsSystemAuditGatewayTest.php
new file mode 100644
index 0000000..8f2ed14
--- /dev/null
+++ b/tests/Service/Settings/SettingsSystemAuditGatewayTest.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use MintyPHP\Service\Settings\SettingsSystemAuditGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsSystemAuditGatewayTest extends TestCase
+{
+    public function testIsSystemAuditEnabledUsesFallbackWhenMissing(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturn(null);
+
+        $gateway = new SettingsSystemAuditGateway(new SettingsMetadataGateway($settings));
+        $this->assertTrue($gateway->isSystemAuditEnabled());
+    }
+
+    public function testRetentionFallsBackWhenOutOfRange(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturn('5');
+
+        $gateway = new SettingsSystemAuditGateway(new SettingsMetadataGateway($settings));
+        $this->assertSame(365, $gateway->getSystemAuditRetentionDays());
+    }
+
+    public function testSetSystemAuditRetentionRejectsOutOfRange(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->never())->method('set');
+
+        $gateway = new SettingsSystemAuditGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->setSystemAuditRetentionDays(10));
+    }
+}
diff --git a/tests/Service/Settings/SettingsUserLifecycleGatewayTest.php b/tests/Service/Settings/SettingsUserLifecycleGatewayTest.php
new file mode 100644
index 0000000..3a31471
--- /dev/null
+++ b/tests/Service/Settings/SettingsUserLifecycleGatewayTest.php
@@ -0,0 +1,52 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Settings;
+
+use MintyPHP\Repository\Settings\SettingRepositoryInterface;
+use MintyPHP\Service\Settings\SettingsMetadataGateway;
+use MintyPHP\Service\Settings\SettingsUserLifecycleGateway;
+use PHPUnit\Framework\TestCase;
+
+class SettingsUserLifecycleGatewayTest extends TestCase
+{
+    public function testSetUserInactivityDeleteDaysRequiresDeactivatePolicy(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturnCallback(static function (string $key): ?string {
+            if ($key === 'user_inactivity_deactivate_days') {
+                return '0';
+            }
+            return null;
+        });
+        $settings->expects($this->never())->method('set');
+
+        $gateway = new SettingsUserLifecycleGateway(new SettingsMetadataGateway($settings));
+        $this->assertFalse($gateway->setUserInactivityDeleteDays(30));
+    }
+
+    public function testSetUserInactivityDeactivateDaysSetsDeleteToZeroWhenDisabled(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->expects($this->exactly(2))->method('set')->willReturn(true);
+
+        $gateway = new SettingsUserLifecycleGateway(new SettingsMetadataGateway($settings));
+        $this->assertTrue($gateway->setUserInactivityDeactivateDays(0));
+    }
+
+    public function testGetUserInactivityDeleteDaysReturnsZeroWhenDeactivateDisabled(): void
+    {
+        $settings = $this->createMock(SettingRepositoryInterface::class);
+        $settings->method('getValue')->willReturnCallback(static function (string $key): ?string {
+            if ($key === 'user_inactivity_deactivate_days') {
+                return '0';
+            }
+            if ($key === 'user_inactivity_delete_days') {
+                return '180';
+            }
+            return null;
+        });
+
+        $gateway = new SettingsUserLifecycleGateway(new SettingsMetadataGateway($settings));
+        $this->assertSame(0, $gateway->getUserInactivityDeleteDays());
+    }
+}
diff --git a/tests/Service/User/UserAccountServiceTest.php b/tests/Service/User/UserAccountServiceTest.php
new file mode 100644
index 0000000..4bbe8c3
--- /dev/null
+++ b/tests/Service/User/UserAccountServiceTest.php
@@ -0,0 +1,479 @@
+<?php
+
+namespace MintyPHP\Tests\Service\User;
+
+use MintyPHP\Repository\User\UserListQueryRepositoryInterface;
+use MintyPHP\Repository\User\UserReadRepositoryInterface;
+use MintyPHP\Repository\User\UserWriteRepositoryInterface;
+use MintyPHP\Service\Audit\SystemAuditService;
+use MintyPHP\Service\User\UserAccountService;
+use MintyPHP\Service\User\UserAssignmentService;
+use MintyPHP\Service\User\UserDirectoryGateway;
+use MintyPHP\Service\User\UserPasswordService;
+use MintyPHP\Service\User\UserScopeGateway;
+use MintyPHP\Service\User\UserSettingsGateway;
+use PHPUnit\Framework\TestCase;
+
+class UserAccountServiceTest extends TestCase
+{
+    public function testListPagedDropsTenantUserIdForGlobalAccess(): void
+    {
+        $scopeGateway = $this->createMock(UserScopeGateway::class);
+        $scopeGateway->expects($this->once())
+            ->method('hasGlobalAccess')
+            ->with(99)
+            ->willReturn(true);
+
+        $listQueryRepository = $this->createMock(UserListQueryRepositoryInterface::class);
+        $listQueryRepository->expects($this->once())
+            ->method('listPaged')
+            ->with($this->callback(static function (array $options): bool {
+                return !isset($options['tenantUserId'])
+                    && (int) ($options['page'] ?? 0) === 2;
+            }))
+            ->willReturn(['rows' => [], 'total' => 0]);
+
+        $service = $this->newService(null, null, $listQueryRepository, null, null, null, $scopeGateway);
+        $result = $service->listPaged(['page' => 2, 'tenantUserId' => 99]);
+
+        $this->assertSame(0, (int) ($result['total'] ?? -1));
+    }
+
+    public function testDeleteByUuidReturnsNotFoundForEmptyUuid(): void
+    {
+        $service = $this->newService();
+
+        $result = $service->deleteByUuid('');
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame(404, (int) ($result['status'] ?? 0));
+        $this->assertSame('not_found', (string) ($result['error'] ?? ''));
+    }
+
+    public function testDeleteByUuidPreventsSelfDelete(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->expects($this->once())
+            ->method('findByUuid')
+            ->with('user-uuid')
+            ->willReturn(['id' => 10, 'uuid' => 'user-uuid']);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->never())->method('delete');
+
+        $service = $this->newService($readRepository, $writeRepository);
+        $result = $service->deleteByUuid('user-uuid', 10);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame(400, (int) ($result['status'] ?? 0));
+        $this->assertSame('self_delete', (string) ($result['error'] ?? ''));
+    }
+
+    public function testDeleteByUuidDeletesAndRecordsAuditEvent(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->expects($this->once())
+            ->method('findByUuid')
+            ->with('user-uuid')
+            ->willReturn(['id' => 11, 'uuid' => 'user-uuid']);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->once())
+            ->method('delete')
+            ->with(11)
+            ->willReturn(true);
+
+        $auditService = $this->createMock(SystemAuditService::class);
+        $auditService->expects($this->once())
+            ->method('record')
+            ->with(
+                'admin.users.delete',
+                'success',
+                $this->callback(static function (array $context): bool {
+                    return (int) ($context['actor_user_id'] ?? 0) === 44
+                        && (int) ($context['target_id'] ?? 0) === 11
+                        && (string) ($context['target_uuid'] ?? '') === 'user-uuid';
+                })
+            );
+
+        $service = $this->newService($readRepository, $writeRepository, null, null, null, null, null, null, $auditService);
+        $result = $service->deleteByUuid('user-uuid', 44);
+
+        $this->assertTrue($result['ok']);
+        $this->assertSame(11, (int) (($result['user'] ?? [])['id'] ?? 0));
+    }
+
+    public function testDeleteByUuidsReturnsPermissionDeniedWhenNothingIsInScope(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->method('findByUuid')->willReturn(['id' => 51, 'uuid' => 'other-uuid']);
+
+        $scopeGateway = $this->createMock(UserScopeGateway::class);
+        $scopeGateway->method('canAccess')->willReturn(false);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->never())->method('deleteByUuids');
+
+        $service = $this->newService($readRepository, $writeRepository, null, null, null, null, $scopeGateway);
+        $result = $service->deleteByUuids(['other-uuid'], 99);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('permission_denied', (string) ($result['error'] ?? ''));
+    }
+
+    public function testDeleteByUuidsReturnsSelfDeleteWhenOnlyOwnUuidRemains(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->expects($this->once())
+            ->method('findByUuid')
+            ->with('self-uuid')
+            ->willReturn(['id' => 99, 'uuid' => 'self-uuid']);
+        $readRepository->expects($this->once())
+            ->method('find')
+            ->with(99)
+            ->willReturn(['id' => 99, 'uuid' => 'self-uuid']);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->never())->method('deleteByUuids');
+
+        $service = $this->newService($readRepository, $writeRepository);
+        $result = $service->deleteByUuids(['self-uuid'], 99);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame('self_delete', (string) ($result['error'] ?? ''));
+    }
+
+    public function testSetActiveByUuidPreventsSelfDeactivate(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->method('findByUuid')->willReturn(['id' => 42, 'uuid' => 'u-42']);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->never())->method('setActive');
+
+        $service = $this->newService($readRepository, $writeRepository);
+        $result = $service->setActiveByUuid('u-42', false, 42);
+
+        $this->assertFalse($result['ok']);
+        $this->assertSame(400, (int) ($result['status'] ?? 0));
+        $this->assertSame('self_deactivate', (string) ($result['error'] ?? ''));
+    }
+
+    public function testSetActiveByUuidUpdatesAssignmentsAndAudit(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->method('findByUuid')->willReturn(['id' => 33, 'uuid' => 'u-33', 'active' => 0]);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->once())
+            ->method('setActive')
+            ->with(33, true, 90)
+            ->willReturn(true);
+
+        $assignmentService = $this->createMock(UserAssignmentService::class);
+        $assignmentService->expects($this->once())
+            ->method('bumpAuthzVersion')
+            ->with(33);
+
+        $auditService = $this->createMock(SystemAuditService::class);
+        $auditService->expects($this->once())
+            ->method('record')
+            ->with(
+                'admin.users.activate',
+                'success',
+                $this->callback(static fn ($context): bool => is_array($context))
+            );
+
+        $service = $this->newService($readRepository, $writeRepository, null, $assignmentService, null, null, null, null, $auditService);
+        $result = $service->setActiveByUuid('u-33', true, 90);
+
+        $this->assertTrue($result['ok']);
+    }
+
+    public function testSetActiveByUuidsBumpsAuthzVersionForResolvedUserIds(): void
+    {
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->once())
+            ->method('setActiveByUuids')
+            ->with(['u-1', 'u-2'], false, 7)
+            ->willReturn(true);
+        $writeRepository->expects($this->once())
+            ->method('bumpAuthzVersionByUserIds')
+            ->with([11, 12])
+            ->willReturn(2);
+
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->method('findByUuid')->willReturnMap([
+            ['u-1', ['id' => 11, 'uuid' => 'u-1']],
+            ['u-2', ['id' => 12, 'uuid' => 'u-2']],
+        ]);
+
+        $scopeGateway = $this->createMock(UserScopeGateway::class);
+        $scopeGateway->method('canAccess')->willReturn(true);
+
+        $auditService = $this->createMock(SystemAuditService::class);
+        $auditService->expects($this->once())
+            ->method('record')
+            ->with(
+                'admin.users.bulk_update',
+                'success',
+                $this->callback(static fn ($context): bool => is_array($context))
+            );
+
+        $service = $this->newService($readRepository, $writeRepository, null, null, null, null, $scopeGateway, null, $auditService);
+        $result = $service->setActiveByUuids(['u-1', 'u-2'], false, 7);
+
+        $this->assertTrue($result['ok']);
+        $this->assertSame(2, (int) ($result['count'] ?? 0));
+    }
+
+    public function testRegisterCreatesUserAndAssignsDefaultEntities(): void
+    {
+        $passwordService = $this->createMock(UserPasswordService::class);
+        $passwordService->method('validatePassword')->willReturn([]);
+
+        $settingsGateway = $this->createMock(UserSettingsGateway::class);
+        $settingsGateway->method('getAppTheme')->willReturn('dark');
+        $settingsGateway->method('getDefaultTenantId')->willReturn(3);
+        $settingsGateway->method('getDefaultRoleId')->willReturn(4);
+        $settingsGateway->method('getDefaultDepartmentId')->willReturn(5);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->once())
+            ->method('create')
+            ->with($this->callback(static function (array $data): bool {
+                return (string) ($data['email'] ?? '') === 'user@example.com'
+                    && (string) ($data['theme'] ?? '') === 'dark'
+                    && (int) ($data['primary_tenant_id'] ?? 0) === 3
+                    && (int) ($data['active'] ?? 0) === 1;
+            }))
+            ->willReturn(77);
+
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->expects($this->exactly(2))
+            ->method('findByEmail')
+            ->with('user@example.com')
+            ->willReturnOnConsecutiveCalls(
+                null,
+                ['id' => 77, 'uuid' => 'user-uuid']
+            );
+
+        $assignmentService = $this->createMock(UserAssignmentService::class);
+        $assignmentService->expects($this->once())->method('syncTenants')->with(77, [3]);
+        $assignmentService->expects($this->once())->method('syncRoles')->with(77, [4]);
+        $assignmentService->expects($this->once())->method('syncDepartments')->with(77, [5]);
+
+        $service = $this->newService(
+            $readRepository,
+            $writeRepository,
+            null,
+            $assignmentService,
+            $passwordService,
+            $settingsGateway
+        );
+
+        $result = $service->register([
+            'first_name' => 'Max',
+            'last_name' => 'Mustermann',
+            'email' => 'user@example.com',
+            'password' => 'StrongPass1!',
+            'password2' => 'StrongPass1!',
+        ]);
+
+        $this->assertTrue($result['ok']);
+    }
+
+    public function testUpdateSelfProfileReturnsErrorWhenRequestedTenantIsNotAssigned(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->expects($this->once())
+            ->method('find')
+            ->with(15)
+            ->willReturn([
+                'id' => 15,
+                'first_name' => 'Max',
+                'last_name' => 'Mustermann',
+                'locale' => 'de',
+                'theme' => 'light',
+            ]);
+
+        $directoryGateway = $this->createMock(UserDirectoryGateway::class);
+        $directoryGateway->expects($this->once())
+            ->method('findTenantByUuid')
+            ->with('tenant-uuid-2')
+            ->willReturn(['id' => 2, 'uuid' => 'tenant-uuid-2']);
+
+        $assignmentService = $this->createMock(UserAssignmentService::class);
+        $assignmentService->expects($this->once())
+            ->method('buildAssignmentsForUser')
+            ->with(15)
+            ->willReturn([
+                'tenants' => [['id' => 1, 'uuid' => 'tenant-uuid-1']],
+                'roles' => [],
+                'departments' => [],
+            ]);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->never())->method('update');
+
+        $service = $this->newService(
+            $readRepository,
+            $writeRepository,
+            null,
+            $assignmentService,
+            null,
+            null,
+            null,
+            $directoryGateway
+        );
+
+        $result = $service->updateSelfProfile(15, [
+            'first_name' => 'Max',
+            'last_name' => 'Mustermann',
+            'current_tenant_uuid' => 'tenant-uuid-2',
+        ]);
+
+        $this->assertFalse($result['ok']);
+        $this->assertNotEmpty($result['errors']);
+    }
+
+    public function testUpdateSelfProfilePersistsDataAndTenantSwitchWhenAllowed(): void
+    {
+        $readRepository = $this->createMock(UserReadRepositoryInterface::class);
+        $readRepository->expects($this->once())
+            ->method('find')
+            ->with(21)
+            ->willReturn([
+                'id' => 21,
+                'first_name' => 'Max',
+                'last_name' => 'Mustermann',
+                'profile_description' => '',
+                'job_title' => '',
+                'phone' => '',
+                'mobile' => '',
+                'short_dial' => '',
+                'address' => '',
+                'postal_code' => '',
+                'city' => '',
+                'country' => '',
+                'region' => '',
+                'locale' => 'de',
+                'theme' => 'light',
+            ]);
+
+        $directoryGateway = $this->createMock(UserDirectoryGateway::class);
+        $directoryGateway->expects($this->once())
+            ->method('findTenantByUuid')
+            ->with('tenant-uuid-9')
+            ->willReturn(['id' => 9, 'uuid' => 'tenant-uuid-9']);
+
+        $assignmentService = $this->createMock(UserAssignmentService::class);
+        $assignmentService->expects($this->once())
+            ->method('buildAssignmentsForUser')
+            ->with(21)
+            ->willReturn([
+                'tenants' => [['id' => 9, 'uuid' => 'tenant-uuid-9']],
+                'roles' => [],
+                'departments' => [],
+            ]);
+
+        $writeRepository = $this->createMock(UserWriteRepositoryInterface::class);
+        $writeRepository->expects($this->once())
+            ->method('update')
+            ->with(21, $this->callback(static fn ($payload): bool => is_array($payload)))
+            ->willReturn(true);
+        $writeRepository->expects($this->once())
+            ->method('setCurrentTenant')
+            ->with(21, 9)
+            ->willReturn(true);
+
+        $service = $this->newService(
+            $readRepository,
+            $writeRepository,
+            null,
+            $assignmentService,
+            null,
+            null,
+            null,
+            $directoryGateway
+        );
+
+        $result = $service->updateSelfProfile(21, [
+            'first_name' => 'Max',
+            'last_name' => 'Mustermann',
+            'current_tenant_uuid' => 'tenant-uuid-9',
+            'locale' => 'de',
+            'theme' => 'light',
+        ]);
+
+        $this->assertTrue($result['ok']);
+    }
+
+    private function newService(
+        ?UserReadRepositoryInterface $readRepository = null,
+        ?UserWriteRepositoryInterface $writeRepository = null,
+        ?UserListQueryRepositoryInterface $listQueryRepository = null,
+        ?UserAssignmentService $assignmentService = null,
+        ?UserPasswordService $passwordService = null,
+        ?UserSettingsGateway $settingsGateway = null,
+        ?UserScopeGateway $scopeGateway = null,
+        ?UserDirectoryGateway $directoryGateway = null,
+        ?SystemAuditService $auditService = null
+    ): UserAccountService {
+        $readRepository = $readRepository ?? $this->createMock(UserReadRepositoryInterface::class);
+        $writeRepository = $writeRepository ?? $this->createMock(UserWriteRepositoryInterface::class);
+        $listQueryRepository = $listQueryRepository ?? $this->createMock(UserListQueryRepositoryInterface::class);
+
+        if ($assignmentService === null) {
+            $assignmentService = $this->createMock(UserAssignmentService::class);
+            $assignmentService->method('normalizeTenantIds')->willReturn([]);
+            $assignmentService->method('normalizeIdInput')->willReturn([]);
+            $assignmentService->method('buildAssignmentsForUser')->willReturn([
+                'tenants' => [],
+                'roles' => [],
+                'departments' => [],
+            ]);
+            $assignmentService->method('syncTenants')->willReturn(true);
+            $assignmentService->method('syncRoles')->willReturn(true);
+            $assignmentService->method('syncDepartments')->willReturn(true);
+        }
+
+        if ($passwordService === null) {
+            $passwordService = $this->createMock(UserPasswordService::class);
+            $passwordService->method('validatePassword')->willReturn([]);
+        }
+
+        if ($settingsGateway === null) {
+            $settingsGateway = $this->createMock(UserSettingsGateway::class);
+            $settingsGateway->method('getDefaultTenantId')->willReturn(null);
+            $settingsGateway->method('getDefaultRoleId')->willReturn(null);
+            $settingsGateway->method('getDefaultDepartmentId')->willReturn(null);
+            $settingsGateway->method('getAppTheme')->willReturn('light');
+        }
+
+        if ($scopeGateway === null) {
+            $scopeGateway = $this->createMock(UserScopeGateway::class);
+            $scopeGateway->method('hasGlobalAccess')->willReturn(false);
+            $scopeGateway->method('canAccess')->willReturn(false);
+        }
+
+        if ($directoryGateway === null) {
+            $directoryGateway = $this->createMock(UserDirectoryGateway::class);
+            $directoryGateway->method('findTenantByUuid')->willReturn(null);
+        }
+
+        $auditService = $auditService ?? $this->createMock(SystemAuditService::class);
+
+        return new UserAccountService(
+            $readRepository,
+            $writeRepository,
+            $listQueryRepository,
+            $assignmentService,
+            $passwordService,
+            $settingsGateway,
+            $scopeGateway,
+            $directoryGateway,
+            $auditService
+        );
+    }
+}
diff --git a/web/css/components/app-confirm-dialog.css b/web/css/components/app-confirm-dialog.css
new file mode 100644
index 0000000..1dad676
--- /dev/null
+++ b/web/css/components/app-confirm-dialog.css
@@ -0,0 +1,58 @@
+@layer components {
+  dialog[data-app-confirm-dialog] > article.app-confirm-dialog {
+    max-width: 32rem;
+  }
+
+  dialog[data-app-confirm-dialog] > article.app-confirm-dialog > header {
+    position: relative;
+    padding-inline-end: 2rem;
+  }
+
+  dialog[data-app-confirm-dialog] > article.app-confirm-dialog > header h2 {
+    margin: 0;
+  }
+
+  dialog[data-app-confirm-dialog] [data-app-confirm-close].close {
+    position: absolute;
+    inset-inline-end: 1rem;
+    inset-block-start: 1rem;
+    float: none;
+    margin: 0;
+  }
+
+  dialog[data-app-confirm-dialog] [data-app-confirm-message] {
+    margin-bottom: 0.5rem;
+    white-space: pre-wrap;
+  }
+
+  dialog[data-app-confirm-dialog] [data-app-confirm-note] {
+    margin-top: 0;
+    margin-bottom: 0;
+  }
+
+  dialog[data-app-confirm-dialog] footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.5rem;
+    padding: 10px;
+  }
+
+  dialog[data-app-confirm-dialog] footer button {
+    margin: 0;
+  }
+
+  dialog[data-app-confirm-dialog][data-confirm-variant="danger"] > article {
+    border-top: 3px solid var(--app-del-color, #b42318);
+  }
+
+  dialog[data-app-confirm-dialog][data-confirm-variant="warning"] > article {
+    border-top: 3px solid var(--app-warning-color, #b54708);
+  }
+
+  @media (max-width: 576px) {
+    dialog[data-app-confirm-dialog] footer {
+      flex-direction: column-reverse;
+      align-items: stretch;
+    }
+  }
+}
diff --git a/web/css/layout/app-aside-icon-bar.css b/web/css/layout/app-aside-icon-bar.css
index 97b1674..8a0e13d 100644
--- a/web/css/layout/app-aside-icon-bar.css
+++ b/web/css/layout/app-aside-icon-bar.css
@@ -5,6 +5,7 @@ aside.aside-icon-bar {
   --app-icon-bar-border-width: 3px;
   --app-icon-bar-hover-bg: var(--app-accordion-border-color);
   --app-icon-bar-border: 1px solid var(--app-border);
+  --app-icon-bar-mobile-safe-space: calc(3.5rem + env(safe-area-inset-bottom));
   display: none;
 }
 
@@ -104,5 +105,13 @@ aside.aside-icon-bar li button.active {
     border-left: 0;
     border-top: var(--app-icon-bar-border-width) solid var(--app-primary);
   }
+
+  .app-main-content,
+  footer.site-footer {
+    padding-bottom: max(
+      var(--app-spacing),
+      var(--app-icon-bar-mobile-safe-space)
+    );
+  }
 }
 }
diff --git a/web/css/layout/app-sidebar.css b/web/css/layout/app-sidebar.css
index 7cfe027..81084d4 100644
--- a/web/css/layout/app-sidebar.css
+++ b/web/css/layout/app-sidebar.css
@@ -218,7 +218,6 @@
     padding: 0 var(--app-spacing);
     font-size: var(--app-sidebar-summary-size);
     color: var(--app-muted-color);
-    line-height: 1;
   }
 
   nav#aside-panel-people {
diff --git a/web/js/app-init.js b/web/js/app-init.js
index 431e93a..39cd9e6 100644
--- a/web/js/app-init.js
+++ b/web/js/app-init.js
@@ -1,3 +1,4 @@
+import './core/app-telemetry.js';
 import './components/app-flash-auto-dismiss.js';
 import './components/app-tabs.js';
 import './components/app-fslightbox-refresh.js';
@@ -20,3 +21,4 @@ import './components/app-color-default-toggle.js';
 import './components/app-custom-field-options-toggle.js';
 import './components/app-tenant-sso-toggle.js';
 import './components/app-standard-detail-page.js';
+import './components/app-settings-telemetry.js';
diff --git a/web/js/app-login-init.js b/web/js/app-login-init.js
index e483ae8..15a9cc4 100644
--- a/web/js/app-login-init.js
+++ b/web/js/app-login-init.js
@@ -1,2 +1,3 @@
+import './core/app-telemetry.js';
 import './components/app-flash-auto-dismiss.js';
 import './components/app-password-hints.js';
diff --git a/web/js/components/app-confirm-actions.js b/web/js/components/app-confirm-actions.js
index 135818a..f448f91 100644
--- a/web/js/components/app-confirm-actions.js
+++ b/web/js/components/app-confirm-actions.js
@@ -1,4 +1,10 @@
+import { confirmDialog, requestSubmitWithFallback } from '../core/app-confirm-dialog.js';
+
 const CONFIRM_ATTR = 'data-confirm-message';
+const confirmedSubmitterByForm = new WeakMap();
+const confirmedClickElements = new WeakSet();
+
+const trimAttr = (element, attr) => String(element?.getAttribute(attr) || '').trim();
 
 const isSubmitControl = (element) => {
   if (!(element instanceof HTMLElement)) {
@@ -16,6 +22,38 @@ const isSubmitControl = (element) => {
 };
 
 const submitterByForm = new Map();
+const belongsToForm = (control, form) => {
+  if (!(control instanceof HTMLElement) || !(form instanceof HTMLFormElement)) {
+    return false;
+  }
+  const owner = control.form;
+  if (owner instanceof HTMLFormElement) {
+    return owner === form;
+  }
+  const controlFormAttr = trimAttr(control, 'form');
+  const formId = trimAttr(form, 'id');
+  if (controlFormAttr !== '' && formId !== '') {
+    return controlFormAttr === formId;
+  }
+  return form.contains(control);
+};
+
+const readConfirmOption = (primary, fallback, suffix) => {
+  const attr = `data-confirm-${suffix}`;
+  return trimAttr(primary, attr) || trimAttr(fallback, attr);
+};
+
+const buildConfirmOptions = (message, primary, fallback) => ({
+  message,
+  title: readConfirmOption(primary, fallback, 'title'),
+  confirmLabel: readConfirmOption(primary, fallback, 'confirm-label'),
+  cancelLabel: readConfirmOption(primary, fallback, 'cancel-label'),
+  variant: readConfirmOption(primary, fallback, 'variant'),
+  focus: readConfirmOption(primary, fallback, 'focus'),
+  describedBy: readConfirmOption(primary, fallback, 'describedby')
+    || readConfirmOption(primary, fallback, 'described-by'),
+  actionKind: readConfirmOption(primary, fallback, 'action-kind')
+});
 
 const onClickCapture = (event) => {
   const trigger = event.target instanceof HTMLElement ? event.target.closest('a, button, input') : null;
@@ -23,6 +61,11 @@ const onClickCapture = (event) => {
     return;
   }
 
+  if (confirmedClickElements.has(trigger)) {
+    confirmedClickElements.delete(trigger);
+    return;
+  }
+
   if (isSubmitControl(trigger)) {
     const form = trigger.form instanceof HTMLFormElement ? trigger.form : null;
     if (form) {
@@ -36,10 +79,17 @@ const onClickCapture = (event) => {
     return;
   }
 
-  if (!window.confirm(confirmMessage)) {
-    event.preventDefault();
-    event.stopPropagation();
-  }
+  event.preventDefault();
+  event.stopPropagation();
+
+  void confirmDialog.confirm(buildConfirmOptions(confirmMessage, trigger, null))
+    .then((approved) => {
+      if (!approved || !document.contains(trigger)) {
+        return;
+      }
+      confirmedClickElements.add(trigger);
+      trigger.click();
+    });
 };
 
 const onSubmitCapture = (event) => {
@@ -53,6 +103,12 @@ const onSubmitCapture = (event) => {
     : (submitterByForm.get(form) || null);
   submitterByForm.delete(form);
 
+  const confirmedSubmitter = confirmedSubmitterByForm.get(form);
+  if (confirmedSubmitter && (confirmedSubmitter === true || confirmedSubmitter === submitter || confirmedSubmitter === null)) {
+    confirmedSubmitterByForm.delete(form);
+    return;
+  }
+
   const submitterMessage = String(submitter?.getAttribute(CONFIRM_ATTR) || '').trim();
   const formMessage = String(form.getAttribute(CONFIRM_ATTR) || '').trim();
   const confirmMessage = submitterMessage !== '' ? submitterMessage : formMessage;
@@ -60,10 +116,19 @@ const onSubmitCapture = (event) => {
   if (confirmMessage === '') {
     return;
   }
-  if (!window.confirm(confirmMessage)) {
-    event.preventDefault();
-    event.stopPropagation();
-  }
+
+  event.preventDefault();
+  event.stopPropagation();
+
+  void confirmDialog.confirm(buildConfirmOptions(confirmMessage, submitter, form))
+    .then((approved) => {
+      if (!approved || !document.contains(form)) {
+        return;
+      }
+      const submitterForSubmit = submitter && belongsToForm(submitter, form) ? submitter : null;
+      confirmedSubmitterByForm.set(form, submitterForSubmit || true);
+      requestSubmitWithFallback(form, submitterForSubmit);
+    });
 };
 
 document.addEventListener('click', onClickCapture, true);
diff --git a/web/js/components/app-settings-telemetry.js b/web/js/components/app-settings-telemetry.js
new file mode 100644
index 0000000..839a389
--- /dev/null
+++ b/web/js/components/app-settings-telemetry.js
@@ -0,0 +1,35 @@
+const initTelemetrySettings = () => {
+  const panel = document.querySelector('[data-tab-panel="telemetry"]');
+  if (!panel) {
+    return;
+  }
+
+  const toggle = panel.querySelector('[data-telemetry-enabled-toggle]');
+  const samplingFieldset = panel.querySelector('[data-telemetry-sampling-fieldset]');
+  const samplingRow = panel.querySelector('[data-telemetry-sampling-row]');
+  const samplingSelect = panel.querySelector('[data-telemetry-sampling-select]');
+
+  if (!toggle || !samplingFieldset) {
+    return;
+  }
+
+  const syncSamplingVisibility = () => {
+    const active = Boolean(toggle.checked);
+    samplingFieldset.hidden = !active;
+    if (samplingRow) {
+      samplingRow.hidden = !active;
+    }
+    if (samplingSelect) {
+      samplingSelect.disabled = !active || toggle.disabled;
+    }
+  };
+
+  toggle.addEventListener('change', syncSamplingVisibility);
+  syncSamplingVisibility();
+};
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initTelemetrySettings);
+} else {
+  initTelemetrySettings();
+}
diff --git a/web/js/core/app-confirm-dialog.js b/web/js/core/app-confirm-dialog.js
new file mode 100644
index 0000000..66a901a
--- /dev/null
+++ b/web/js/core/app-confirm-dialog.js
@@ -0,0 +1,325 @@
+import { warnOnce } from './app-dom.js';
+
+const VARIANTS = new Set(['default', 'warning', 'danger']);
+const FOCUS_TARGETS = new Set(['confirm', 'cancel']);
+const DANGER_KEYWORDS = /(delete|deleted|purge|revoke|remove|destroy|danger|erase|drop|wipe|lösch|loesch|entfern|widerruf)/i;
+const FOCUSABLE_SELECTOR = [
+  'button:not([disabled])',
+  'a[href]',
+  'input:not([type="hidden"]):not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])'
+].join(',');
+
+const trimValue = (value) => String(value ?? '').trim();
+
+const getNativeConfirm = () => {
+  const fallback = window?.['confirm'];
+  return typeof fallback === 'function' ? fallback.bind(window) : null;
+};
+
+const normalizeVariant = (value) => {
+  const variant = trimValue(value).toLowerCase();
+  return VARIANTS.has(variant) ? variant : '';
+};
+
+const normalizeFocus = (value) => {
+  const focus = trimValue(value).toLowerCase();
+  return FOCUS_TARGETS.has(focus) ? focus : '';
+};
+
+const inferVariant = ({ variant = '', actionKind = '', message = '' } = {}) => {
+  const explicit = normalizeVariant(variant);
+  if (explicit !== '') {
+    return explicit;
+  }
+  const action = trimValue(actionKind).toLowerCase();
+  if (action.includes('danger') || action.includes('delete') || action.includes('purge') || action.includes('revoke')) {
+    return 'danger';
+  }
+  return DANGER_KEYWORDS.test(trimValue(message)) ? 'danger' : 'default';
+};
+
+const getFocusableElements = (dialog) => Array.from(dialog.querySelectorAll(FOCUSABLE_SELECTOR))
+  .filter((element) => !element.hasAttribute('hidden'))
+  .filter((element) => element.getAttribute('aria-hidden') !== 'true');
+
+const requestSubmitWithFallback = (form, submitter) => {
+  if (!(form instanceof HTMLFormElement)) {
+    return;
+  }
+  if (typeof form.requestSubmit === 'function') {
+    if (submitter instanceof HTMLElement) {
+      try {
+        form.requestSubmit(submitter);
+        return;
+      } catch {
+        // Fallback below.
+      }
+    }
+    form.requestSubmit();
+    return;
+  }
+  if (submitter instanceof HTMLElement && typeof submitter.click === 'function') {
+    submitter.click();
+    return;
+  }
+  form.submit();
+};
+
+class ConfirmDialogController {
+  constructor() {
+    this.queue = Promise.resolve();
+  }
+
+  enqueue(task) {
+    const next = this.queue.then(task, task);
+    this.queue = next.then(() => undefined, () => undefined);
+    return next;
+  }
+
+  resolveElements() {
+    const dialog = document.querySelector('[data-app-confirm-dialog]');
+    if (!(dialog instanceof HTMLDialogElement)) {
+      return null;
+    }
+    const titleEl = dialog.querySelector('[data-app-confirm-title]');
+    const messageEl = dialog.querySelector('[data-app-confirm-message]');
+    const noteEl = dialog.querySelector('[data-app-confirm-note]');
+    const cancelButton = dialog.querySelector('[data-app-confirm-cancel]');
+    const confirmButton = dialog.querySelector('[data-app-confirm-confirm]');
+    const closeButton = dialog.querySelector('[data-app-confirm-close]');
+
+    if (!(titleEl instanceof HTMLElement) || !(messageEl instanceof HTMLElement) || !(cancelButton instanceof HTMLButtonElement) || !(confirmButton instanceof HTMLButtonElement)) {
+      warnOnce('UI_CONFIRM_DIALOG_INVALID', 'Missing confirm dialog elements', { module: 'confirm-dialog' });
+      return null;
+    }
+
+    return {
+      dialog,
+      titleEl,
+      messageEl,
+      noteEl: noteEl instanceof HTMLElement ? noteEl : null,
+      cancelButton,
+      confirmButton,
+      closeButton: closeButton instanceof HTMLButtonElement ? closeButton : null
+    };
+  }
+
+  fallbackConfirm(options = {}) {
+    const message = trimValue(options.message);
+    if (message === '') {
+      return Promise.resolve(true);
+    }
+    const fallback = getNativeConfirm();
+    if (!fallback) {
+      return Promise.resolve(false);
+    }
+    return Promise.resolve(Boolean(fallback(message)));
+  }
+
+  run(options = {}) {
+    const message = trimValue(options.message);
+    if (message === '') {
+      return Promise.resolve(true);
+    }
+
+    const elements = this.resolveElements();
+    if (!elements || typeof elements.dialog.showModal !== 'function') {
+      return this.fallbackConfirm({ message });
+    }
+
+    return new Promise((resolve) => {
+      const {
+        dialog,
+        titleEl,
+        messageEl,
+        noteEl,
+        cancelButton,
+        confirmButton,
+        closeButton
+      } = elements;
+
+      const variant = inferVariant(options);
+      const focusTarget = normalizeFocus(options.focus) || (variant === 'danger' ? 'cancel' : 'confirm');
+      const dataset = dialog.dataset || {};
+      const title = trimValue(options.title) || trimValue(dataset.defaultTitle) || 'Please confirm';
+      const confirmLabel = trimValue(options.confirmLabel) || trimValue(dataset.defaultConfirmLabel) || 'Confirm';
+      const cancelLabel = trimValue(options.cancelLabel) || trimValue(dataset.defaultCancelLabel) || 'Cancel';
+      const describedByExternal = trimValue(options.describedBy);
+      const note = trimValue(options.note) || (variant === 'danger' ? trimValue(dataset.defaultDangerNote) : '');
+
+      const activeElement = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+      const cleanupCallbacks = [];
+      let resolved = false;
+
+      const addCleanup = (fn) => {
+        cleanupCallbacks.push(fn);
+      };
+
+      const cleanup = () => {
+        while (cleanupCallbacks.length > 0) {
+          const fn = cleanupCallbacks.pop();
+          try {
+            fn();
+          } catch {
+            // no-op
+          }
+        }
+      };
+
+      const finish = (approved) => {
+        if (resolved) {
+          return;
+        }
+        resolved = true;
+        cleanup();
+        try {
+          if (dialog.open) {
+            dialog.close(approved ? 'confirm' : 'cancel');
+          }
+        } catch {
+          // no-op
+        }
+        document.body.classList.remove('modal-is-open');
+        if (activeElement && document.contains(activeElement)) {
+          window.requestAnimationFrame(() => {
+            activeElement.focus({ preventScroll: true });
+          });
+        }
+        resolve(Boolean(approved));
+      };
+
+      const onCancelClick = (event) => {
+        event.preventDefault();
+        finish(false);
+      };
+      const onCloseClick = (event) => {
+        event.preventDefault();
+        finish(false);
+      };
+      const onConfirmClick = (event) => {
+        event.preventDefault();
+        finish(true);
+      };
+      const onDialogCancel = (event) => {
+        event.preventDefault();
+        finish(false);
+      };
+      const onBackdropClick = (event) => {
+        if (event.target === dialog) {
+          finish(false);
+        }
+      };
+      const onClose = () => {
+        finish(dialog.returnValue === 'confirm');
+      };
+      const onKeyDown = (event) => {
+        if (event.key !== 'Tab') {
+          return;
+        }
+        const focusable = getFocusableElements(dialog);
+        if (!focusable.length) {
+          event.preventDefault();
+          return;
+        }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const active = document.activeElement;
+        if (event.shiftKey) {
+          if (active === first || !dialog.contains(active)) {
+            event.preventDefault();
+            last.focus();
+          }
+          return;
+        }
+        if (active === last) {
+          event.preventDefault();
+          first.focus();
+        }
+      };
+
+      titleEl.textContent = title;
+      messageEl.textContent = message;
+      cancelButton.textContent = cancelLabel;
+      confirmButton.textContent = confirmLabel;
+      dialog.setAttribute('data-confirm-variant', variant);
+      confirmButton.classList.remove('primary', 'warning', 'danger');
+      if (variant === 'danger') {
+        confirmButton.classList.add('danger');
+      } else if (variant === 'warning') {
+        confirmButton.classList.add('warning');
+      } else {
+        confirmButton.classList.add('primary');
+      }
+
+      if (noteEl) {
+        if (note === '') {
+          noteEl.hidden = true;
+          noteEl.textContent = '';
+        } else {
+          noteEl.hidden = false;
+          noteEl.textContent = note;
+        }
+      }
+
+      const describedByIds = [
+        trimValue(messageEl.id),
+        noteEl && !noteEl.hidden ? trimValue(noteEl.id) : '',
+        describedByExternal
+      ].filter(Boolean);
+      if (describedByIds.length) {
+        dialog.setAttribute('aria-describedby', describedByIds.join(' '));
+      } else {
+        dialog.removeAttribute('aria-describedby');
+      }
+
+      cancelButton.addEventListener('click', onCancelClick);
+      if (closeButton) {
+        closeButton.addEventListener('click', onCloseClick);
+      }
+      confirmButton.addEventListener('click', onConfirmClick);
+      dialog.addEventListener('cancel', onDialogCancel);
+      dialog.addEventListener('click', onBackdropClick);
+      dialog.addEventListener('close', onClose);
+      dialog.addEventListener('keydown', onKeyDown);
+
+      addCleanup(() => cancelButton.removeEventListener('click', onCancelClick));
+      if (closeButton) {
+        addCleanup(() => closeButton.removeEventListener('click', onCloseClick));
+      }
+      addCleanup(() => confirmButton.removeEventListener('click', onConfirmClick));
+      addCleanup(() => dialog.removeEventListener('cancel', onDialogCancel));
+      addCleanup(() => dialog.removeEventListener('click', onBackdropClick));
+      addCleanup(() => dialog.removeEventListener('close', onClose));
+      addCleanup(() => dialog.removeEventListener('keydown', onKeyDown));
+
+      document.body.classList.add('modal-is-open');
+
+      try {
+        dialog.showModal();
+      } catch {
+        cleanup();
+        document.body.classList.remove('modal-is-open');
+        resolve(this.fallbackConfirm({ message }));
+        return;
+      }
+
+      window.requestAnimationFrame(() => {
+        if (focusTarget === 'cancel') {
+          cancelButton.focus();
+          return;
+        }
+        confirmButton.focus();
+      });
+    });
+  }
+
+  confirm(options = {}) {
+    return this.enqueue(() => this.run(options));
+  }
+}
+
+export const confirmDialog = new ConfirmDialogController();
+export { inferVariant as inferConfirmVariant, normalizeVariant as normalizeConfirmVariant, normalizeFocus as normalizeConfirmFocus, requestSubmitWithFallback };
diff --git a/web/js/core/app-detail-page-factory.js b/web/js/core/app-detail-page-factory.js
index ca874e8..9874d45 100644
--- a/web/js/core/app-detail-page-factory.js
+++ b/web/js/core/app-detail-page-factory.js
@@ -1,4 +1,5 @@
 import { initDetailActionPolicy } from './app-details-action-policy.js';
+import { confirmDialog } from './app-confirm-dialog.js';
 
 const DEFAULT_UNSAVED_MESSAGE = 'You have unsaved changes. Leave without saving?';
 
@@ -434,17 +435,25 @@ export function initStandardDetailPage(options = {}) {
     return '';
   };
 
-  const onBackLinkClick = (event) => {
+  const onBackLinkClick = async (event) => {
     if (!shouldWarn()) {
       return;
     }
-    const leaveWithoutSaving = window.confirm(unsavedMessage);
+    event.preventDefault();
+    const leaveWithoutSaving = await confirmDialog.confirm({
+      title: unsavedIndicatorLabel,
+      message: unsavedMessage,
+      variant: 'warning',
+      focus: 'cancel'
+    });
     if (!leaveWithoutSaving) {
-      event.preventDefault();
       return;
     }
     // Avoid a second native beforeunload prompt after explicit confirmation.
     allowNextUnload = true;
+    if (backLink instanceof HTMLAnchorElement) {
+      window.location.href = backLink.href;
+    }
   };
 
   const onFormStateChange = () => {
diff --git a/web/js/core/app-details-action-policy.js b/web/js/core/app-details-action-policy.js
index c666b40..4553bd3 100644
--- a/web/js/core/app-details-action-policy.js
+++ b/web/js/core/app-details-action-policy.js
@@ -1,3 +1,5 @@
+import { confirmDialog, requestSubmitWithFallback } from './app-confirm-dialog.js';
+
 const escapeAttr = (value) => {
   const raw = String(value || '');
   if (typeof CSS !== 'undefined' && CSS && typeof CSS.escape === 'function') {
@@ -111,6 +113,36 @@ const readConfirmMessage = (submitter, form) => {
   return String(form.getAttribute('data-detail-confirm-message') || '').trim();
 };
 
+const readConfirmOption = (submitter, form, detailSuffix, genericSuffix = detailSuffix) => {
+  const detailAttr = `data-detail-confirm-${detailSuffix}`;
+  const genericAttr = `data-confirm-${genericSuffix}`;
+  return String(
+    submitter?.getAttribute(detailAttr)
+    || submitter?.getAttribute(genericAttr)
+    || form.getAttribute(detailAttr)
+    || form.getAttribute(genericAttr)
+    || ''
+  ).trim();
+};
+
+const readActionKind = (submitter, form) => String(
+  submitter?.getAttribute('data-detail-action-kind')
+  || form.getAttribute('data-detail-action-kind')
+  || ''
+).trim();
+
+const buildConfirmOptions = (message, submitter, form) => ({
+  message,
+  title: readConfirmOption(submitter, form, 'title'),
+  confirmLabel: readConfirmOption(submitter, form, 'confirm-label'),
+  cancelLabel: readConfirmOption(submitter, form, 'cancel-label'),
+  variant: readConfirmOption(submitter, form, 'variant'),
+  focus: readConfirmOption(submitter, form, 'focus'),
+  describedBy: readConfirmOption(submitter, form, 'describedby')
+    || readConfirmOption(submitter, form, 'described-by'),
+  actionKind: readActionKind(submitter, form)
+});
+
 const readSubmitLockMode = (submitter, form) => normalizeSubmitLock(
   submitter?.getAttribute('data-detail-submit-lock')
   || form.getAttribute('data-detail-submit-lock')
@@ -153,6 +185,7 @@ export function initDetailActionPolicy(options = {}) {
 
   const submittingForms = new Set();
   const submitterByForm = new Map();
+  const confirmedSubmitterByForm = new WeakMap();
 
   const onClickCapture = (event) => {
     const target = event.target instanceof HTMLElement
@@ -181,10 +214,26 @@ export function initDetailActionPolicy(options = {}) {
       return;
     }
 
-    const confirmMessage = readConfirmMessage(submitter, form);
-    if (confirmMessage !== '' && !window.confirm(confirmMessage)) {
-      event.preventDefault();
-      return;
+    const bypassSubmitter = confirmedSubmitterByForm.get(form);
+    if (bypassSubmitter && (bypassSubmitter === true || bypassSubmitter === submitter || bypassSubmitter === null)) {
+      confirmedSubmitterByForm.delete(form);
+    } else {
+      const confirmMessage = readConfirmMessage(submitter, form);
+      if (confirmMessage !== '') {
+        event.preventDefault();
+        event.stopPropagation();
+
+        void confirmDialog.confirm(buildConfirmOptions(confirmMessage, submitter, form))
+          .then((approved) => {
+            if (!approved || !document.contains(form)) {
+              return;
+            }
+            const submitterForSubmit = submitter && belongsToForm(submitter, form) ? submitter : null;
+            confirmedSubmitterByForm.set(form, submitterForSubmit || true);
+            requestSubmitWithFallback(form, submitterForSubmit);
+          });
+        return;
+      }
     }
 
     if (lockMode === 'none') {
diff --git a/web/js/core/app-dom.js b/web/js/core/app-dom.js
index 98691ed..ea8244c 100644
--- a/web/js/core/app-dom.js
+++ b/web/js/core/app-dom.js
@@ -1,10 +1,37 @@
+import { telemetry } from './app-telemetry.js';
+
 const warned = new Set();
 
 export const warnOnce = (code, message, details = {}) => {
-  const key = `${code}:${message}`;
+  const normalizedCode = String(code ?? '').trim() || 'UI_WARN';
+  const normalizedMessage = String(message ?? '').trim();
+  const key = `${normalizedCode}:${normalizedMessage}`;
   if (warned.has(key)) {return;}
   warned.add(key);
-  console.warn(`[${code}] ${message}`, details);
+  console.warn(`[${normalizedCode}] ${normalizedMessage}`, details);
+
+  const warnMeta = {
+    source: 'warn_once',
+    code: normalizedCode,
+  };
+
+  if (details && typeof details === 'object' && !Array.isArray(details)) {
+    if (typeof details.module === 'string' && details.module.trim() !== '') {
+      warnMeta.module = details.module.trim();
+    }
+    if (typeof details.component === 'string' && details.component.trim() !== '') {
+      warnMeta.component = details.component.trim();
+    }
+    if (typeof details.feature === 'string' && details.feature.trim() !== '') {
+      warnMeta.feature = details.feature.trim();
+    }
+  }
+
+  telemetry.capture('frontend.warn_once', {
+    severity: 'warning',
+    message: `[${normalizedCode}] ${normalizedMessage}`,
+    meta: warnMeta,
+  });
 };
 
 export const requireEl = (selector, details = {}) => {
diff --git a/web/js/core/app-grid-factory.js b/web/js/core/app-grid-factory.js
index 89d4671..3ee9f8c 100644
--- a/web/js/core/app-grid-factory.js
+++ b/web/js/core/app-grid-factory.js
@@ -1,4 +1,5 @@
 import { warnOnce } from './app-dom.js';
+import { confirmDialog } from './app-confirm-dialog.js';
 import { gridFiltersFromSchema } from '../pages/app-list-utils.js';
 import { initListFilterExperience } from '../pages/app-list-filter-experience.js';
 import { buildChipsFromMeta, removeChipFromMetaState, clearMetaState } from '../pages/app-list-filter-state.js';
@@ -58,6 +59,42 @@ const escapeHtmlAttr = (value) => String(value ?? '')
   .replaceAll('>', '&gt;')
   .replaceAll('"', '&quot;');
 
+const normalizeColumnIdPart = (value) => String(value ?? '')
+  .trim()
+  .toLowerCase()
+  .replaceAll(/[^a-z0-9]+/g, '_')
+  .replaceAll(/^_+|_+$/g, '');
+
+const uniqueColumnId = (candidate, usedIds, fallbackPrefix = 'col') => {
+  const base = normalizeColumnIdPart(candidate) || fallbackPrefix;
+  let next = base;
+  let counter = 2;
+  while (usedIds.has(next)) {
+    next = `${base}_${counter}`;
+    counter += 1;
+  }
+  usedIds.add(next);
+  return next;
+};
+
+const normalizeGridColumns = (columns, sortColumns) => {
+  const source = Array.isArray(columns) ? columns : [];
+  const sortKeys = Array.isArray(sortColumns) ? sortColumns : [];
+  const usedIds = new Set();
+
+  return source.map((column, index) => {
+    const baseColumn = (column && typeof column === 'object' && !Array.isArray(column))
+      ? column
+      : { name: String(column ?? '') };
+    const explicitId = typeof baseColumn.id === 'string' ? baseColumn.id : '';
+    const sortKey = typeof sortKeys[index] === 'string' ? sortKeys[index] : '';
+    const label = typeof baseColumn.name === 'string' ? baseColumn.name : '';
+    const fallback = `col_${index + 1}`;
+    const id = uniqueColumnId(explicitId || sortKey || label || fallback, usedIds, fallback);
+    return { ...baseColumn, id };
+  });
+};
+
 export function createServerGrid(options) {
   const {
     container,
@@ -99,6 +136,8 @@ export function createServerGrid(options) {
     return null;
   }
 
+  const normalizedColumns = normalizeGridColumns(columns, sortColumns);
+
   const params = new URLSearchParams(window.location.search);
   const urlStateConfig = {
     pageParam: 'page',
@@ -428,6 +467,7 @@ export function createServerGrid(options) {
   };
 
   const explicitActionConfig = actions && actions.enabled ? {
+    id: String(actions.id || 'row_actions').trim() || 'row_actions',
     label: actions.label || 'Actions',
     index: Number.isInteger(actions.index) ? actions.index : null,
     items: Array.isArray(actions.items) ? actions.items : [],
@@ -436,6 +476,7 @@ export function createServerGrid(options) {
     onAction: typeof actions.onAction === 'function' ? actions.onAction : null
   } : null;
   const rowOpenActionConfig = !explicitActionConfig && showRowActionButton ? {
+    id: 'row_actions',
     label: gridjsLib.html(
       `<span class="app-grid-actions-header" data-tooltip="${escapeHtmlAttr(rowEnterHint)}" data-tooltip-pos="top" aria-label="${escapeHtmlAttr(rowEnterHint)}">${escapeHtmlAttr(rowActionColumnLabel)}</span>`
     ),
@@ -470,9 +511,25 @@ export function createServerGrid(options) {
     selectAllEnabled: selection.selectAllEnabled !== false
   } : null;
 
+  if (selectionConfig) {
+    const usedColumnIds = new Set(
+      normalizedColumns
+        .map((column) => (column && typeof column === 'object' ? String(column.id || '').trim() : ''))
+        .filter(Boolean)
+    );
+    selectionConfig.id = uniqueColumnId(selectionConfig.id, usedColumnIds, 'select_row');
+  }
+
   const insertActionColumn = (cols) => {
     if (!actionConfig) {return cols;}
+    const usedColumnIds = new Set(
+      cols
+        .map((column) => (column && typeof column === 'object' ? String(column.id || '').trim() : ''))
+        .filter(Boolean)
+    );
+    const actionColumnId = uniqueColumnId(actionConfig.id, usedColumnIds, 'row_actions');
     const actionColumn = {
+      id: actionColumnId,
       name: actionConfig.label,
       sort: false,
       formatter: (_cell, row) => {
@@ -642,7 +699,7 @@ export function createServerGrid(options) {
   }
 
   const grid = new gridjsLib.Grid({
-    columns: insertActionColumn(insertSelectionColumn(columns)),
+    columns: insertActionColumn(insertSelectionColumn(normalizedColumns)),
     server: serverConfig,
     search: false,
     sort: sortConfig,
@@ -890,8 +947,18 @@ export function createServerGrid(options) {
       const confirmText = typeof actionItem.confirm === 'function'
         ? actionItem.confirm({ row: rowData, id })
         : actionItem.confirm;
-      if (confirmText && !window.confirm(confirmText)) {
-        return;
+      if (confirmText) {
+        const confirmOptionsFromItem = typeof actionItem.confirmOptions === 'function'
+          ? (actionItem.confirmOptions({ row: rowData, id, action: actionKey }) || {})
+          : (actionItem.confirmOptions || {});
+        const approved = await confirmDialog.confirm({
+          ...confirmOptionsFromItem,
+          message: String(confirmText),
+          actionKind: String(confirmOptionsFromItem.actionKind || actionKey || '')
+        });
+        if (!approved) {
+          return;
+        }
       }
       if (actionItem.type === 'link') {
         const href = typeof actionItem.href === 'function'
diff --git a/web/js/core/app-telemetry.js b/web/js/core/app-telemetry.js
new file mode 100644
index 0000000..f6815ea
--- /dev/null
+++ b/web/js/core/app-telemetry.js
@@ -0,0 +1,565 @@
+const DEFAULT_SAMPLE_RATE = 0.2;
+const DEFAULT_DEDUPE_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_EVENTS_PER_MINUTE = 20;
+const MAX_MESSAGE_LENGTH = 280;
+const MAX_FINGERPRINT_LENGTH = 96;
+const MAX_META_ENTRIES = 12;
+const MAX_META_VALUE_LENGTH = 140;
+const MAX_META_JSON_LENGTH = 1800;
+
+const EVENT_KEY_TO_TYPE = Object.freeze({
+  warn_once: 'frontend.warn_once',
+  ajax_error: 'frontend.ajax_error',
+});
+
+const EVENT_TYPE_TO_KEY = Object.freeze({
+  'frontend.warn_once': 'warn_once',
+  'frontend.ajax_error': 'ajax_error',
+});
+
+const DEFAULT_ALLOWED_EVENT_KEYS = Object.freeze(['warn_once', 'ajax_error']);
+const DEFAULT_ALLOWED_EVENT_TYPES = new Set(DEFAULT_ALLOWED_EVENT_KEYS.map((key) => EVENT_KEY_TO_TYPE[key]));
+
+const AJAX_ERROR_TYPE = EVENT_KEY_TO_TYPE.ajax_error;
+
+const ALLOWED_META_KEYS = new Set([
+  'action',
+  'code',
+  'component',
+  'error_code',
+  'feature',
+  'http_method',
+  'http_status',
+  'location',
+  'module',
+  'page_request_id',
+  'request_path',
+  'source',
+  'status_text',
+]);
+
+const seenFingerprints = new Map();
+let fetchHookInstalled = false;
+let clientRateWindowStartMs = 0;
+let clientRateWindowCount = 0;
+
+const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+const clampRate = (value, fallback = DEFAULT_SAMPLE_RATE) => {
+  const numeric = Number.parseFloat(String(value ?? ''));
+  if (!Number.isFinite(numeric)) {
+    return fallback;
+  }
+  if (numeric < 0) {return 0;}
+  if (numeric > 1) {return 1;}
+  return numeric;
+};
+
+const clampPositiveInt = (value, fallback) => {
+  const numeric = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(numeric) || numeric < 1) {
+    return fallback;
+  }
+  return numeric;
+};
+
+const normalizeEventType = (eventType) => {
+  const normalized = normalizeWhitespace(eventType).toLowerCase();
+  if (normalized in EVENT_KEY_TO_TYPE) {
+    return EVENT_KEY_TO_TYPE[normalized];
+  }
+  if (normalized in EVENT_TYPE_TO_KEY) {
+    return normalized;
+  }
+  return '';
+};
+
+const normalizeSeverity = (severity, eventType) => {
+  const normalized = normalizeWhitespace(severity).toLowerCase();
+  if (normalized === 'error' || normalized === 'warning' || normalized === 'info') {
+    return normalized;
+  }
+  return eventType === AJAX_ERROR_TYPE ? 'error' : 'warning';
+};
+
+const normalizeRoute = (value) => {
+  const raw = normalizeWhitespace(value);
+  if (raw === '') {
+    return normalizeWhitespace(window.location.pathname || '/') || '/';
+  }
+  try {
+    const url = new URL(raw, window.location.href);
+    if (url.origin !== window.location.origin) {
+      return '';
+    }
+    return normalizeWhitespace(url.pathname || '/') || '/';
+  } catch {
+    const stripped = raw.split('?')[0].split('#')[0];
+    return normalizeWhitespace(stripped || '/') || '/';
+  }
+};
+
+const normalizeMessage = (value) => {
+  const normalized = normalizeWhitespace(value);
+  if (normalized === '') {
+    return '';
+  }
+  return normalized.slice(0, MAX_MESSAGE_LENGTH);
+};
+
+const normalizeFingerprint = (value) => {
+  const normalized = normalizeWhitespace(value).toLowerCase();
+  if (normalized === '') {
+    return '';
+  }
+  const safe = normalized.replace(/[^a-z0-9:_-]/g, '');
+  return safe.slice(0, MAX_FINGERPRINT_LENGTH);
+};
+
+const hashString = (value) => {
+  let hash = 2166136261;
+  const source = String(value ?? '');
+  for (let index = 0; index < source.length; index += 1) {
+    hash ^= source.charCodeAt(index);
+    hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};
+
+const buildFingerprint = (eventType, message, route) => normalizeFingerprint(
+  `v1_${hashString(`${eventType}|${route}|${message}`)}`
+);
+
+const normalizeOccurredAt = (value) => {
+  const raw = normalizeWhitespace(value);
+  if (raw !== '') {
+    const timestamp = Date.parse(raw);
+    if (Number.isFinite(timestamp)) {
+      return new Date(timestamp).toISOString();
+    }
+  }
+  return new Date().toISOString();
+};
+
+const normalizeMetaValue = (value) => {
+  if (typeof value === 'boolean') {
+    return value ? '1' : '0';
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? String(value) : '';
+  }
+  if (typeof value === 'string') {
+    return normalizeWhitespace(value).slice(0, MAX_META_VALUE_LENGTH);
+  }
+  if (value instanceof Error) {
+    return normalizeWhitespace(value.name || 'Error').slice(0, MAX_META_VALUE_LENGTH);
+  }
+  if (value === null || value === undefined) {
+    return '';
+  }
+  return normalizeWhitespace(String(value)).slice(0, MAX_META_VALUE_LENGTH);
+};
+
+const normalizeMeta = (meta) => {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) {
+    return {};
+  }
+
+  const normalized = {};
+  let index = 0;
+
+  Object.entries(meta).forEach(([rawKey, rawValue]) => {
+    if (index >= MAX_META_ENTRIES) {
+      return;
+    }
+
+    const key = normalizeWhitespace(rawKey).toLowerCase();
+    if (key === '' || !ALLOWED_META_KEYS.has(key)) {
+      return;
+    }
+
+    const value = normalizeMetaValue(rawValue);
+    if (value === '') {
+      return;
+    }
+
+    normalized[key] = value;
+    index += 1;
+  });
+
+  return normalized;
+};
+
+const normalizeAllowedEventKeys = (value) => {
+  const keys = new Set();
+  const raw = Array.isArray(value)
+    ? value
+    : String(value ?? '')
+      .split(/[,\n]/g)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+
+  raw.forEach((entry) => {
+    const key = String(entry).trim().toLowerCase();
+    if (key in EVENT_KEY_TO_TYPE) {
+      keys.add(key);
+    } else if (key in EVENT_TYPE_TO_KEY) {
+      keys.add(EVENT_TYPE_TO_KEY[key]);
+    }
+  });
+
+  if (keys.size === 0) {
+    DEFAULT_ALLOWED_EVENT_KEYS.forEach((key) => keys.add(key));
+  }
+
+  return keys;
+};
+
+const resolveConfig = () => {
+  const root = document.documentElement;
+  if (!root) {
+    return {
+      enabled: false,
+      endpoint: '',
+      csrfKey: '',
+      csrfToken: '',
+      sampleRate: DEFAULT_SAMPLE_RATE,
+      maxEventsPerMinute: DEFAULT_MAX_EVENTS_PER_MINUTE,
+      allowedEventTypes: DEFAULT_ALLOWED_EVENT_TYPES,
+    };
+  }
+
+  const enabledRaw = normalizeWhitespace(root.dataset.telemetryEnabled || '');
+  const enabled = enabledRaw !== '' && ['1', 'true', 'yes', 'on'].includes(enabledRaw.toLowerCase());
+
+  const allowedEventKeys = normalizeAllowedEventKeys(root.dataset.telemetryAllowedEvents || '');
+  const allowedEventTypes = new Set();
+  allowedEventKeys.forEach((key) => {
+    const eventType = EVENT_KEY_TO_TYPE[key];
+    if (eventType) {
+      allowedEventTypes.add(eventType);
+    }
+  });
+
+  return {
+    enabled,
+    endpoint: normalizeWhitespace(root.dataset.telemetryUrl || ''),
+    csrfKey: normalizeWhitespace(root.dataset.telemetryCsrfKey || ''),
+    csrfToken: normalizeWhitespace(root.dataset.telemetryCsrfToken || ''),
+    sampleRate: clampRate(root.dataset.telemetrySampleRate || DEFAULT_SAMPLE_RATE, DEFAULT_SAMPLE_RATE),
+    maxEventsPerMinute: clampPositiveInt(
+      root.dataset.telemetryMaxEventsPerMinute || DEFAULT_MAX_EVENTS_PER_MINUTE,
+      DEFAULT_MAX_EVENTS_PER_MINUTE
+    ),
+    allowedEventTypes: allowedEventTypes.size > 0 ? allowedEventTypes : DEFAULT_ALLOWED_EVENT_TYPES,
+  };
+};
+
+const shouldSample = (rate) => {
+  if (rate <= 0) {return false;}
+  if (rate >= 1) {return true;}
+  return Math.random() < rate;
+};
+
+const trimSeenFingerprints = (now = Date.now()) => {
+  seenFingerprints.forEach((expiresAt, key) => {
+    if (expiresAt <= now) {
+      seenFingerprints.delete(key);
+    }
+  });
+};
+
+const isDuplicateFingerprint = (fingerprint, ttlMs, now = Date.now()) => {
+  trimSeenFingerprints(now);
+  const expiresAt = seenFingerprints.get(fingerprint) || 0;
+  if (expiresAt > now) {
+    return true;
+  }
+  seenFingerprints.set(fingerprint, now + ttlMs);
+  return false;
+};
+
+const hasClientRateBudget = (maxEventsPerMinute, nowMs = Date.now()) => {
+  const limit = clampPositiveInt(maxEventsPerMinute, DEFAULT_MAX_EVENTS_PER_MINUTE);
+  const windowMs = 60 * 1000;
+  if (clientRateWindowStartMs <= 0 || (nowMs - clientRateWindowStartMs) >= windowMs) {
+    clientRateWindowStartMs = nowMs;
+    clientRateWindowCount = 0;
+  }
+
+  if (clientRateWindowCount >= limit) {
+    return false;
+  }
+
+  clientRateWindowCount += 1;
+  return true;
+};
+
+const toUrlSearchParams = (payload, config) => {
+  const body = new URLSearchParams();
+  body.set('event_type', payload.eventType);
+  body.set('severity', payload.severity);
+  body.set('message', payload.message);
+  body.set('fingerprint', payload.fingerprint);
+  body.set('occurred_at', payload.occurredAt);
+
+  const metaJson = JSON.stringify(payload.meta);
+  if (metaJson && metaJson.length <= MAX_META_JSON_LENGTH) {
+    body.set('meta', metaJson);
+  }
+
+  body.set(config.csrfKey, config.csrfToken);
+  return body;
+};
+
+const sendPayload = (payload, config) => {
+  if (!config.endpoint || !config.csrfKey || !config.csrfToken) {
+    return false;
+  }
+
+  const body = toUrlSearchParams(payload, config);
+
+  try {
+    if (navigator.sendBeacon && navigator.sendBeacon(config.endpoint, body)) {
+      return true;
+    }
+  } catch {
+    // continue with fetch fallback.
+  }
+
+  try {
+    void fetch(config.endpoint, {
+      method: 'POST',
+      credentials: 'same-origin',
+      keepalive: true,
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
+        'Accept': 'application/json',
+        'X-Requested-With': 'fetch',
+        'X-Telemetry-Request': '1',
+      },
+      body,
+    }).catch(() => {});
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const headerValue = (headers, key) => {
+  if (!headers) {
+    return '';
+  }
+
+  if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+    return normalizeWhitespace(headers.get(key) || '');
+  }
+
+  if (Array.isArray(headers)) {
+    const tuple = headers.find((entry) => Array.isArray(entry) && String(entry[0] || '').toLowerCase() === key.toLowerCase());
+    return tuple ? normalizeWhitespace(tuple[1] || '') : '';
+  }
+
+  if (typeof headers === 'object') {
+    const direct = headers[key] ?? headers[key.toLowerCase()] ?? headers[key.toUpperCase()];
+    return normalizeWhitespace(direct || '');
+  }
+
+  return '';
+};
+
+const fetchInputUrl = (input) => {
+  if (typeof input === 'string') {
+    return input;
+  }
+  if (input instanceof URL) {
+    return input.toString();
+  }
+  if (typeof Request !== 'undefined' && input instanceof Request) {
+    return input.url;
+  }
+  return '';
+};
+
+const fetchInputMethod = (input, init) => {
+  const initMethod = normalizeWhitespace(init?.method || '').toUpperCase();
+  if (initMethod !== '') {
+    return initMethod;
+  }
+  if (typeof Request !== 'undefined' && input instanceof Request) {
+    const requestMethod = normalizeWhitespace(input.method || '').toUpperCase();
+    if (requestMethod !== '') {
+      return requestMethod;
+    }
+  }
+  return 'GET';
+};
+
+const isTelemetryFetch = (input, init, telemetryPath) => {
+  if (telemetryPath === '') {
+    return false;
+  }
+
+  const requestHeaders = init?.headers;
+  const inputHeaders = typeof Request !== 'undefined' && input instanceof Request ? input.headers : null;
+  const marker = headerValue(requestHeaders, 'X-Telemetry-Request') || headerValue(inputHeaders, 'X-Telemetry-Request');
+  if (marker === '1') {
+    return true;
+  }
+
+  const requestPath = normalizeRoute(fetchInputUrl(input));
+  return requestPath !== '' && requestPath === telemetryPath;
+};
+
+const shouldTrackFetch = (input, init, config) => {
+  if (!config.enabled || !config.allowedEventTypes.has(AJAX_ERROR_TYPE)) {
+    return false;
+  }
+
+  const rawUrl = fetchInputUrl(input);
+  if (rawUrl === '') {
+    return false;
+  }
+
+  const path = normalizeRoute(rawUrl);
+  if (path === '') {
+    return false;
+  }
+
+  const telemetryPath = normalizeRoute(config.endpoint);
+  if (isTelemetryFetch(input, init, telemetryPath)) {
+    return false;
+  }
+
+  return true;
+};
+
+export const telemetry = {
+  capture(eventType, payload = {}, options = {}) {
+    if (typeof document === 'undefined' || typeof window === 'undefined') {
+      return false;
+    }
+
+    const normalizedEventType = normalizeEventType(eventType);
+    if (normalizedEventType === '') {
+      return false;
+    }
+
+    const config = resolveConfig();
+    if (!config.enabled || !config.allowedEventTypes.has(normalizedEventType)) {
+      return false;
+    }
+
+    const message = normalizeMessage(payload.message || '');
+    if (message === '') {
+      return false;
+    }
+
+    const route = normalizeRoute(payload.route || window.location.pathname || '/');
+    const fingerprint = normalizeFingerprint(payload.fingerprint || '')
+      || buildFingerprint(normalizedEventType, message, route);
+    if (fingerprint === '') {
+      return false;
+    }
+
+    const dedupeTtlMs = Math.max(0, Number.parseInt(String(options.dedupeTtlMs ?? DEFAULT_DEDUPE_TTL_MS), 10) || 0);
+    if (!options.skipDedupe && dedupeTtlMs > 0 && isDuplicateFingerprint(fingerprint, dedupeTtlMs)) {
+      return false;
+    }
+
+    const sampleRate = clampRate(
+      options.sampleRate !== undefined ? options.sampleRate : config.sampleRate,
+      config.sampleRate
+    );
+    if (!shouldSample(sampleRate)) {
+      return false;
+    }
+
+    const maxEventsPerMinute = clampPositiveInt(
+      options.maxEventsPerMinute !== undefined ? options.maxEventsPerMinute : config.maxEventsPerMinute,
+      config.maxEventsPerMinute
+    );
+    if (!options.skipClientRateLimit && !hasClientRateBudget(maxEventsPerMinute)) {
+      return false;
+    }
+
+    const meta = normalizeMeta(payload.meta || {});
+    if (route !== '') {
+      meta.location = route;
+    }
+    const pageRequestId = normalizeWhitespace(document.documentElement?.dataset.requestId || '');
+    if (pageRequestId !== '') {
+      meta.page_request_id = pageRequestId.slice(0, 36);
+    }
+
+    return sendPayload({
+      eventType: normalizedEventType,
+      severity: normalizeSeverity(payload.severity, normalizedEventType),
+      message,
+      fingerprint,
+      meta,
+      occurredAt: normalizeOccurredAt(payload.occurredAt),
+    }, config);
+  },
+
+  installGlobalFetchHook() {
+    if (fetchHookInstalled || typeof window === 'undefined' || typeof window.fetch !== 'function') {
+      return;
+    }
+
+    const originalFetch = window.fetch.bind(window);
+    window.fetch = (input, init) => {
+      const config = resolveConfig();
+      if (!shouldTrackFetch(input, init, config)) {
+        return originalFetch(input, init);
+      }
+
+      const method = fetchInputMethod(input, init);
+      const requestPath = normalizeRoute(fetchInputUrl(input));
+
+      return originalFetch(input, init)
+        .then((response) => {
+          const shouldTrackStatus = response.status >= 500 || response.status === 429;
+          if (!response.ok && shouldTrackStatus) {
+            telemetry.capture(AJAX_ERROR_TYPE, {
+              severity: response.status >= 500 ? 'error' : 'warning',
+              message: `AJAX request failed (${response.status}) ${method} ${requestPath || '/'}`,
+              meta: {
+                source: 'fetch',
+                module: 'global-fetch',
+                http_method: method,
+                http_status: response.status,
+                status_text: response.statusText || '',
+                request_path: requestPath || '/',
+              },
+            });
+          }
+          return response;
+        })
+        .catch((error) => {
+          if (!(error instanceof Error && error.name === 'AbortError')) {
+            telemetry.capture(AJAX_ERROR_TYPE, {
+              severity: 'error',
+              message: `AJAX network error ${method} ${requestPath || '/'}`,
+              meta: {
+                source: 'fetch',
+                module: 'global-fetch',
+                http_method: method,
+                request_path: requestPath || '/',
+                error_code: error instanceof Error ? error.name : 'NetworkError',
+              },
+            });
+          }
+          throw error;
+        });
+    };
+
+    fetchHookInstalled = true;
+  },
+};
+
+if (typeof window !== 'undefined') {
+  telemetry.installGlobalFetchHook();
+}
+
+export { DEFAULT_DEDUPE_TTL_MS };
diff --git a/web/js/pages/address-book-index.js b/web/js/pages/address-book-index.js
index 16bc08d..514db64 100644
--- a/web/js/pages/address-book-index.js
+++ b/web/js/pages/address-book-index.js
@@ -2,6 +2,7 @@ import { initMultiSelect } from '../components/app-multiselect-init.js';
 import { initMultiSelectCascade } from '../components/app-multiselect-cascade.js';
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase, escapeHtml, buildBadgeList, gridFilterMultiCsv, gridFilterText } from './app-list-utils.js';
 
 const config = readPageConfig('address-book-index');
@@ -125,7 +126,7 @@ if (config) {
   });
 
   if (!gridConfig || !gridConfig.grid) {
-    console.warn('Address book grid init failed');
+    warnOnce('UI_INIT_FAIL', 'Address book grid init failed', { module: 'address-book-index', component: 'grid' });
   }
 
   initMultiSelect().then(() => {
diff --git a/web/js/pages/admin-api-audit-index.js b/web/js/pages/admin-api-audit-index.js
index d50c930..1d5563c 100644
--- a/web/js/pages/admin-api-audit-index.js
+++ b/web/js/pages/admin-api-audit-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-api-audit-index');
@@ -138,7 +139,7 @@ if (config) {
       },
     });
     if (!gridConfig || !gridConfig.grid) {
-      console.warn('API audit grid init failed');
+      warnOnce('UI_INIT_FAIL', 'API audit grid init failed', { module: 'admin-api-audit-index', component: 'grid' });
       return null;
     }
     return gridConfig;
diff --git a/web/js/pages/admin-departments-index.js b/web/js/pages/admin-departments-index.js
index 38401ac..849c9b2 100644
--- a/web/js/pages/admin-departments-index.js
+++ b/web/js/pages/admin-departments-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { badgeHtml, getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-departments-index');
@@ -111,7 +112,7 @@ if (config) {
       },
     });
     if (!gridConfig || !gridConfig.grid) {
-      console.warn('Departments grid init failed');
+      warnOnce('UI_INIT_FAIL', 'Departments grid init failed', { module: 'admin-departments-index', component: 'grid' });
       return null;
     }
     return gridConfig;
diff --git a/web/js/pages/admin-import-audit-index.js b/web/js/pages/admin-import-audit-index.js
index 77dadd3..2bbf5cd 100644
--- a/web/js/pages/admin-import-audit-index.js
+++ b/web/js/pages/admin-import-audit-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-import-audit-index');
@@ -98,6 +99,6 @@ if (config) {
   });
 
   if (!gridConfig || !gridConfig.grid) {
-    console.warn('Import audit grid init failed');
+    warnOnce('UI_INIT_FAIL', 'Import audit grid init failed', { module: 'admin-import-audit-index', component: 'grid' });
   }
 }
diff --git a/web/js/pages/admin-mail-log-index.js b/web/js/pages/admin-mail-log-index.js
index 74312f0..39953b6 100644
--- a/web/js/pages/admin-mail-log-index.js
+++ b/web/js/pages/admin-mail-log-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-mail-log-index');
@@ -92,7 +93,7 @@ if (config) {
       },
     });
     if (!gridConfig || !gridConfig.grid) {
-      console.warn('Mail log grid init failed');
+      warnOnce('UI_INIT_FAIL', 'Mail log grid init failed', { module: 'admin-mail-log-index', component: 'grid' });
       return null;
     }
     return gridConfig;
diff --git a/web/js/pages/admin-permissions-index.js b/web/js/pages/admin-permissions-index.js
index a6c19d1..095431c 100644
--- a/web/js/pages/admin-permissions-index.js
+++ b/web/js/pages/admin-permissions-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { badgeHtml, getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-permissions-index');
@@ -67,7 +68,7 @@ if (config) {
       },
     });
     if (!gridConfig || !gridConfig.grid) {
-      console.warn('Permissions grid init failed');
+      warnOnce('UI_INIT_FAIL', 'Permissions grid init failed', { module: 'admin-permissions-index', component: 'grid' });
       return null;
     }
     return gridConfig;
diff --git a/web/js/pages/admin-roles-index.js b/web/js/pages/admin-roles-index.js
index 524fc48..7ee0b84 100644
--- a/web/js/pages/admin-roles-index.js
+++ b/web/js/pages/admin-roles-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { badgeHtml, getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-roles-index');
@@ -116,7 +117,7 @@ if (config) {
       },
     });
     if (!standardGridConfig || !standardGridConfig.grid) {
-      console.warn('Roles grid init failed');
+      warnOnce('UI_INIT_FAIL', 'Roles grid init failed', { module: 'admin-roles-index', component: 'grid' });
       return null;
     }
     return standardGridConfig;
diff --git a/web/js/pages/admin-scheduled-jobs-index.js b/web/js/pages/admin-scheduled-jobs-index.js
index 5e4e675..d27525d 100644
--- a/web/js/pages/admin-scheduled-jobs-index.js
+++ b/web/js/pages/admin-scheduled-jobs-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-scheduled-jobs-index');
@@ -91,6 +92,6 @@ if (config) {
   });
 
   if (!gridConfig || !gridConfig.grid) {
-    console.warn('Scheduled jobs grid init failed');
+    warnOnce('UI_INIT_FAIL', 'Scheduled jobs grid init failed', { module: 'admin-scheduled-jobs-index', component: 'grid' });
   }
 }
diff --git a/web/js/pages/admin-system-audit-index.js b/web/js/pages/admin-system-audit-index.js
index 2db1954..745b2b4 100644
--- a/web/js/pages/admin-system-audit-index.js
+++ b/web/js/pages/admin-system-audit-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-system-audit-index');
@@ -103,6 +104,6 @@ if (config) {
 
   const gridConfig = initSystemAuditGrid();
   if (!gridConfig || !gridConfig.grid) {
-    console.warn('System audit grid init failed');
+    warnOnce('UI_INIT_FAIL', 'System audit grid init failed', { module: 'admin-system-audit-index', component: 'grid' });
   }
 }
diff --git a/web/js/pages/admin-tenants-index.js b/web/js/pages/admin-tenants-index.js
index 13181b8..06ff328 100644
--- a/web/js/pages/admin-tenants-index.js
+++ b/web/js/pages/admin-tenants-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { badgeHtml, escapeHtml, getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-tenants-index');
@@ -160,7 +161,7 @@ if (config) {
       },
     });
     if (!gridConfig || !gridConfig.grid) {
-      console.warn('Tenants grid init failed');
+      warnOnce('UI_INIT_FAIL', 'Tenants grid init failed', { module: 'admin-tenants-index', component: 'grid' });
       return null;
     }
     return gridConfig;
diff --git a/web/js/pages/admin-user-lifecycle-audit-index.js b/web/js/pages/admin-user-lifecycle-audit-index.js
index 25d0ecf..594d4fc 100644
--- a/web/js/pages/admin-user-lifecycle-audit-index.js
+++ b/web/js/pages/admin-user-lifecycle-audit-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase } from './app-list-utils.js';
 
 const config = readPageConfig('admin-user-lifecycle-audit-index');
@@ -71,6 +72,6 @@ if (config) {
   });
 
   if (!gridConfig || !gridConfig.grid) {
-    console.warn('User lifecycle audit grid init failed');
+    warnOnce('UI_INIT_FAIL', 'User lifecycle audit grid init failed', { module: 'admin-user-lifecycle-audit-index', component: 'grid' });
   }
 }
diff --git a/web/js/pages/admin-users-index.js b/web/js/pages/admin-users-index.js
index 1f1208e..fcd491f 100644
--- a/web/js/pages/admin-users-index.js
+++ b/web/js/pages/admin-users-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { initUsersListPage } from './app-users-list.js';
 import { bindBulkVisibility } from '../components/app-bulk-selection.js';
 import { buildUrl, badgeHtml, getAppBase, escapeHtml, buildBadgeList } from './app-list-utils.js';
@@ -166,7 +167,7 @@ if (config) {
     });
 
     if (!gridConfig || !gridConfig.grid) {
-      console.warn('Users grid init failed');
+      warnOnce('UI_INIT_FAIL', 'Users grid init failed', { module: 'admin-users-index', component: 'grid' });
       return null;
     }
 
diff --git a/web/js/pages/app-users-list.js b/web/js/pages/app-users-list.js
index b50bfa2..5abc5fe 100644
--- a/web/js/pages/app-users-list.js
+++ b/web/js/pages/app-users-list.js
@@ -1,3 +1,6 @@
+import { confirmDialog } from '../core/app-confirm-dialog.js';
+import { warnOnce } from '../core/app-dom.js';
+
 export function initUsersListPage(options = {}) {
   const {
     gridConfig,
@@ -73,7 +76,10 @@ export function initUsersListPage(options = {}) {
         const validActions = ['activate', 'deactivate', 'delete', 'send-access', 'access-pdf'];
         if (!ids.length || !validActions.includes(action)) {
           if (action && !validActions.includes(action)) {
-            console.warn(`Unsupported users bulk action: ${action}`);
+            warnOnce('UI_ACTION_UNSUPPORTED', `Unsupported users bulk action: ${action}`, {
+              module: 'users-list',
+              component: 'bulk-action',
+            });
           }
           return;
         }
@@ -85,8 +91,14 @@ export function initUsersListPage(options = {}) {
           'access-pdf': labels.bulkAccessPdfConfirm
         };
         const confirmText = confirmTexts[action];
-        if (confirmText && !window.confirm(confirmText)) {
-          return;
+        if (confirmText) {
+          const approved = await confirmDialog.confirm({
+            message: confirmText,
+            actionKind: action,
+          });
+          if (!approved) {
+            return;
+          }
         }
 
         const downloadFormSelector = bulkDownloadForms?.[action];
diff --git a/web/js/pages/search-index.js b/web/js/pages/search-index.js
index 13609d7..b145b7d 100644
--- a/web/js/pages/search-index.js
+++ b/web/js/pages/search-index.js
@@ -1,5 +1,6 @@
 import { initStandardListPage } from '../core/app-grid-factory.js';
 import { readPageConfig } from '../core/app-page-config.js';
+import { warnOnce } from '../core/app-dom.js';
 import { getAppBase, escapeHtml } from './app-list-utils.js';
 
 const config = readPageConfig('search-index');
@@ -64,6 +65,6 @@ if (config) {
   });
 
   if (!gridConfig || !gridConfig.grid) {
-    console.warn('Search results grid init failed');
+    warnOnce('UI_INIT_FAIL', 'Search results grid init failed', { module: 'search-index', component: 'grid' });
   }
 }