From 98ef2d5109d5b3c495064f1111362db8d18c11de Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 17:54:44 +0000
Subject: [PATCH 1/7] docs: Initialize documentation pipeline [skip ci]

---
 .doc-pipeline-status.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .doc-pipeline-status.md

diff --git a/.doc-pipeline-status.md b/.doc-pipeline-status.md
new file mode 100644
index 000000000..53e79aa7d
--- /dev/null
+++ b/.doc-pipeline-status.md
@@ -0,0 +1,5 @@
+# Documentation Pipeline Started
+
+Run ID: doc-orchestrator-2026-06-04T17-54-24.845Z
+Status: In Progress
+Started: 2026-06-04 17:54:44 UTC

From a56d51f3a04ad53d7f4cb62e4e1a128c95708d40 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 17:54:50 +0000
Subject: [PATCH 2/7] chore(docs): Clean slate - remove all documentation (251
 files) [skip ci]

---
 docs/README.md                                | 109 ----
 docs/development/.gitignore                   |   7 -
 docs/development/README.md                    | 104 ----
 docs/development/architecture/README.md       | 199 --------
 docs/development/contributing/guidelines.md   | 264 ----------
 docs/development/security/README.md           | 292 -----------
 docs/development/setup/environment.md         | 209 --------
 docs/development/setup/local-development.md   | 218 --------
 docs/development/testing/README.md            | 295 -----------
 docs/diagrams/architecture/.gitignore         |   8 -
 docs/diagrams/architecture/README-2.mmd       |   7 -
 docs/diagrams/architecture/README-3.mmd       |   7 -
 docs/diagrams/architecture/README-4.mmd       |   6 -
 docs/diagrams/architecture/README-5.mmd       |   4 -
 docs/diagrams/architecture/README-6.mmd       |   5 -
 docs/diagrams/architecture/README-7.mmd       |  10 -
 docs/diagrams/architecture/README-8.mmd       |  19 -
 docs/diagrams/architecture/README.mmd         |  15 -
 .../api-contracts-and-pagination-2.mmd        |   5 -
 .../api-contracts-and-pagination-3.mmd        |   6 -
 .../api-contracts-and-pagination-4.mmd        |   3 -
 .../api-contracts-and-pagination-5.mmd        |   3 -
 .../api-contracts-and-pagination-6.mmd        |   6 -
 .../api-contracts-and-pagination-7.mmd        |   7 -
 .../api-contracts-and-pagination.mmd          |   6 -
 .../api-domain-filters-dtos-2.mmd             |   7 -
 .../api-domain-filters-dtos-3.mmd             |   6 -
 .../api-domain-filters-dtos-4.mmd             |   4 -
 .../api-domain-filters-dtos-5.mmd             |   4 -
 .../api-domain-filters-dtos-6.mmd             |   4 -
 .../architecture/api-domain-filters-dtos.mmd  |   6 -
 .../architecture/api-lib-core-services-2.mmd  |   4 -
 .../architecture/api-lib-core-services-3.mmd  |   4 -
 .../architecture/api-lib-core-services-4.mmd  |   5 -
 .../architecture/api-lib-core-services-5.mmd  |   5 -
 .../architecture/api-lib-core-services-6.mmd  |   3 -
 .../architecture/api-lib-core-services-7.mmd  |  13 -
 .../architecture/api-lib-core-services.mmd    |   7 -
 .../api-organization-mapping-2.mmd            |  10 -
 .../api-organization-mapping-3.mmd            |   6 -
 .../api-organization-mapping-4.mmd            |   8 -
 .../api-organization-mapping-5.mmd            |   6 -
 .../api-organization-mapping-6.mmd            |  11 -
 .../architecture/api-organization-mapping.mmd |  23 -
 ...api-service-core-config-and-security-2.mmd |   5 -
 ...api-service-core-config-and-security-3.mmd |   9 -
 ...api-service-core-config-and-security-4.mmd |   7 -
 ...api-service-core-config-and-security-5.mmd |   5 -
 ...api-service-core-config-and-security-6.mmd |  14 -
 .../api-service-core-config-and-security.mmd  |   7 -
 .../api-service-core-dataloaders-2.mmd        |   9 -
 .../api-service-core-dataloaders-3.mmd        |   4 -
 .../api-service-core-dataloaders-4.mmd        |   4 -
 .../api-service-core-dataloaders-5.mmd        |   4 -
 .../api-service-core-dataloaders-6.mmd        |  20 -
 .../api-service-core-dataloaders.mmd          |   7 -
 ...pi-service-core-graphql-datafetchers-2.mmd |   7 -
 ...pi-service-core-graphql-datafetchers-3.mmd |   8 -
 ...pi-service-core-graphql-datafetchers-4.mmd |   5 -
 ...pi-service-core-graphql-datafetchers-5.mmd |   8 -
 ...pi-service-core-graphql-datafetchers-6.mmd |   5 -
 ...pi-service-core-graphql-datafetchers-7.mmd |   4 -
 ...pi-service-core-graphql-datafetchers-8.mmd |   6 -
 .../api-service-core-graphql-datafetchers.mmd |  11 -
 .../api-service-core-graphql-dtos-2.mmd       |   7 -
 .../api-service-core-graphql-dtos-3.mmd       |   6 -
 .../api-service-core-graphql-dtos-4.mmd       |   6 -
 .../api-service-core-graphql-dtos-5.mmd       |  10 -
 .../api-service-core-graphql-dtos.mmd         |   7 -
 ...i-service-core-relay-type-resolution-2.mmd |  10 -
 ...i-service-core-relay-type-resolution-3.mmd |   9 -
 ...i-service-core-relay-type-resolution-4.mmd |   5 -
 ...i-service-core-relay-type-resolution-5.mmd |   3 -
 ...api-service-core-relay-type-resolution.mmd |  14 -
 .../api-service-core-rest-controllers-10.mmd  |   4 -
 .../api-service-core-rest-controllers-11.mmd  |   4 -
 .../api-service-core-rest-controllers-2.mmd   |   9 -
 .../api-service-core-rest-controllers-3.mmd   |   4 -
 .../api-service-core-rest-controllers-4.mmd   |   4 -
 .../api-service-core-rest-controllers-5.mmd   |   9 -
 .../api-service-core-rest-controllers-6.mmd   |   9 -
 .../api-service-core-rest-controllers-7.mmd   |   4 -
 .../api-service-core-rest-controllers-8.mmd   |   5 -
 .../api-service-core-rest-controllers-9.mmd   |   5 -
 .../api-service-core-rest-controllers.mmd     |  29 --
 ...ore-user-sso-services-and-processors-2.mmd |  11 -
 ...ore-user-sso-services-and-processors-3.mmd |  10 -
 ...ore-user-sso-services-and-processors-4.mmd |   8 -
 ...-core-user-sso-services-and-processors.mmd |  18 -
 ...rvice-core-auth-controllers-and-dtos-2.mmd |  11 -
 ...rvice-core-auth-controllers-and-dtos-3.mmd |   5 -
 ...rvice-core-auth-controllers-and-dtos-4.mmd |   4 -
 ...rvice-core-auth-controllers-and-dtos-5.mmd |   5 -
 ...service-core-auth-controllers-and-dtos.mmd |   6 -
 ...e-keys-and-authorization-persistence-2.mmd |   7 -
 ...e-keys-and-authorization-persistence-3.mmd |  11 -
 ...e-keys-and-authorization-persistence-4.mmd |   5 -
 ...e-keys-and-authorization-persistence-5.mmd |  11 -
 ...e-keys-and-authorization-persistence-6.mmd |  18 -
 ...ore-keys-and-authorization-persistence.mmd |  23 -
 ...ation-service-core-server-and-tenant-2.mmd |   4 -
 ...ation-service-core-server-and-tenant-3.mmd |   5 -
 ...ation-service-core-server-and-tenant-4.mmd |   5 -
 ...ation-service-core-server-and-tenant-5.mmd |   4 -
 ...ation-service-core-server-and-tenant-6.mmd |   8 -
 ...ation-service-core-server-and-tenant-7.mmd |   5 -
 ...ation-service-core-server-and-tenant-8.mmd |   9 -
 ...ization-service-core-server-and-tenant.mmd |  20 -
 ...tion-service-core-sso-flow-and-utils-2.mmd |  10 -
 ...tion-service-core-sso-flow-and-utils-3.mmd |   7 -
 ...tion-service-core-sso-flow-and-utils-4.mmd |   8 -
 ...tion-service-core-sso-flow-and-utils-5.mmd |   6 -
 ...tion-service-core-sso-flow-and-utils-6.mmd |  14 -
 ...zation-service-core-sso-flow-and-utils.mmd |  15 -
 .../data-kafka-configuration-and-retry-2.mmd  |   8 -
 .../data-kafka-configuration-and-retry-3.mmd  |   5 -
 .../data-kafka-configuration-and-retry-4.mmd  |   5 -
 .../data-kafka-configuration-and-retry-5.mmd  |  10 -
 .../data-kafka-configuration-and-retry-6.mmd  |   4 -
 .../data-kafka-configuration-and-retry.mmd    |   5 -
 .../data-mongo-base-repositories-2.mmd        |   4 -
 .../data-mongo-base-repositories-3.mmd        |   4 -
 .../data-mongo-base-repositories-4.mmd        |   4 -
 .../data-mongo-base-repositories-5.mmd        |   5 -
 .../data-mongo-base-repositories-6.mmd        |   6 -
 .../data-mongo-base-repositories-7.mmd        |   5 -
 .../data-mongo-base-repositories.mmd          |   7 -
 .../data-mongo-domain-model-2.mmd             |  22 -
 .../data-mongo-domain-model-3.mmd             |   6 -
 .../data-mongo-domain-model-4.mmd             |   6 -
 .../data-mongo-domain-model-5.mmd             |   3 -
 .../data-mongo-domain-model-6.mmd             |   4 -
 .../architecture/data-mongo-domain-model.mmd  |   9 -
 .../data-mongo-query-filters-2.mmd            |   5 -
 .../data-mongo-query-filters-3.mmd            |   4 -
 .../data-mongo-query-filters-4.mmd            |   9 -
 .../data-mongo-query-filters-5.mmd            |   4 -
 .../data-mongo-query-filters-6.mmd            |   5 -
 .../architecture/data-mongo-query-filters.mmd |   7 -
 .../data-mongo-reactive-repositories-2.mmd    |   9 -
 .../data-mongo-reactive-repositories-3.mmd    |   4 -
 .../data-mongo-reactive-repositories.mmd      |  12 -
 ...-sync-config-and-custom-repositories-2.mmd |   4 -
 ...-sync-config-and-custom-repositories-3.mmd |   4 -
 ...-sync-config-and-custom-repositories-4.mmd |   7 -
 ...-sync-config-and-custom-repositories-5.mmd |   4 -
 ...-sync-config-and-custom-repositories-6.mmd |   4 -
 ...-sync-config-and-custom-repositories-7.mmd |   4 -
 ...-sync-config-and-custom-repositories-8.mmd |   3 -
 ...-sync-config-and-custom-repositories-9.mmd |   5 -
 ...go-sync-config-and-custom-repositories.mmd |  10 -
 .../data-nats-notifications-2.mmd             |   8 -
 .../data-nats-notifications-3.mmd             |   6 -
 .../data-nats-notifications-4.mmd             |   9 -
 .../data-nats-notifications-5.mmd             |   5 -
 .../data-nats-notifications-6.mmd             |  13 -
 .../architecture/data-nats-notifications.mmd  |  13 -
 .../data-pinot-repositories-2.mmd             |   6 -
 .../data-pinot-repositories-3.mmd             |   9 -
 .../data-pinot-repositories-4.mmd             |   9 -
 .../data-pinot-repositories-5.mmd             |   4 -
 .../data-pinot-repositories-6.mmd             |   9 -
 .../architecture/data-pinot-repositories.mmd  |   5 -
 .../architecture/data-redis-cache-2.mmd       |   7 -
 .../architecture/data-redis-cache-3.mmd       |   7 -
 .../architecture/data-redis-cache.mmd         |  10 -
 .../external-api-service-core-2.mmd           |   7 -
 .../external-api-service-core-3.mmd           |   5 -
 .../external-api-service-core-4.mmd           |   4 -
 .../external-api-service-core-5.mmd           |   6 -
 .../external-api-service-core.mmd             |  16 -
 ...ay-service-core-security-and-routing-2.mmd |  10 -
 ...ay-service-core-security-and-routing-3.mmd |  10 -
 ...ay-service-core-security-and-routing-4.mmd |   8 -
 ...ay-service-core-security-and-routing-5.mmd |  12 -
 ...eway-service-core-security-and-routing.mmd |  20 -
 ...ice-core-initializers-and-schedulers-2.mmd |   4 -
 ...ice-core-initializers-and-schedulers-3.mmd |   5 -
 ...ice-core-initializers-and-schedulers-4.mmd |   5 -
 ...ice-core-initializers-and-schedulers-5.mmd |   6 -
 ...ice-core-initializers-and-schedulers-6.mmd |   5 -
 ...ice-core-initializers-and-schedulers-7.mmd |   3 -
 ...ice-core-initializers-and-schedulers-8.mmd |   6 -
 ...ice-core-initializers-and-schedulers-9.mmd |   6 -
 ...rvice-core-initializers-and-schedulers.mmd |  33 --
 docs/diagrams/architecture/processors-2.mmd   |   4 -
 docs/diagrams/architecture/processors-3.mmd   |   4 -
 docs/diagrams/architecture/processors-4.mmd   |   4 -
 docs/diagrams/architecture/processors-5.mmd   |   5 -
 docs/diagrams/architecture/processors-6.mmd   |   4 -
 docs/diagrams/architecture/processors-7.mmd   |   4 -
 docs/diagrams/architecture/processors-8.mmd   |   5 -
 docs/diagrams/architecture/processors.mmd     |   6 -
 .../security-core-and-oauth-bff-2.mmd         |  11 -
 .../security-core-and-oauth-bff-3.mmd         |   6 -
 .../security-core-and-oauth-bff-4.mmd         |   6 -
 .../security-core-and-oauth-bff-5.mmd         |  12 -
 .../security-core-and-oauth-bff-6.mmd         |   9 -
 .../security-core-and-oauth-bff-7.mmd         |   8 -
 .../security-core-and-oauth-bff-8.mmd         |   5 -
 .../security-core-and-oauth-bff.mmd           |   9 -
 docs/diagrams/architecture/services-2.mmd     |   8 -
 docs/diagrams/architecture/services-3.mmd     |   9 -
 docs/diagrams/architecture/services-4.mmd     |   8 -
 docs/diagrams/architecture/services-5.mmd     |   4 -
 docs/diagrams/architecture/services-6.mmd     |  11 -
 docs/diagrams/architecture/services-7.mmd     |   7 -
 docs/diagrams/architecture/services.mmd       |  26 -
 ...ream-service-core-kafka-and-handlers-2.mmd |  10 -
 ...ream-service-core-kafka-and-handlers-3.mmd |   6 -
 ...ream-service-core-kafka-and-handlers-4.mmd |   5 -
 ...ream-service-core-kafka-and-handlers-5.mmd |   5 -
 ...stream-service-core-kafka-and-handlers.mmd |  43 --
 docs/getting-started/.gitignore               |   7 -
 docs/getting-started/first-steps.md           | 178 -------
 docs/getting-started/introduction.md          | 136 -----
 docs/getting-started/prerequisites.md         | 163 ------
 docs/getting-started/quick-start.md           | 200 --------
 docs/reference/architecture/.gitignore        |   8 -
 docs/reference/architecture/README.md         | 447 -----------------
 .../api-contracts-and-pagination.md           | 329 ------------
 .../api-domain-filters-dtos.md                | 366 --------------
 .../api-lib-core-services.md                  | 298 -----------
 .../api-organization-mapping.md               | 322 ------------
 .../api-service-core-config-and-security.md   | 350 -------------
 .../api-service-core-dataloaders.md           | 343 -------------
 .../api-service-core-graphql-datafetchers.md  | 439 ----------------
 .../api-service-core-graphql-dtos.md          | 434 ----------------
 .../api-service-core-relay-type-resolution.md | 276 ----------
 .../api-service-core-rest-controllers.md      | 425 ----------------
 ...e-core-user-sso-services-and-processors.md | 183 -------
 .../processors.md                             | 303 -----------
 .../services.md                               | 302 -----------
 ...-service-core-auth-controllers-and-dtos.md | 393 ---------------
 ...core-keys-and-authorization-persistence.md | 355 -------------
 ...rization-service-core-server-and-tenant.md | 405 ---------------
 ...ization-service-core-sso-flow-and-utils.md | 359 -------------
 .../data-kafka-configuration-and-retry.md     | 380 --------------
 .../data-mongo-base-repositories.md           | 256 ----------
 .../data-mongo-domain-model.md                | 471 ------------------
 .../data-mongo-query-filters.md               | 316 ------------
 .../data-mongo-reactive-repositories.md       | 287 -----------
 ...ngo-sync-config-and-custom-repositories.md | 434 ----------------
 .../data-nats-notifications.md                | 365 --------------
 .../data-pinot-repositories.md                | 308 ------------
 .../data-redis-cache/data-redis-cache.md      | 240 ---------
 .../external-api-service-core.md              | 436 ----------------
 ...teway-service-core-security-and-routing.md | 368 --------------
 ...ervice-core-initializers-and-schedulers.md | 433 ----------------
 .../security-core-and-oauth-bff.md            | 351 -------------
 .../stream-service-core-kafka-and-handlers.md | 356 -------------
 251 files changed, 15318 deletions(-)
 delete mode 100644 docs/README.md
 delete mode 100644 docs/development/.gitignore
 delete mode 100644 docs/development/README.md
 delete mode 100644 docs/development/architecture/README.md
 delete mode 100644 docs/development/contributing/guidelines.md
 delete mode 100644 docs/development/security/README.md
 delete mode 100644 docs/development/setup/environment.md
 delete mode 100644 docs/development/setup/local-development.md
 delete mode 100644 docs/development/testing/README.md
 delete mode 100644 docs/diagrams/architecture/.gitignore
 delete mode 100644 docs/diagrams/architecture/README-2.mmd
 delete mode 100644 docs/diagrams/architecture/README-3.mmd
 delete mode 100644 docs/diagrams/architecture/README-4.mmd
 delete mode 100644 docs/diagrams/architecture/README-5.mmd
 delete mode 100644 docs/diagrams/architecture/README-6.mmd
 delete mode 100644 docs/diagrams/architecture/README-7.mmd
 delete mode 100644 docs/diagrams/architecture/README-8.mmd
 delete mode 100644 docs/diagrams/architecture/README.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination-7.mmd
 delete mode 100644 docs/diagrams/architecture/api-contracts-and-pagination.mmd
 delete mode 100644 docs/diagrams/architecture/api-domain-filters-dtos-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-domain-filters-dtos-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-domain-filters-dtos-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-domain-filters-dtos-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-domain-filters-dtos-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-domain-filters-dtos.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services-7.mmd
 delete mode 100644 docs/diagrams/architecture/api-lib-core-services.mmd
 delete mode 100644 docs/diagrams/architecture/api-organization-mapping-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-organization-mapping-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-organization-mapping-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-organization-mapping-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-organization-mapping-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-organization-mapping.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-config-and-security-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-config-and-security-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-config-and-security-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-config-and-security-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-config-and-security-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-config-and-security.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-dataloaders-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-dataloaders-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-dataloaders-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-dataloaders-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-dataloaders-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-dataloaders.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-7.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers-8.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-datafetchers.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-dtos-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-dtos-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-dtos-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-dtos-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-graphql-dtos.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-relay-type-resolution-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-relay-type-resolution-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-relay-type-resolution-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-relay-type-resolution-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-relay-type-resolution.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-10.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-11.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-5.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-6.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-7.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-8.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers-9.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-rest-controllers.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-2.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-3.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-4.mmd
 delete mode 100644 docs/diagrams/architecture/api-service-core-user-sso-services-and-processors.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-2.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-3.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-4.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-5.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-2.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-3.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-4.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-5.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-6.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-2.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-3.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-4.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-5.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-6.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-7.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant-8.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-server-and-tenant.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-2.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-3.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-4.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-5.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-6.mmd
 delete mode 100644 docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils.mmd
 delete mode 100644 docs/diagrams/architecture/data-kafka-configuration-and-retry-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-kafka-configuration-and-retry-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-kafka-configuration-and-retry-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-kafka-configuration-and-retry-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-kafka-configuration-and-retry-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-kafka-configuration-and-retry.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories-7.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-base-repositories.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-domain-model-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-domain-model-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-domain-model-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-domain-model-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-domain-model-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-domain-model.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-query-filters-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-query-filters-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-query-filters-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-query-filters-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-query-filters-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-query-filters.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-reactive-repositories-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-reactive-repositories-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-reactive-repositories.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-7.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-8.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-9.mmd
 delete mode 100644 docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories.mmd
 delete mode 100644 docs/diagrams/architecture/data-nats-notifications-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-nats-notifications-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-nats-notifications-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-nats-notifications-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-nats-notifications-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-nats-notifications.mmd
 delete mode 100644 docs/diagrams/architecture/data-pinot-repositories-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-pinot-repositories-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-pinot-repositories-4.mmd
 delete mode 100644 docs/diagrams/architecture/data-pinot-repositories-5.mmd
 delete mode 100644 docs/diagrams/architecture/data-pinot-repositories-6.mmd
 delete mode 100644 docs/diagrams/architecture/data-pinot-repositories.mmd
 delete mode 100644 docs/diagrams/architecture/data-redis-cache-2.mmd
 delete mode 100644 docs/diagrams/architecture/data-redis-cache-3.mmd
 delete mode 100644 docs/diagrams/architecture/data-redis-cache.mmd
 delete mode 100644 docs/diagrams/architecture/external-api-service-core-2.mmd
 delete mode 100644 docs/diagrams/architecture/external-api-service-core-3.mmd
 delete mode 100644 docs/diagrams/architecture/external-api-service-core-4.mmd
 delete mode 100644 docs/diagrams/architecture/external-api-service-core-5.mmd
 delete mode 100644 docs/diagrams/architecture/external-api-service-core.mmd
 delete mode 100644 docs/diagrams/architecture/gateway-service-core-security-and-routing-2.mmd
 delete mode 100644 docs/diagrams/architecture/gateway-service-core-security-and-routing-3.mmd
 delete mode 100644 docs/diagrams/architecture/gateway-service-core-security-and-routing-4.mmd
 delete mode 100644 docs/diagrams/architecture/gateway-service-core-security-and-routing-5.mmd
 delete mode 100644 docs/diagrams/architecture/gateway-service-core-security-and-routing.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-2.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-3.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-4.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-5.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-6.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-7.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-8.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers-9.mmd
 delete mode 100644 docs/diagrams/architecture/management-service-core-initializers-and-schedulers.mmd
 delete mode 100644 docs/diagrams/architecture/processors-2.mmd
 delete mode 100644 docs/diagrams/architecture/processors-3.mmd
 delete mode 100644 docs/diagrams/architecture/processors-4.mmd
 delete mode 100644 docs/diagrams/architecture/processors-5.mmd
 delete mode 100644 docs/diagrams/architecture/processors-6.mmd
 delete mode 100644 docs/diagrams/architecture/processors-7.mmd
 delete mode 100644 docs/diagrams/architecture/processors-8.mmd
 delete mode 100644 docs/diagrams/architecture/processors.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-2.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-3.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-4.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-5.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-6.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-7.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff-8.mmd
 delete mode 100644 docs/diagrams/architecture/security-core-and-oauth-bff.mmd
 delete mode 100644 docs/diagrams/architecture/services-2.mmd
 delete mode 100644 docs/diagrams/architecture/services-3.mmd
 delete mode 100644 docs/diagrams/architecture/services-4.mmd
 delete mode 100644 docs/diagrams/architecture/services-5.mmd
 delete mode 100644 docs/diagrams/architecture/services-6.mmd
 delete mode 100644 docs/diagrams/architecture/services-7.mmd
 delete mode 100644 docs/diagrams/architecture/services.mmd
 delete mode 100644 docs/diagrams/architecture/stream-service-core-kafka-and-handlers-2.mmd
 delete mode 100644 docs/diagrams/architecture/stream-service-core-kafka-and-handlers-3.mmd
 delete mode 100644 docs/diagrams/architecture/stream-service-core-kafka-and-handlers-4.mmd
 delete mode 100644 docs/diagrams/architecture/stream-service-core-kafka-and-handlers-5.mmd
 delete mode 100644 docs/diagrams/architecture/stream-service-core-kafka-and-handlers.mmd
 delete mode 100644 docs/getting-started/.gitignore
 delete mode 100644 docs/getting-started/first-steps.md
 delete mode 100644 docs/getting-started/introduction.md
 delete mode 100644 docs/getting-started/prerequisites.md
 delete mode 100644 docs/getting-started/quick-start.md
 delete mode 100644 docs/reference/architecture/.gitignore
 delete mode 100644 docs/reference/architecture/README.md
 delete mode 100644 docs/reference/architecture/api-contracts-and-pagination/api-contracts-and-pagination.md
 delete mode 100644 docs/reference/architecture/api-domain-filters-dtos/api-domain-filters-dtos.md
 delete mode 100644 docs/reference/architecture/api-lib-core-services/api-lib-core-services.md
 delete mode 100644 docs/reference/architecture/api-organization-mapping/api-organization-mapping.md
 delete mode 100644 docs/reference/architecture/api-service-core-config-and-security/api-service-core-config-and-security.md
 delete mode 100644 docs/reference/architecture/api-service-core-dataloaders/api-service-core-dataloaders.md
 delete mode 100644 docs/reference/architecture/api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md
 delete mode 100644 docs/reference/architecture/api-service-core-graphql-dtos/api-service-core-graphql-dtos.md
 delete mode 100644 docs/reference/architecture/api-service-core-relay-type-resolution/api-service-core-relay-type-resolution.md
 delete mode 100644 docs/reference/architecture/api-service-core-rest-controllers/api-service-core-rest-controllers.md
 delete mode 100644 docs/reference/architecture/api-service-core-user-sso-services-and-processors/api-service-core-user-sso-services-and-processors.md
 delete mode 100644 docs/reference/architecture/api-service-core-user-sso-services-and-processors/processors.md
 delete mode 100644 docs/reference/architecture/api-service-core-user-sso-services-and-processors/services.md
 delete mode 100644 docs/reference/architecture/authorization-service-core-auth-controllers-and-dtos/authorization-service-core-auth-controllers-and-dtos.md
 delete mode 100644 docs/reference/architecture/authorization-service-core-keys-and-authorization-persistence/authorization-service-core-keys-and-authorization-persistence.md
 delete mode 100644 docs/reference/architecture/authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md
 delete mode 100644 docs/reference/architecture/authorization-service-core-sso-flow-and-utils/authorization-service-core-sso-flow-and-utils.md
 delete mode 100644 docs/reference/architecture/data-kafka-configuration-and-retry/data-kafka-configuration-and-retry.md
 delete mode 100644 docs/reference/architecture/data-mongo-base-repositories/data-mongo-base-repositories.md
 delete mode 100644 docs/reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md
 delete mode 100644 docs/reference/architecture/data-mongo-query-filters/data-mongo-query-filters.md
 delete mode 100644 docs/reference/architecture/data-mongo-reactive-repositories/data-mongo-reactive-repositories.md
 delete mode 100644 docs/reference/architecture/data-mongo-sync-config-and-custom-repositories/data-mongo-sync-config-and-custom-repositories.md
 delete mode 100644 docs/reference/architecture/data-nats-notifications/data-nats-notifications.md
 delete mode 100644 docs/reference/architecture/data-pinot-repositories/data-pinot-repositories.md
 delete mode 100644 docs/reference/architecture/data-redis-cache/data-redis-cache.md
 delete mode 100644 docs/reference/architecture/external-api-service-core/external-api-service-core.md
 delete mode 100644 docs/reference/architecture/gateway-service-core-security-and-routing/gateway-service-core-security-and-routing.md
 delete mode 100644 docs/reference/architecture/management-service-core-initializers-and-schedulers/management-service-core-initializers-and-schedulers.md
 delete mode 100644 docs/reference/architecture/security-core-and-oauth-bff/security-core-and-oauth-bff.md
 delete mode 100644 docs/reference/architecture/stream-service-core-kafka-and-handlers/stream-service-core-kafka-and-handlers.md

diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index f5d99817c..000000000
--- a/docs/README.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# openframe-oss-lib Documentation
-
-Welcome to the documentation for **openframe-oss-lib** — the foundational backend library powering the [OpenFrame](https://openframe.ai) platform.
-
-This section contains comprehensive guides covering getting started, development workflows, security practices, testing strategies, and full reference architecture documentation for every module.
-
----
-
-## 📚 Table of Contents
-
-### Getting Started
-
-- [Introduction](./getting-started/introduction.md) — What is openframe-oss-lib, key features, and high-level architecture
-- [Prerequisites](./getting-started/prerequisites.md) — Required software, Java setup, GitHub Packages access, IDE configuration
-- [Quick Start](./getting-started/quick-start.md) — Clone, build, and add modules as dependencies in 5 minutes
-- [First Steps](./getting-started/first-steps.md) — Module structure, domain model exploration, security modules, and gateway overview
-
----
-
-### Development
-
-- [Development Overview](./development/README.md) — Index of all development documentation and quick navigation
-- [Environment Setup](./development/setup/environment.md) — IDE configuration (IntelliJ / VS Code), Maven setup, Docker, environment variables
-- [Local Development](./development/setup/local-development.md) — Clone, build, iterate, debug, and manage dependencies locally
-- [Architecture Overview](./development/architecture/README.md) — System design, component relationships, data flows, and key design decisions
-- [Security Best Practices](./development/security/README.md) — Auth patterns, multi-tenant key isolation, secrets management, input validation
-- [Testing Overview](./development/testing/README.md) — Test structure, running tests, integration test infrastructure, writing new tests
-- [Contributing Guidelines](./development/contributing/guidelines.md) — Code style, branching, commit conventions, and pull request process
-
----
-
-### Reference Architecture
-
-- [Repository Overview](./reference/architecture/README.md) — Full module index and end-to-end system view
-
-#### API Foundation
-- [API Contracts and Pagination](./reference/architecture/api-contracts-and-pagination/api-contracts-and-pagination.md) — Relay-style pagination, cursor codec, mutation inputs
-- [API Domain Filters & DTOs](./reference/architecture/api-domain-filters-dtos/api-domain-filters-dtos.md) — Strongly-typed filter DTOs for devices, events, logs, and organizations
-- [API Lib Core Services](./reference/architecture/api-lib-core-services/api-lib-core-services.md) — Reusable domain services: tool connections, ticket queries, device status
-- [API Organization Mapping](./reference/architecture/api-organization-mapping/api-organization-mapping.md) — Organization-level API mapping layer
-
-#### API Service Core
-- [API Service Core Overview](./reference/architecture/api-service-core-user-sso-services-and-processors/api-service-core-user-sso-services-and-processors.md) — User SSO services and processors
-- [API Service Core Services](./reference/architecture/api-service-core-user-sso-services-and-processors/services.md) — Core service implementations
-- [API Service Core Processors](./reference/architecture/api-service-core-user-sso-services-and-processors/processors.md) — Processor implementations
-- [REST Controllers](./reference/architecture/api-service-core-rest-controllers/api-service-core-rest-controllers.md) — Internal REST endpoints: organizations, devices, users, invitations, API keys
-- [GraphQL Data Fetchers](./reference/architecture/api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md) — Relay-compliant GraphQL execution layer
-- [GraphQL DTOs](./reference/architecture/api-service-core-graphql-dtos/api-service-core-graphql-dtos.md) — GraphQL input/output types
-- [DataLoaders](./reference/architecture/api-service-core-dataloaders/api-service-core-dataloaders.md) — Batched DataLoader implementations for N+1 prevention
-- [Relay Type Resolution](./reference/architecture/api-service-core-relay-type-resolution/api-service-core-relay-type-resolution.md) — Polymorphic Relay node type resolution
-- [Config and Security](./reference/architecture/api-service-core-config-and-security/api-service-core-config-and-security.md) — JWT resource server, multi-issuer support, OAuth client initialization
-
-#### Authorization Service Core
-- [Server and Tenant](./reference/architecture/authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md) — Multi-tenant OAuth2 authorization server, tenant discovery and registration
-- [Auth Controllers and DTOs](./reference/architecture/authorization-service-core-auth-controllers-and-dtos/authorization-service-core-auth-controllers-and-dtos.md) — Authentication controllers and data transfer objects
-- [Keys and Authorization Persistence](./reference/architecture/authorization-service-core-keys-and-authorization-persistence/authorization-service-core-keys-and-authorization-persistence.md) — Per-tenant RSA key pairs, JWT issuance, persistence
-- [SSO Flow and Utils](./reference/architecture/authorization-service-core-sso-flow-and-utils/authorization-service-core-sso-flow-and-utils.md) — Google and Microsoft SSO flows, PKCE support
-
-#### Gateway Service Core
-- [Gateway Security and Routing](./reference/architecture/gateway-service-core-security-and-routing/gateway-service-core-security-and-routing.md) — Reactive edge gateway, JWT validation, API key rate limiting, WebSocket proxying
-
-#### Stream Service Core
-- [Kafka and Handlers](./reference/architecture/stream-service-core-kafka-and-handlers/stream-service-core-kafka-and-handlers.md) — Debezium CDC ingestion, event enrichment, unified event type mapping
-
-#### External API Service Core
-- [External API Service](./reference/architecture/external-api-service-core/external-api-service-core.md) — Public REST interface for third-party integrations
-
-#### Management Service Core
-- [Initializers and Schedulers](./reference/architecture/management-service-core-initializers-and-schedulers/management-service-core-initializers-and-schedulers.md) — Startup initializers, ShedLock distributed schedulers
-
-#### Security Core
-- [Security Core and OAuth BFF](./reference/architecture/security-core-and-oauth-bff/security-core-and-oauth-bff.md) — PKCE utilities, JWT encoder/decoder, OAuth BFF login flow
-
-#### Data Layer
-- [MongoDB Domain Model](./reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md) — Canonical MongoDB documents: User, Organization, Device, Ticket, Tool
-- [MongoDB Base Repositories](./reference/architecture/data-mongo-base-repositories/data-mongo-base-repositories.md) — Base repository interfaces and patterns
-- [MongoDB Query Filters](./reference/architecture/data-mongo-query-filters/data-mongo-query-filters.md) — MongoDB query filter construction
-- [MongoDB Sync Config and Custom Repositories](./reference/architecture/data-mongo-sync-config-and-custom-repositories/data-mongo-sync-config-and-custom-repositories.md) — Synchronous repositories, index configuration, custom queries
-- [MongoDB Reactive Repositories](./reference/architecture/data-mongo-reactive-repositories/data-mongo-reactive-repositories.md) — Reactive MongoDB repository layer
-- [Redis Cache](./reference/architecture/data-redis-cache/data-redis-cache.md) — Tenant-aware cache key prefixing, Spring Cache integration
-- [Kafka Configuration and Retry](./reference/architecture/data-kafka-configuration-and-retry/data-kafka-configuration-and-retry.md) — Multi-tenant Kafka config, topic provisioning, retry handling
-- [NATS Notifications](./reference/architecture/data-nats-notifications/data-nats-notifications.md) — Persist-first notification strategy, read-state tracking, NATS publishing
-- [Pinot Repositories](./reference/architecture/data-pinot-repositories/data-pinot-repositories.md) — Apache Pinot analytics queries for logs and device facets
-
----
-
-### Architecture Diagrams
-
-Visual Mermaid diagrams are available for every module under:
-
-```text
-docs/diagrams/architecture/
-```
-
-Diagrams cover request flows, data flows, class relationships, and sequence diagrams for all major components.
-
----
-
-## 📖 Quick Links
-
-- [Project README](../README.md) — Main project overview and quick start
-- [Contributing Guide](../CONTRIBUTING.md) — How to contribute to openframe-oss-lib
-- [OpenFrame Platform](https://openframe.ai) — The OpenFrame MSP platform
-- [OpenMSP Community (Slack)](https://www.openmsp.ai/) — Community discussions and support
-- [Flamingo](https://flamingo.run) — The team behind OpenFrame
-
----
-
-*Documentation generated by [OpenFrame Doc Orchestrator](https://github.com/flamingo-stack/openframe-oss-tenant)*
diff --git a/docs/development/.gitignore b/docs/development/.gitignore
deleted file mode 100644
index a5d01be52..000000000
--- a/docs/development/.gitignore
+++ /dev/null
@@ -1,7 +0,0 @@
-# VoltAgent temp files
-temp/
-
-# JSON intermediate files (except schema/config)
-*.json
-!*-schema.json
-!*-config.json
diff --git a/docs/development/README.md b/docs/development/README.md
deleted file mode 100644
index eb274e770..000000000
--- a/docs/development/README.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# Development Documentation
-
-Welcome to the **openframe-oss-lib** development documentation. This section covers everything you need to contribute to, extend, and maintain the OpenFrame OSS library.
-
----
-
-## Overview
-
-**openframe-oss-lib** is a Java 21 / Spring Boot 3.3 multi-module Maven library. It is the shared backend infrastructure stack for the OpenFrame MSP platform. The development section explains how to set up your environment, understand the architecture, write tests, secure your code, and contribute effectively.
-
----
-
-## Documentation Index
-
-| Document | Description |
-|----------|-------------|
-| [Environment Setup](./setup/environment.md) | IDE configuration, extensions, and dev tools |
-| [Local Development](./setup/local-development.md) | Clone, build, run, and debug locally |
-| [Architecture Overview](./architecture/README.md) | System design, module relationships, data flows |
-| [Security Best Practices](./security/README.md) | Auth patterns, secrets management, input validation |
-| [Testing Overview](./testing/README.md) | Test structure, running tests, writing new tests |
-| [Contributing Guidelines](./contributing/guidelines.md) | Code style, PR process, commit conventions |
-
----
-
-## Quick Navigation
-
-### I want to...
-
-**Set up my local environment**
-→ Start with [Environment Setup](./setup/environment.md), then [Local Development](./setup/local-development.md)
-
-**Understand how the system works**
-→ Read the [Architecture Overview](./architecture/README.md)
-
-**Add a new feature or fix a bug**
-→ Follow the [Contributing Guidelines](./contributing/guidelines.md) and review [Local Development](./setup/local-development.md)
-
-**Write tests for my changes**
-→ See [Testing Overview](./testing/README.md)
-
-**Understand security requirements**
-→ Read [Security Best Practices](./security/README.md)
-
----
-
-## Tech Stack at a Glance
-
-| Layer | Technology |
-|-------|-----------|
-| Language | Java 21 |
-| Framework | Spring Boot 3.3 |
-| Build Tool | Apache Maven 3.9+ |
-| Multi-tenancy | Thread-local tenant context, per-tenant RSA keys |
-| Auth | Spring Authorization Server, Spring Security OAuth2 |
-| Persistence | MongoDB (sync + reactive), Redis, Cassandra, Apache Pinot |
-| Messaging | Kafka / Debezium CDC, NATS JetStream |
-| Gateway | Spring Cloud Gateway + WebFlux + Netty |
-| API | Relay-compliant GraphQL (Netflix DGS), REST |
-| Testing | JUnit 5, Testcontainers, RestAssured |
-| Distributed Locking | ShedLock + Redis |
-
----
-
-## Repository Structure
-
-```text
-openframe-oss-lib/
-├── pom.xml                              # Parent POM (unified versioning)
-├── openframe-core/                      # Core utilities
-├── openframe-exception/                 # Exception hierarchy
-├── openframe-core-crypto/               # Encryption
-├── openframe-security-core/             # JWT, PKCE, cookies
-├── openframe-security-oauth/            # OAuth2 BFF
-├── openframe-authorization-service-core/# Multi-tenant auth server
-├── openframe-api-lib/                   # API contracts, DTOs
-├── openframe-api-service-core/          # REST + GraphQL API
-├── openframe-gateway-service-core/      # Reactive gateway
-├── openframe-client-core/               # Agent/client endpoints
-├── openframe-data-mongo-common/         # MongoDB documents
-├── openframe-data-mongo-sync/           # Sync repositories
-├── openframe-data-mongo-reactive/       # Reactive repositories
-├── openframe-data-redis/                # Redis cache
-├── openframe-data-kafka/                # Kafka configuration
-├── openframe-data-nats/                 # NATS messaging
-├── openframe-data-cassandra/            # Cassandra storage
-├── openframe-data-pinot/                # Pinot analytics
-├── openframe-management-service-core/   # Schedulers, initializers
-├── openframe-stream-service-core/       # Kafka streams
-├── openframe-external-api-service-core/ # External REST API
-├── openframe-test-service-core/         # Integration test utilities
-├── sdk/
-│   ├── fleetmdm/                        # Fleet MDM SDK
-│   └── tacticalrmm/                     # Tactical RMM SDK
-└── ...
-```
-
----
-
-## Community
-
-All development discussions happen in the [OpenMSP Slack Community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA). We do not use GitHub Issues or GitHub Discussions.
-
-[![OpenFrame v0.5.2: Autonomous AI Agent Architecture for MSPs](https://img.youtube.com/vi/PexpoNdZtUk/maxresdefault.jpg)](https://www.youtube.com/watch?v=PexpoNdZtUk)
diff --git a/docs/development/architecture/README.md b/docs/development/architecture/README.md
deleted file mode 100644
index e03e09358..000000000
--- a/docs/development/architecture/README.md
+++ /dev/null
@@ -1,199 +0,0 @@
-# Architecture Overview
-
-**openframe-oss-lib** implements a layered, multi-tenant service-oriented architecture. This document provides a high-level overview of the system design, component relationships, and key data flows.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    Client["Client / Browser / Agent"] --> Gateway["Gateway Service Core\n(Spring Cloud Gateway + WebFlux)"]
-    Gateway --> ExternalAPI["External API Service Core\n(REST + API Keys)"]
-    Gateway --> ApiCore["API Service Core\n(REST + GraphQL)"]
-
-    ApiCore --> Authz["Authorization Service Core\n(OAuth2 / JWT)"]
-    ApiCore --> Stream["Stream Service Core\n(Kafka / Debezium)"]
-    ApiCore --> Management["Management Service Core\n(Schedulers / Initializers)"]
-    ApiCore --> ClientSvc["Client Core\n(Agent Registration)"]
-
-    Authz --> Mongo["MongoDB"]
-    ApiCore --> Mongo
-    ApiCore --> Redis["Redis"]
-    Stream --> Kafka["Apache Kafka"]
-    Stream --> Pinot["Apache Pinot"]
-    Stream --> Cassandra["Apache Cassandra"]
-    Management --> NATS["NATS JetStream"]
-    Management --> Mongo
-```
-
----
-
-## Core Modules
-
-| Module | Responsibility | Key Technologies |
-|--------|---------------|-----------------|
-| `openframe-gateway-service-core` | Edge layer: JWT auth, API key rate limiting, WebSocket proxying, tool routing | Spring Cloud Gateway, WebFlux, Netty |
-| `openframe-authorization-service-core` | Multi-tenant OAuth2 auth server: JWT issuance, SSO, per-tenant keys | Spring Authorization Server, Spring Security |
-| `openframe-security-core` | JWT encoding/decoding, PKCE, cookie management | Nimbus JOSE, Spring Security |
-| `openframe-security-oauth` | OAuth2 BFF: browser-facing login/callback/refresh/logout endpoints | Spring Security OAuth2 |
-| `openframe-api-service-core` | Internal API: GraphQL (Relay) + REST controllers | Netflix DGS, Spring MVC |
-| `openframe-api-lib` | API contracts: filter DTOs, cursor pagination, mutation types | Spring, Jackson |
-| `openframe-external-api-service-core` | External API: API key–authenticated REST endpoints for integrations | Spring MVC, OpenAPI |
-| `openframe-client-core` | Agent/device registration, tool agent endpoints | Spring MVC, NATS |
-| `openframe-stream-service-core` | Kafka/Debezium CDC: event ingestion, normalization, enrichment | Kafka Streams, Spring Kafka |
-| `openframe-management-service-core` | Startup initializers, distributed schedulers, tool orchestration | ShedLock, Spring Retry |
-| `openframe-data-mongo-common` | MongoDB domain documents: canonical persistence model | Spring Data MongoDB |
-| `openframe-data-mongo-sync` | Synchronous MongoDB repositories + index configuration | Spring Data MongoDB |
-| `openframe-data-mongo-reactive` | Reactive MongoDB repositories | Spring Data MongoDB Reactive |
-| `openframe-data-redis` | Tenant-aware Redis cache, reactive repositories | Spring Data Redis |
-| `openframe-data-kafka` | Multi-tenant Kafka configuration, topic provisioning, retry | Spring Kafka |
-| `openframe-data-nats` | NATS JetStream publishers, notification broadcasting | NATS Spring Cloud Stream |
-| `openframe-data-cassandra` | Tenant-scoped Cassandra log storage | Spring Data Cassandra |
-| `openframe-data-pinot` | Apache Pinot analytics queries | Pinot Java Client |
-| `sdk/fleetmdm` | Fleet MDM Java client | Spring WebClient |
-| `sdk/tacticalrmm` | Tactical RMM Java client | Spring WebClient |
-
----
-
-## Data Flow: Request Processing
-
-```mermaid
-sequenceDiagram
-    participant C as Client
-    participant GW as Gateway
-    participant Auth as Auth Service
-    participant API as API Service
-    participant DB as MongoDB
-
-    C->>GW: HTTP Request (with Bearer token or API key)
-    GW->>GW: Validate JWT (multi-issuer) / API key
-    GW->>API: Forwarded request + X-User-Id header
-    API->>DB: Query data (via Spring Data repositories)
-    DB-->>API: Domain documents
-    API-->>GW: Response
-    GW-->>C: HTTP Response
-```
-
----
-
-## Data Flow: Authentication (OAuth2)
-
-```mermaid
-sequenceDiagram
-    participant B as Browser
-    participant BFF as OAuth BFF
-    participant AuthSrv as Authorization Server
-    participant KS as TenantKeyService
-    participant DB as MongoDB
-
-    B->>BFF: GET /oauth/login
-    BFF->>AuthSrv: Redirect (PKCE + state)
-    AuthSrv->>B: Login UI
-    B->>AuthSrv: Credentials
-    AuthSrv->>KS: Get tenant RSA key pair
-    KS->>DB: Load/create TenantKey
-    AuthSrv->>BFF: callback?code=...
-    BFF->>AuthSrv: Exchange code → tokens
-    AuthSrv-->>BFF: JWT (access + refresh)
-    BFF->>B: Set HttpOnly cookies
-```
-
----
-
-## Data Flow: Event Streaming (Kafka / Debezium)
-
-```mermaid
-flowchart LR
-    subgraph Tools["Integrated Tools"]
-        T1["Tactical RMM"]
-        T2["Fleet MDM"]
-        T3["MeshCentral"]
-    end
-    subgraph Processing["Stream Service Core"]
-        L["Kafka Listener"]
-        D["Tool Deserializer"]
-        E["Enrichment Service"]
-        M["EventTypeMapper"]
-        H["Message Handler"]
-    end
-    subgraph Storage["Storage"]
-        C["Cassandra\n(UnifiedLogEvent)"]
-        K["Kafka\n(Enriched Topics)"]
-    end
-
-    T1 --> L
-    T2 --> L
-    T3 --> L
-    L --> D
-    D --> E
-    E --> M
-    M --> H
-    H --> C
-    H --> K
-```
-
----
-
-## Multi-Tenancy Design
-
-Every module implements strict tenant isolation:
-
-```mermaid
-flowchart TD
-    Request["HTTP Request"] --> TenantFilter["TenantContextFilter\n(Extracts tenant ID)"]
-    TenantFilter --> ThreadLocal["TenantContext\n(ThreadLocal)"]
-    ThreadLocal --> KeyService["TenantKeyService\n(Per-tenant RSA keys)"]
-    ThreadLocal --> Repo["Tenant-Scoped Repositories"]
-    ThreadLocal --> LockKey["ShedLock Key\nof:{tenantId}:job-lock:..."]
-    ThreadLocal --> CacheKey["Redis Key\nof:{tenantId}:..."]
-```
-
-Key multi-tenancy patterns:
-
-| Pattern | Implementation |
-|---------|---------------|
-| Tenant context propagation | `TenantContext` ThreadLocal, set by `TenantContextFilter` |
-| Per-tenant JWT signing keys | `TenantKeyService` with RSA key pairs stored in MongoDB |
-| Tenant-scoped cache keys | `OpenframeRedisKeyBuilder` prefixes every key with tenant ID |
-| Tenant-scoped scheduler locks | ShedLock keys include `tenantId` and `environment` |
-| JWT claim injection | `tenant_id`, `userId`, `roles` are embedded in every access token |
-
----
-
-## Key Design Decisions
-
-### 1. Reactive Gateway, Blocking Services
-
-The gateway (`openframe-gateway-service-core`) is fully reactive (WebFlux + Netty). Internal services use Spring MVC (blocking), keeping service-level logic simple while the gateway handles high concurrency.
-
-### 2. GraphQL + REST Coexistence
-
-- **Internal API:** Relay-compliant GraphQL (Netflix DGS) with DataLoaders for N+1 prevention
-- **External API:** REST with OpenAPI documentation and API key authentication
-- Both APIs share the same domain services and repositories
-
-### 3. Event-Driven Normalization
-
-Integrated tools (Tactical RMM, Fleet MDM, MeshCentral) emit raw Debezium CDC events into Kafka. The Stream Service normalizes these into a unified `UnifiedEventType` before persisting to Cassandra or re-publishing.
-
-### 4. Startup Orchestration
-
-All bootstrapping logic is centralized in `openframe-management-service-core` using Spring `ApplicationRunner`. This ensures consistent initialization order across deployments.
-
----
-
-## Reference Documentation
-
-Detailed architecture documentation is available for each module:
-
-- [Gateway Service Core](./reference/architecture/gateway-service-core-security-and-routing/gateway-service-core-security-and-routing.md)
-- [Authorization Service Core](./reference/architecture/authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md)
-- [Stream Service Core](./reference/architecture/stream-service-core-kafka-and-handlers/stream-service-core-kafka-and-handlers.md)
-- [Management Service Core](./reference/architecture/management-service-core-initializers-and-schedulers/management-service-core-initializers-and-schedulers.md)
-- [External API Service Core](./reference/architecture/external-api-service-core/external-api-service-core.md)
-- [Data Mongo Domain Model](./reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md)
-- [Data Kafka Configuration](./reference/architecture/data-kafka-configuration-and-retry/data-kafka-configuration-and-retry.md)
-- [Security Core and OAuth BFF](./reference/architecture/security-core-and-oauth-bff/security-core-and-oauth-bff.md)
-
-[![Watch What's New in OpenFrame 0.7.8](https://img.youtube.com/vi/BQAjDB4ED2Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=BQAjDB4ED2Y)
diff --git a/docs/development/contributing/guidelines.md b/docs/development/contributing/guidelines.md
deleted file mode 100644
index d12792a64..000000000
--- a/docs/development/contributing/guidelines.md
+++ /dev/null
@@ -1,264 +0,0 @@
-# Contributing Guidelines
-
-Thank you for contributing to **openframe-oss-lib**! This guide covers code style, branching strategy, commit conventions, and the pull request process.
-
----
-
-## Community First
-
-All contribution discussions happen on the [OpenMSP Slack Community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA). We do **not** use GitHub Issues or GitHub Discussions.
-
-Before starting a large contribution:
-1. Join the [OpenMSP Slack](https://www.openmsp.ai/)
-2. Describe what you're planning in the `#openframe-dev` channel
-3. Get feedback from maintainers before investing significant effort
-
----
-
-## Code Style and Conventions
-
-### Java Style
-
-The project follows standard Java conventions with the following specifics:
-
-| Convention | Rule |
-|-----------|------|
-| Indentation | 4 spaces (no tabs) |
-| Line length | Max 120 characters |
-| Imports | No wildcard imports; organize by static → java → jakarta → spring → other |
-| Braces | Allman-adjacent style (opening brace on same line) |
-| Naming | `camelCase` methods/fields, `PascalCase` classes, `UPPER_SNAKE` constants |
-
-### Lombok Usage
-
-Use Lombok to reduce boilerplate. Preferred annotations:
-
-```java
-// Prefer these
-@Data          // getters, setters, equals, hashCode, toString
-@Value         // immutable value objects
-@Builder       // fluent builders
-@RequiredArgsConstructor  // constructor injection
-@Slf4j         // logging
-
-// Avoid manual getters/setters when @Data or @Value apply
-```
-
-### Spring Boot Conventions
-
-- Use constructor injection (via `@RequiredArgsConstructor`) over field injection (`@Autowired`)
-- Prefer `@ConfigurationProperties` over `@Value` for configuration
-- Use `@Service`, `@Repository`, `@Component`, `@Controller` consistently
-- Configuration classes should be annotated with `@Configuration`
-
-```java
-// Correct: Constructor injection
-@Service
-@RequiredArgsConstructor
-public class MyService {
-    private final MyRepository repository;
-    private final AnotherService anotherService;
-}
-
-// Avoid: Field injection
-@Service
-public class MyService {
-    @Autowired
-    private MyRepository repository;
-}
-```
-
-### Multi-Tenancy Requirements
-
-Every service and repository method that accesses tenant-scoped data **must** include `tenantId` in queries:
-
-```java
-// Correct: Always scope to tenant
-Optional<Organization> findByIdAndTenantId(String id, String tenantId);
-
-// Wrong: Missing tenant scope
-Optional<Organization> findById(String id); // Never use for tenant-scoped data
-```
-
-### Exception Handling
-
-Use the standard exception hierarchy from `openframe-exception`:
-
-```java
-// Use specific exception types
-throw new NotFoundException("Organization not found: " + id);
-throw new BadRequestException("Invalid email format");
-throw new ForbiddenException("Access denied for tenant: " + tenantId);
-throw new ConflictException("Email already exists");
-throw new ValidationException("Required field missing: name");
-```
-
-Never throw `RuntimeException` or `Exception` directly.
-
----
-
-## Branch Naming
-
-Use descriptive branch names with a type prefix:
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Feature | `feature/<description>` | `feature/add-nats-retry-logic` |
-| Bug fix | `fix/<description>` | `fix/tenant-context-not-cleared` |
-| Refactor | `refactor/<description>` | `refactor/notification-repository` |
-| Documentation | `docs/<description>` | `docs/update-kafka-readme` |
-| Dependency updates | `deps/<description>` | `deps/upgrade-spring-boot-3.4` |
-
----
-
-## Commit Message Format
-
-Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
-
-```text
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer]
-```
-
-### Types
-
-| Type | When to Use |
-|------|------------|
-| `feat` | New feature or capability |
-| `fix` | Bug fix |
-| `refactor` | Code change that neither fixes a bug nor adds a feature |
-| `test` | Adding or updating tests |
-| `docs` | Documentation only changes |
-| `chore` | Build system, dependency updates, CI changes |
-| `perf` | Performance improvements |
-
-### Scope
-
-Use the module name (without `openframe-` prefix) as scope:
-
-```text
-feat(security-core): add PKCE utility for code challenge generation
-fix(data-mongo-sync): resolve tenant context leak in batch operations
-refactor(gateway-service-core): extract rate limit logic into service
-test(data-nats): add integration test for notification broadcast
-docs(api-service-core): update GraphQL data fetcher documentation
-chore(deps): upgrade spring-boot to 3.3.2
-```
-
-### Examples
-
-```text
-feat(authorization-service-core): add Microsoft SSO provider strategy
-
-Implements MicrosoftClientRegistrationStrategy to support Microsoft
-Entra ID (Azure AD) authentication flows alongside existing Google SSO.
-
-Closes: #discussion in #openframe-dev slack
-```
-
-```text
-fix(stream-service-core): handle null tenant_id in debezium enrichment
-
-When a Debezium event is missing the tenant header, the enrichment service
-now falls back to domain-based tenant resolution instead of throwing NPE.
-```
-
----
-
-## Pull Request Process
-
-### Before Opening a PR
-
-1. **Build passes:** `mvn install -DskipTests`
-2. **Tests pass:** `mvn test -pl <affected-module>`
-3. **No secrets committed:** Review all changed files
-4. **Follows code style:** Check Lombok, constructor injection, tenant scoping
-5. **Covers edge cases:** Add unit tests for new logic
-
-### PR Title
-
-Use the same format as commit messages:
-
-```text
-feat(security-core): add PKCE utility for authorization flows
-fix(data-mongo-sync): resolve tenant context leak
-```
-
-### PR Description Template
-
-```markdown
-## What does this PR do?
-
-Brief description of the change.
-
-## Why?
-
-Motivation for the change.
-
-## How was it tested?
-
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] Manual testing performed
-
-## Checklist
-
-- [ ] No secrets in code or tests
-- [ ] All new endpoints have authorization rules
-- [ ] New DB queries are tenant-scoped
-- [ ] Input validation on all new DTOs
-- [ ] No breaking changes (or breaking changes are documented)
-```
-
-### Review Checklist (for Reviewers)
-
-- [ ] Code follows established patterns (constructor injection, Lombok, multi-tenancy)
-- [ ] New functionality is tested
-- [ ] Security considerations are addressed (tenant scope, input validation, no secrets)
-- [ ] Error handling uses the standard exception hierarchy
-- [ ] No performance regressions (N+1 queries, missing indexes)
-
----
-
-## Versioning
-
-All modules are versioned together using `${revision}` in the parent POM. Version bumps are managed by the maintainers. Contributors do not need to update the version number in PRs.
-
-The version follows [Semantic Versioning](https://semver.org/):
-- **Major:** Breaking API changes
-- **Minor:** New backward-compatible features
-- **Patch:** Backward-compatible bug fixes
-
----
-
-## Adding a New Module
-
-When adding a new module to the library:
-
-1. Create the module directory following the existing naming convention (`openframe-<name>/`)
-2. Add a `pom.xml` that inherits from the parent
-3. Add the module to the parent `pom.xml` `<modules>` section
-4. Add the module to `<dependencyManagement>` in the parent with `${revision}`
-5. Write unit tests before submitting
-6. Update the README and architecture documentation
-
-```xml
-<!-- Parent pom.xml: modules section -->
-<module>openframe-my-new-module</module>
-
-<!-- Parent pom.xml: dependencyManagement -->
-<dependency>
-    <groupId>com.openframe.oss</groupId>
-    <artifactId>openframe-my-new-module</artifactId>
-    <version>${revision}</version>
-</dependency>
-```
-
----
-
-## Getting Help
-
-Stuck on a contribution? Reach out on the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) in `#openframe-dev`.
diff --git a/docs/development/security/README.md b/docs/development/security/README.md
deleted file mode 100644
index 36431181f..000000000
--- a/docs/development/security/README.md
+++ /dev/null
@@ -1,292 +0,0 @@
-# Security Best Practices
-
-This guide covers the security patterns, conventions, and requirements for developing with and contributing to **openframe-oss-lib**.
-
----
-
-## Authentication and Authorization Patterns
-
-### JWT-Based Authentication
-
-Every service in OpenFrame uses JWT bearer tokens for authentication. The library provides:
-
-- **`openframe-security-core`** — JWT encoder/decoder beans, RSA key loading
-- **`openframe-authorization-service-core`** — Multi-tenant OAuth2 Authorization Server
-- **`openframe-gateway-service-core`** — Multi-issuer JWT validation at the edge
-
-**Key principle:** JWTs are issued per-tenant with tenant-scoped RSA key pairs. Never use a shared signing key across tenants.
-
-#### JWT Claims Structure
-
-Every access token must contain:
-
-| Claim | Description |
-|-------|-------------|
-| `tenant_id` | Tenant identifier for multi-tenancy |
-| `userId` | Authenticated user's ID |
-| `roles` | User roles (`ADMIN`, `OWNER`, `AGENT`) |
-| `iss` | Issuer URL (tenant-specific) |
-| `exp` | Expiration timestamp |
-
-```java
-// Correct: Extract tenant from JWT principal
-@GetMapping("/me")
-public ResponseEntity<?> getCurrentUser(@AuthenticationPrincipal Jwt jwt) {
-    String tenantId = jwt.getClaimAsString("tenant_id");
-    String userId = jwt.getClaimAsString("userId");
-    // ...
-}
-```
-
-### Multi-Tenant Key Isolation
-
-Each tenant has its own RSA key pair managed by `TenantKeyService`:
-
-```mermaid
-flowchart LR
-    Token["JWT Signing Request"] --> CTX["TenantContext.getTenantId()"]
-    CTX --> KS["TenantKeyService.getOrCreateActiveKey()"]
-    KS --> DB["MongoDB: TenantKey collection"]
-    KS --> RSA["RSA Key Pair"]
-    RSA --> JWT["Signed JWT"]
-```
-
-> **Never** share RSA key material between tenants or inject keys via environment variables in production. Always use the `TenantKeyService` for key lifecycle management.
-
-### Role-Based Access Control
-
-Gateway-level role enforcement is configured in `GatewaySecurityConfig`:
-
-| Path Pattern | Required Role |
-|-------------|--------------|
-| `/api/**` | `ADMIN` |
-| `/tools/agent/**` | `AGENT` |
-| `/ws/tools/agent/**` | `AGENT` |
-| `/ws/nats` | `ADMIN` or `AGENT` |
-| `/external-api/**` | API key (no JWT required) |
-
-When adding new routes, always explicitly define authorization rules. Never rely on implicit `permitAll()` for sensitive endpoints.
-
----
-
-## OAuth2 Best Practices
-
-### PKCE (Proof Key for Code Exchange)
-
-All browser-initiated authorization flows **must** use PKCE. The `PKCEUtils` class provides:
-
-```java
-// Always use PKCE for browser flows
-String codeVerifier = PKCEUtils.generateCodeVerifier();
-String codeChallenge = PKCEUtils.generateCodeChallenge(codeVerifier);
-String state = PKCEUtils.generateState();
-```
-
-Never implement custom PKCE logic — use the provided utility class.
-
-### Token Storage
-
-Tokens are stored as **HTTP-only cookies** by the OAuth BFF controller. This pattern prevents XSS-based token theft:
-
-```text
-Set-Cookie: access_token=...; HttpOnly; Secure; SameSite=Strict
-Set-Cookie: refresh_token=...; HttpOnly; Secure; SameSite=Strict
-```
-
-> **Never** expose tokens in JavaScript-accessible storage (localStorage, sessionStorage) or URL parameters.
-
-### API Keys
-
-External API consumers authenticate via `X-API-Key` header. API keys follow a two-part format:
-
-```text
-X-API-Key: <keyId>.<secretKey>
-```
-
-Key security requirements:
-
-- Store only the **hashed** secret in MongoDB (`ApiKey.secretHash`)
-- Never log raw API key values
-- Apply rate limiting via `RateLimitService` for all API key–authenticated routes
-- Rotate API keys on suspected compromise
-
----
-
-## Data Encryption and Secure Storage
-
-### Encryption Service
-
-The `openframe-core-crypto` module provides symmetric encryption for sensitive fields stored in MongoDB:
-
-```java
-@Autowired
-private EncryptionService encryptionService;
-
-// Encrypt before storing
-String encrypted = encryptionService.encrypt(plainText);
-
-// Decrypt on read
-String plain = encryptionService.decrypt(encrypted);
-```
-
-Fields that should always be encrypted in MongoDB:
-
-- Tool credentials (`ToolCredentials`)
-- API key secrets (`ApiKey.secretHash` — hashed, not encrypted)
-- SSO provider client secrets (`SSOConfig`)
-
-### Password Hashing
-
-Passwords are hashed using BCrypt via the `PasswordEncoder` bean provided by `ManagementConfiguration`:
-
-```java
-// Correct: Always hash passwords before storing
-String hashed = passwordEncoder.encode(rawPassword);
-
-// Correct: Verify passwords using the encoder
-boolean matches = passwordEncoder.matches(rawPassword, hashed);
-```
-
-Never store raw passwords in any form — not in logs, databases, or environment variables.
-
----
-
-## Input Validation and Sanitization
-
-### Bean Validation
-
-All request DTOs must use Jakarta Bean Validation annotations:
-
-```java
-@NotNull
-@ValidEmail          // Custom OpenFrame validator
-private String email;
-
-@NotBlank
-@TenantDomain        // Custom OpenFrame validator
-private String tenantDomain;
-```
-
-Custom validators in `openframe-core`:
-
-| Annotation | Validates |
-|-----------|----------|
-| `@ValidEmail` | Email format and domain |
-| `@TenantDomain` | Tenant domain slug format |
-
-### SQL / NoSQL Injection Prevention
-
-MongoDB queries are always executed via Spring Data repositories or `MongoTemplate` with typed objects — never with raw string interpolation:
-
-```java
-// Correct: Use typed Spring Data query method
-List<User> users = userRepository.findByTenantIdAndEmail(tenantId, email);
-
-// Wrong: Never build raw query strings
-// mongoTemplate.find(Query.query(Criteria.where("email").is("' OR '1'='1")), User.class);
-```
-
----
-
-## Common Security Vulnerabilities and Mitigations
-
-| Vulnerability | Risk | Mitigation in openframe-oss-lib |
-|-------------|------|-------------------------------|
-| Cross-Tenant Data Access | CRITICAL | TenantContext + tenant-scoped repositories; always include `tenantId` in queries |
-| JWT Token Forgery | HIGH | Per-tenant RSA keys; multi-issuer validation; short expiry |
-| CSRF | MEDIUM | OAuth2 state parameter + PKCE; HTTP-only cookies with SameSite |
-| API Key Exposure | HIGH | Keys hashed at rest; rate limiting; `X-API-Key` header only |
-| XSS Token Theft | HIGH | HTTP-only cookies; CSP headers enforced at gateway |
-| Mass Assignment | MEDIUM | Explicit DTO mapping; never expose domain documents directly |
-| Insecure Direct Object Reference | HIGH | Always scope queries with `tenantId` + authorization checks |
-
----
-
-## Secrets Management
-
-### Local Development
-
-For local development, use `application-local.yml` (never committed) to override sensitive properties:
-
-```yaml
-# application-local.yml (gitignored)
-jwt:
-  private-key: classpath:keys/local-private.pem
-  public-key: classpath:keys/local-public.pem
-spring:
-  data:
-    mongodb:
-      uri: mongodb://localhost:27017/openframe-local
-```
-
-### Environment Variable Conventions
-
-In production deployments, secrets must be injected as environment variables, never hardcoded:
-
-```bash
-# JWT keys
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."
-JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..."
-
-# MongoDB
-SPRING_DATA_MONGODB_URI="mongodb+srv://user:pass@cluster..."
-
-# Redis
-SPRING_DATA_REDIS_HOST="redis.internal"
-```
-
-> Use your platform's secret manager (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets) to inject these values. Never commit secrets to version control.
-
-### CI/CD Secret Handling
-
-GitHub Actions secrets are referenced via:
-
-```yaml
-env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-Never echo, log, or print secrets in CI steps.
-
----
-
-## Security Testing and Code Review Guidelines
-
-### Pre-Commit Checklist
-
-Before opening a Pull Request, verify:
-
-- [ ] No secrets, tokens, or keys in code or test fixtures
-- [ ] All new endpoints have explicit authorization rules
-- [ ] New database queries include `tenantId` scope
-- [ ] Input validation annotations on all request DTOs
-- [ ] Sensitive fields are encrypted at rest
-- [ ] No raw SQL/NoSQL string interpolation
-
-### Integration Test Security
-
-Integration tests should:
-
-- Use randomly generated test data (not hardcoded UUIDs matching production patterns)
-- Clean up test data after each test
-- Never use production URLs or credentials
-
----
-
-## Origin Sanitization
-
-The `OriginSanitizerFilter` in the gateway sanitizes the `Origin` header to prevent header injection attacks. Never bypass this filter for external-facing routes.
-
-```mermaid
-flowchart LR
-    Request["Incoming Request"] --> OSF["OriginSanitizerFilter"]
-    OSF --> AHF["AddAuthorizationHeaderFilter"]
-    AHF --> JWT["JWT Validation"]
-    JWT --> Route["Route Handler"]
-```
-
----
-
-## Reporting Security Issues
-
-For security vulnerabilities, do **not** open a public GitHub issue. Contact the team via the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) in a direct message to the maintainers, or email the security contact listed on [flamingo.run](https://flamingo.run).
diff --git a/docs/development/setup/environment.md b/docs/development/setup/environment.md
deleted file mode 100644
index c2c95cf53..000000000
--- a/docs/development/setup/environment.md
+++ /dev/null
@@ -1,209 +0,0 @@
-# Development Environment Setup
-
-This guide walks you through setting up a complete development environment for **openframe-oss-lib**.
-
----
-
-## IDE Recommendations
-
-### IntelliJ IDEA (Recommended)
-
-IntelliJ IDEA Community or Ultimate is the recommended IDE for this project. It provides the best support for:
-
-- Maven multi-module projects
-- Spring Boot auto-configuration detection
-- Lombok annotation processing
-- Java 21 features (records, virtual threads, sealed classes)
-
-**Download:** [https://www.jetbrains.com/idea/](https://www.jetbrains.com/idea/)
-
-### VS Code (Alternative)
-
-VS Code with the **Extension Pack for Java** is a lighter-weight alternative.
-
-Required extensions:
-
-- Extension Pack for Java (Microsoft)
-- Spring Boot Extension Pack (VMware)
-- Lombok Annotations Support
-
----
-
-## IntelliJ IDEA Setup
-
-### Step 1 — Import the Project
-
-1. Open IntelliJ IDEA
-2. Select **File → Open**
-3. Navigate to the cloned `openframe-oss-lib` directory
-4. Select the root `pom.xml` → click **Open as Project**
-5. Wait for Maven to import all 30+ modules
-
-### Step 2 — Configure Project SDK
-
-1. Open **File → Project Structure → Project**
-2. Set **SDK** to Java 21
-3. Set **Language Level** to `21`
-
-### Step 3 — Enable Annotation Processors (Lombok)
-
-1. Open **Settings → Build, Execution, Deployment → Compiler → Annotation Processors**
-2. Check **Enable annotation processing**
-3. Select **Obtain processors from project classpath**
-
-Without this step, Lombok-generated code will show errors.
-
-### Step 4 — Maven Delegate (Recommended)
-
-1. Open **Settings → Build, Execution, Deployment → Build Tools → Maven → Runner**
-2. Check **Delegate IDE build/run actions to Maven**
-
-This ensures builds use Maven directly rather than IntelliJ's internal compiler, avoiding configuration drift.
-
-### Step 5 — Increase Memory (Optional but Recommended)
-
-Edit `Help → Change Memory Settings` and increase to at least:
-
-```text
-Xmx: 4096 MB
-```
-
----
-
-## VS Code Setup
-
-Install the Extension Pack for Java:
-
-```bash
-code --install-extension vscjava.vscode-java-pack
-code --install-extension vmware.vscode-spring-boot
-```
-
-Add to `.vscode/settings.json` in your workspace:
-
-```json
-{
-  "java.configuration.runtimes": [
-    {
-      "name": "JavaSE-21",
-      "path": "/path/to/jdk-21"
-    }
-  ],
-  "java.compile.nullAnalysis.mode": "disabled",
-  "maven.executable.path": "/path/to/mvn"
-}
-```
-
----
-
-## Required Development Tools
-
-| Tool | Installation |
-|------|-------------|
-| Java 21 JDK | [Adoptium Temurin 21](https://adoptium.net/) |
-| Maven 3.9+ | [https://maven.apache.org/download.cgi](https://maven.apache.org/download.cgi) |
-| Docker Desktop | [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/) |
-| Git | System package manager or [https://git-scm.com/](https://git-scm.com/) |
-
----
-
-## Environment Variables for Development
-
-Set these in your shell profile (`~/.bashrc`, `~/.zshrc`, or equivalent):
-
-```bash
-# Java 21 home (adjust path for your OS and distribution)
-export JAVA_HOME=/path/to/jdk-21
-export PATH="$JAVA_HOME/bin:$PATH"
-
-# Increase Maven heap for large multi-module builds
-export MAVEN_OPTS="-Xmx4g -XX:MaxMetaspaceSize=512m"
-
-# GitHub Packages credentials (required for dependency resolution)
-export GITHUB_ACTOR="your-github-username"
-export GITHUB_TOKEN="your-github-pat"
-```
-
-> Note: `$GITHUB_TOKEN` must have `read:packages` permission to resolve OSS library dependencies.
-
----
-
-## Git Configuration
-
-Configure your Git identity:
-
-```bash
-git config --global user.name "Your Name"
-git config --global user.email "your-email@example.com"
-```
-
-Configure line endings (important for cross-platform teams):
-
-```bash
-# macOS / Linux
-git config --global core.autocrlf input
-
-# Windows
-git config --global core.autocrlf true
-```
-
----
-
-## Useful Maven Commands
-
-| Command | Purpose |
-|---------|---------|
-| `mvn install -DskipTests` | Build all modules, skip tests |
-| `mvn test -pl openframe-core` | Run unit tests for a specific module |
-| `mvn verify -pl openframe-data-mongo-sync` | Run integration tests for a module |
-| `mvn clean install -DskipTests` | Clean build all modules |
-| `mvn dependency:tree -pl openframe-api-service-core` | View dependency tree |
-| `mvn versions:display-dependency-updates` | Check for dependency updates |
-| `mvn flatten:flatten` | Apply CI-friendly version flattening |
-
----
-
-## Checkstyle and Code Quality (Optional)
-
-The project uses standard Spring Boot conventions. For consistent code style:
-
-- Java files follow standard Java conventions
-- Lombok reduces boilerplate (avoid raw getters/setters when Lombok `@Data`, `@Value`, etc. apply)
-- Import ordering follows IntelliJ defaults
-
----
-
-## Docker Configuration
-
-Docker is required for integration tests via Testcontainers. Ensure:
-
-```bash
-# Docker daemon is running
-docker info
-
-# Pull commonly used images in advance for faster test runs
-docker pull mongo:7
-docker pull nats:2
-```
-
-Testcontainers will automatically manage container lifecycle during tests.
-
----
-
-## Verification
-
-After completing setup, verify everything works:
-
-```bash
-# Full build with tests skipped
-mvn install -DskipTests
-
-# Run unit tests for core module
-mvn test -pl openframe-core
-
-# Check Java version is 21
-java -version
-
-# Check Maven version is 3.9+
-mvn -version
-```
diff --git a/docs/development/setup/local-development.md b/docs/development/setup/local-development.md
deleted file mode 100644
index 6fa2f1815..000000000
--- a/docs/development/setup/local-development.md
+++ /dev/null
@@ -1,218 +0,0 @@
-# Local Development Guide
-
-This guide covers everything you need to work with **openframe-oss-lib** locally: cloning, building, iterating, and debugging.
-
----
-
-## Clone and Initial Setup
-
-```bash
-# 1. Clone the repository
-git clone https://github.com/flamingo-stack/openframe-oss-lib.git
-cd openframe-oss-lib
-
-# 2. Verify Java 21 is active
-java -version
-
-# 3. Configure GitHub Packages (if not already done)
-# See prerequisites.md for settings.xml configuration
-
-# 4. Build all modules (skip tests for speed)
-mvn install -DskipTests
-```
-
----
-
-## Understanding the Multi-Module Build
-
-This is a Maven multi-module project. Key concepts:
-
-- The **root `pom.xml`** is the **parent POM** — it defines shared dependencies, plugin versions, and the module list
-- Each module has its own `pom.xml` that inherits from the parent
-- **Unified versioning** — all modules share the same version via `${revision}` (currently `5.79.3`)
-- The `flatten-maven-plugin` resolves `${revision}` at build time
-
-### Building a Single Module
-
-```bash
-# Build only openframe-core and its dependencies
-mvn install -pl openframe-core -am -DskipTests
-
-# Build only the security modules
-mvn install -pl openframe-security-core,openframe-security-oauth -am -DskipTests
-```
-
-The `-am` flag (`--also-make`) ensures upstream dependencies are built first.
-
----
-
-## Running Tests
-
-### Unit Tests
-
-Unit tests follow the naming conventions `*Test.java` and `*Tests.java`:
-
-```bash
-# Run unit tests for a specific module
-mvn test -pl openframe-core
-
-# Run all unit tests across the project
-mvn test
-```
-
-### Integration Tests
-
-Integration tests are named `*IT.java` and require Docker (Testcontainers):
-
-```bash
-# Ensure Docker is running first
-docker info
-
-# Run integration tests for MongoDB sync module
-mvn verify -pl openframe-data-mongo-sync
-
-# Run integration tests for NATS module
-mvn verify -pl openframe-data-nats
-```
-
-> Integration tests spin up real service containers (MongoDB, NATS) via Testcontainers. They run during the `verify` phase.
-
-### Running a Specific Test
-
-```bash
-# Run a specific test class
-mvn test -pl openframe-data-mongo-sync -Dtest=NotificationReadStateServiceIT
-
-# Run a specific test method
-mvn test -pl openframe-data-mongo-sync -Dtest="NotificationReadStateServiceIT#shouldMarkNotificationAsRead"
-```
-
----
-
-## Development Workflow
-
-### Typical Feature Development Flow
-
-```mermaid
-graph TD
-    A["Create feature branch"] --> B["Implement changes"]
-    B --> C["Run unit tests: mvn test -pl <module>"]
-    C --> D["Run integration tests: mvn verify -pl <module>"]
-    D --> E["Build full project: mvn install -DskipTests"]
-    E --> F["Open PR to main branch"]
-```
-
-### Watch Mode / Hot Reload
-
-openframe-oss-lib is a **library**, not a standalone application. There is no hot-reload in the traditional sense. Instead, iterate by:
-
-1. Making code changes in the module
-2. Running `mvn install -pl <module> -DskipTests` to install to local `.m2`
-3. Your downstream service (which depends on this library) picks up the new version
-
-For faster iteration in the downstream service:
-
-```bash
-# Install specific module to local repo quickly
-mvn install -pl openframe-security-core -DskipTests -q
-```
-
----
-
-## Debugging
-
-### IntelliJ Remote Debug (for downstream services)
-
-When running a downstream Spring Boot service that uses these library modules, attach the IntelliJ debugger:
-
-1. Run the service with: `mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"`
-2. In IntelliJ: **Run → Edit Configurations → Remote JVM Debug**
-3. Set host to `localhost`, port to `5005`
-4. Click **Debug**
-
-### IntelliJ Test Debugging
-
-Right-click any test class or method → **Debug 'TestName'**. IntelliJ uses Maven's test infrastructure with Lombok annotation processing enabled.
-
----
-
-## Local Docker-Compose for Integration Tests
-
-A `docker-compose.yml` exists for the MongoDB sync integration test environment:
-
-```bash
-# Start MongoDB for manual integration testing
-cd openframe-data-mongo-sync/src/test/docker
-docker-compose up -d
-
-# Run integration tests against the running container
-mvn verify -pl openframe-data-mongo-sync
-```
-
-> For most use cases, Testcontainers handles container lifecycle automatically. The docker-compose file is useful for persistent debugging sessions.
-
----
-
-## Dependency Management
-
-### Adding a New Dependency
-
-1. Add the version property to the root `pom.xml` `<properties>` section (if it's a new dependency)
-2. Add the `<dependency>` entry to `<dependencyManagement>` in the root POM
-3. Reference the dependency in the module's `pom.xml` **without a version**
-
-Example — adding a new library:
-
-```xml
-<!-- Root pom.xml: properties -->
-<my.library.version>1.2.3</my.library.version>
-
-<!-- Root pom.xml: dependencyManagement -->
-<dependency>
-    <groupId>com.example</groupId>
-    <artifactId>my-library</artifactId>
-    <version>${my.library.version}</version>
-</dependency>
-
-<!-- Module pom.xml: dependencies (no version needed) -->
-<dependency>
-    <groupId>com.example</groupId>
-    <artifactId>my-library</artifactId>
-</dependency>
-```
-
----
-
-## Common Issues
-
-| Issue | Solution |
-|-------|---------|
-| `Cannot resolve symbol` (Lombok) | Enable annotation processing in IDE settings |
-| Tests fail with `Connection refused` | Start Docker before running integration tests |
-| `${revision}` not resolved | Run `mvn flatten:flatten` or upgrade Maven to 3.9+ |
-| Slow builds | Use `-DskipTests`, `-T4` (parallel builds), or `-pl module -am` |
-| `dependency:resolve` fails | Check `~/.m2/settings.xml` for GitHub Packages credentials |
-
----
-
-## Useful Development Aliases
-
-Add to your shell profile for convenience:
-
-```bash
-# Build specific module quickly
-alias mbi='mvn install -DskipTests'
-alias mbt='mvn test'
-alias mbv='mvn verify'
-
-# Build and install a specific module
-function mbm() {
-  mvn install -pl "$1" -am -DskipTests
-}
-```
-
-Usage:
-
-```bash
-mbm openframe-security-core
-```
diff --git a/docs/development/testing/README.md b/docs/development/testing/README.md
deleted file mode 100644
index 6bd092b81..000000000
--- a/docs/development/testing/README.md
+++ /dev/null
@@ -1,295 +0,0 @@
-# Testing Overview
-
-This guide describes the testing strategy, structure, and conventions used across **openframe-oss-lib**.
-
----
-
-## Test Structure and Organization
-
-Tests are co-located with their source code in the standard Maven layout:
-
-```text
-openframe-<module>/
-├── src/
-│   ├── main/java/com/openframe/...        # Production code
-│   └── test/java/com/openframe/...        # Test code
-│       ├── com/openframe/.../FooTest.java  # Unit test
-│       └── com/openframe/.../FooIT.java    # Integration test
-```
-
-### Naming Conventions
-
-| Convention | Type | Lifecycle Phase |
-|-----------|------|----------------|
-| `*Test.java` | Unit test | `mvn test` (Surefire) |
-| `*Tests.java` | Unit test | `mvn test` (Surefire) |
-| `*TestCase.java` | Unit test | `mvn test` (Surefire) |
-| `*IT.java` | Integration test | `mvn verify` (Failsafe) |
-
-The Maven Surefire plugin in the parent POM is configured to include all four patterns:
-
-```xml
-<includes>
-    <include>**/Test*.java</include>
-    <include>**/*Test.java</include>
-    <include>**/*Tests.java</include>
-    <include>**/*TestCase.java</include>
-    <include>**/*IT.java</include>
-</includes>
-```
-
----
-
-## Running Tests
-
-### All Unit Tests
-
-```bash
-# Run all unit tests across the entire project
-mvn test
-
-# Run unit tests for a specific module
-mvn test -pl openframe-core
-mvn test -pl openframe-data-nats
-mvn test -pl openframe-data-pinot
-```
-
-### Integration Tests
-
-Integration tests require a running Docker daemon (Testcontainers):
-
-```bash
-# Run integration tests for a specific module
-mvn verify -pl openframe-data-mongo-sync
-
-# Run integration + unit tests for a module
-mvn verify -pl openframe-api-service-core
-
-# Run all integration tests (may be slow — requires Docker)
-mvn verify
-```
-
-### Skipping Tests
-
-```bash
-# Skip all tests during build
-mvn install -DskipTests
-
-# Skip integration tests only
-mvn install -DskipITs
-
-# Run only unit tests (skip integration)
-mvn test -DskipITs
-```
-
----
-
-## Integration Test Infrastructure
-
-### Testcontainers
-
-Integration tests use [Testcontainers](https://testcontainers.com/) for infrastructure dependencies. Containers are automatically started and stopped per test class or suite.
-
-**MongoDB Integration Tests:**
-
-```java
-// Base class pattern used in openframe-data-mongo-sync
-@SpringBootTest(classes = IntegrationTestApplication.class)
-@ActiveProfiles("integration")
-public abstract class BaseMongoIntegrationTest {
-    // Testcontainers manages MongoDB lifecycle
-}
-```
-
-**NATS Integration Tests:**
-
-```java
-// Base class pattern in openframe-data-nats
-@SpringBootTest(classes = PublisherIntegrationTestApplication.class)
-public abstract class BaseIntegrationTest {
-    // Testcontainers manages NATS lifecycle
-}
-```
-
-### Docker Compose (Alternative)
-
-For manual testing sessions, a Docker Compose file is available for MongoDB:
-
-```bash
-cd openframe-data-mongo-sync/src/test/docker
-docker-compose up -d
-```
-
----
-
-## Test Utilities
-
-### `openframe-test-service-core`
-
-This dedicated module provides reusable test infrastructure for **end-to-end and integration testing** of OpenFrame services:
-
-| Class | Purpose |
-|-------|---------|
-| `AuthHelper` | Authentication flow helpers |
-| `RequestSpecHelper` | REST-Assured request specification builders |
-| `AuthGenerator` | Generate test authentication tokens |
-| `OrganizationGenerator` | Generate test organization data |
-| `DeviceGenerator` | Generate test device data |
-| `TicketGenerator` | Generate test ticket data |
-| `NotificationFixtures` | Pre-built notification test data |
-
-Example usage:
-
-```java
-@Autowired
-private OrganizationGenerator organizationGenerator;
-
-@Test
-void shouldCreateOrganization() {
-    var org = organizationGenerator.createOrganization("Test Org");
-    assertThat(org.getId()).isNotNull();
-}
-```
-
-### GraphQL Test Helpers
-
-GraphQL integration tests use pre-built query helpers:
-
-```java
-// Available in openframe-test-service-core
-DeviceQueries.listDevices(filterInput)
-OrganizationQueries.listOrganizations(filterInput)
-TicketQueries.listTickets(filterInput)
-```
-
----
-
-## Writing New Tests
-
-### Unit Test Template
-
-```java
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.extension.ExtendWith;
-import org.mockito.InjectMocks;
-import org.mockito.Mock;
-import org.mockito.junit.jupiter.MockitoExtension;
-
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.mockito.Mockito.when;
-
-@ExtendWith(MockitoExtension.class)
-class MyServiceTest {
-
-    @Mock
-    private MyRepository repository;
-
-    @InjectMocks
-    private MyService service;
-
-    @Test
-    void shouldReturnExpectedResult() {
-        // Given
-        when(repository.findById("id-1")).thenReturn(Optional.of(new MyEntity("id-1")));
-
-        // When
-        var result = service.getById("id-1");
-
-        // Then
-        assertThat(result).isPresent();
-        assertThat(result.get().getId()).isEqualTo("id-1");
-    }
-}
-```
-
-### Integration Test Template (MongoDB)
-
-```java
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.Test;
-import org.springframework.beans.factory.annotation.Autowired;
-
-class MyRepositoryIT extends BaseMongoIntegrationTest {
-
-    @Autowired
-    private MyRepository repository;
-
-    @AfterEach
-    void cleanup() {
-        repository.deleteAll();
-    }
-
-    @Test
-    void shouldPersistAndRetrieveEntity() {
-        // Given
-        var entity = new MyEntity("test-id", "test-name");
-        repository.save(entity);
-
-        // When
-        var found = repository.findById("test-id");
-
-        // Then
-        assertThat(found).isPresent();
-        assertThat(found.get().getName()).isEqualTo("test-name");
-    }
-}
-```
-
-### Naming and Structure Conventions
-
-- Use **Given / When / Then** structure in test methods
-- Test method names should describe behavior: `shouldReturnNotFoundWhenEntityDoesNotExist`
-- One assertion concept per test where possible
-- Always clean up test data in `@AfterEach` for integration tests
-- Use `@DisplayName` for complex test scenarios
-
----
-
-## Test Coverage
-
-The project does not enforce a specific line coverage percentage, but the following guidelines apply:
-
-| Component Type | Expected Coverage |
-|---------------|------------------|
-| Core utilities (`openframe-core`, `openframe-exception`) | High (>80%) |
-| Domain services | Medium-High (>70%) |
-| Configuration classes | Low (Spring-managed beans) |
-| Repository implementations | Covered by integration tests |
-
-Focus on **behavioral coverage** (testing what the code does) over line coverage metrics.
-
----
-
-## Notification Integration Tests
-
-The notification subsystem has particularly thorough integration test coverage in `openframe-data-mongo-sync`:
-
-| Test Class | What It Tests |
-|-----------|--------------|
-| `NotificationContextDispatchIT` | Notification dispatch with custom context |
-| `NotificationReadStateIndexesIT` | MongoDB index usage for read state |
-| `NotificationLoadTestIT` | Load and performance testing |
-| `NotificationReadStateIndexUsageIT` | Query plan analysis |
-| `CustomNotificationRepositoryPaginationIT` | Cursor-based notification pagination |
-
-Run them with:
-
-```bash
-mvn verify -pl openframe-data-mongo-sync -Dtest=Notification*IT
-```
-
----
-
-## Pinot Repository Tests
-
-The `openframe-data-pinot` module contains unit tests for query building:
-
-```bash
-mvn test -pl openframe-data-pinot
-```
-
-Key test classes:
-
-- `PinotQueryBuilderTest` — Validates SQL query generation
-- `PinotClientDeviceRepositoryTest` — Device query logic
-- `PinotClientLogRepositoryTest` — Log query logic
diff --git a/docs/diagrams/architecture/.gitignore b/docs/diagrams/architecture/.gitignore
deleted file mode 100644
index b4f4c7a6c..000000000
--- a/docs/diagrams/architecture/.gitignore
+++ /dev/null
@@ -1,8 +0,0 @@
-# CodeWiki temp files (dependency graphs can be 7GB+)
-temp/
-dependency_graphs/
-
-# JSON intermediate files (except schema/config)
-*.json
-!*-schema.json
-!*-config.json
diff --git a/docs/diagrams/architecture/README-2.mmd b/docs/diagrams/architecture/README-2.mmd
deleted file mode 100644
index f0028d3df..000000000
--- a/docs/diagrams/architecture/README-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Browser --> AuthController["Auth Controllers"]
-    AuthController --> TenantContext["TenantContextFilter"]
-    TenantContext --> AuthServer["AuthorizationServerConfig"]
-    AuthServer --> TenantKeyService["TenantKeyService"]
-    TenantKeyService --> Mongo
-    AuthServer --> JWT["Signed JWT"]
diff --git a/docs/diagrams/architecture/README-3.mmd b/docs/diagrams/architecture/README-3.mmd
deleted file mode 100644
index 8873c03c9..000000000
--- a/docs/diagrams/architecture/README-3.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Request --> OriginSanitizer
-    OriginSanitizer --> JwtAuth
-    JwtAuth --> RoleCheck
-    RoleCheck --> RouteDecision
-    RouteDecision --> ToolResolver
-    ToolResolver --> UpstreamTool
diff --git a/docs/diagrams/architecture/README-4.mmd b/docs/diagrams/architecture/README-4.mmd
deleted file mode 100644
index 36a3b850e..000000000
--- a/docs/diagrams/architecture/README-4.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    DebeziumEvent --> Deserializer
-    Deserializer --> Enrichment
-    Enrichment --> EventTypeMapper
-    EventTypeMapper --> Cassandra
-    EventTypeMapper --> KafkaOut
diff --git a/docs/diagrams/architecture/README-5.mmd b/docs/diagrams/architecture/README-5.mmd
deleted file mode 100644
index 259b45977..000000000
--- a/docs/diagrams/architecture/README-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    StreamService --> PinotCluster
-    PinotCluster --> PinotRepositories
-    PinotRepositories --> ApiService
diff --git a/docs/diagrams/architecture/README-6.mmd b/docs/diagrams/architecture/README-6.mmd
deleted file mode 100644
index ef6842c36..000000000
--- a/docs/diagrams/architecture/README-6.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Startup --> Initializers
-    Initializers --> StreamsReady
-    StreamsReady --> Schedulers
-    Schedulers --> ExternalSystems
diff --git a/docs/diagrams/architecture/README-7.mmd b/docs/diagrams/architecture/README-7.mmd
deleted file mode 100644
index 2f8a49559..000000000
--- a/docs/diagrams/architecture/README-7.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-sequenceDiagram
-    participant Browser
-    participant BFF
-    participant AuthServer
-
-    Browser->>BFF: GET /oauth/login
-    BFF->>AuthServer: Redirect with PKCE
-    AuthServer->>BFF: Callback with code
-    BFF->>AuthServer: Exchange code
-    BFF->>Browser: Set cookies
diff --git a/docs/diagrams/architecture/README-8.mmd b/docs/diagrams/architecture/README-8.mmd
deleted file mode 100644
index 05e53be6c..000000000
--- a/docs/diagrams/architecture/README-8.mmd
+++ /dev/null
@@ -1,19 +0,0 @@
-flowchart TD
-    Client --> Gateway
-    Gateway --> ExternalAPI
-    Gateway --> ApiCore
-
-    ApiCore --> Authz
-    ApiCore --> Mongo
-    ApiCore --> Redis
-    ApiCore --> Pinot
-
-    Authz --> Mongo
-    Authz --> JWT
-
-    Stream --> Kafka
-    Stream --> Cassandra
-    Stream --> Pinot
-
-    Management --> Redis
-    Management --> NATS
diff --git a/docs/diagrams/architecture/README.mmd b/docs/diagrams/architecture/README.mmd
deleted file mode 100644
index 7f3f41a75..000000000
--- a/docs/diagrams/architecture/README.mmd
+++ /dev/null
@@ -1,15 +0,0 @@
-flowchart TD
-    Client["Client / Browser / Agent"] --> Gateway["Gateway Service Core"]
-    Gateway --> ExternalAPI["External API Service"]
-    Gateway --> ApiCore["API Service Core"]
-
-    ApiCore --> Authz["Authorization Service Core"]
-    ApiCore --> Stream["Stream Service Core"]
-    ApiCore --> Management["Management Service Core"]
-
-    Authz --> Mongo["MongoDB"]
-    ApiCore --> Mongo
-    Stream --> Kafka["Kafka"]
-    Stream --> Pinot["Pinot"]
-    ApiCore --> Redis["Redis"]
-    Management --> NATS["NATS"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination-2.mmd b/docs/diagrams/architecture/api-contracts-and-pagination-2.mmd
deleted file mode 100644
index 171348e9c..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination-2.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    Request["Query Request with Filters"] --> Service["Query Service"]
-    Service --> Repo["Custom Repository"]
-    Repo --> Result["CountedGenericQueryResult<T>"]
-    Result --> API["Serialized API Response"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination-3.mmd b/docs/diagrams/architecture/api-contracts-and-pagination-3.mmd
deleted file mode 100644
index 76d425bb5..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Client["Client"] --> Args["ConnectionArgs"]
-    Args --> Decode["CursorCodec.decode()"]
-    Decode --> Query["Repository Query with Limit"]
-    Query --> Encode["CursorCodec.encode()"]
-    Encode --> Response["Connection Response with Edges"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination-4.mmd b/docs/diagrams/architecture/api-contracts-and-pagination-4.mmd
deleted file mode 100644
index 0bba98fe8..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination-4.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart LR
-    Raw["Raw Internal Cursor"] --> Encode["Base64 Encode"]
-    Encode --> Opaque["Opaque Cursor String"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination-5.mmd b/docs/diagrams/architecture/api-contracts-and-pagination-5.mmd
deleted file mode 100644
index 293cd83af..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination-5.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart LR
-    Opaque["Opaque Cursor"] --> Decode["Base64 Decode"]
-    Decode --> Raw["Raw Internal Cursor"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination-6.mmd b/docs/diagrams/architecture/api-contracts-and-pagination-6.mmd
deleted file mode 100644
index 91f5ede92..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination-6.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Client["Client Mutation"] --> Input["MutationDeleteInput"]
-    Input --> Validate["Validation Layer"]
-    Validate --> Service["Domain Service"]
-    Service --> Repo["Repository Delete by ID"]
-    Repo --> Response["Mutation Result"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination-7.mmd b/docs/diagrams/architecture/api-contracts-and-pagination-7.mmd
deleted file mode 100644
index 62c5f782c..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination-7.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Step1["Client Requests first 20 after Cursor"] --> Step2["ConnectionArgs Validated"]
-    Step2 --> Step3["CursorCodec.decode()"]
-    Step3 --> Step4["Repository Query with Limit 21"]
-    Step4 --> Step5["Determine hasNextPage"]
-    Step5 --> Step6["CursorCodec.encode() for Edges"]
-    Step6 --> Step7["Return Connection Response"]
diff --git a/docs/diagrams/architecture/api-contracts-and-pagination.mmd b/docs/diagrams/architecture/api-contracts-and-pagination.mmd
deleted file mode 100644
index 2e19bb2b8..000000000
--- a/docs/diagrams/architecture/api-contracts-and-pagination.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Client["Client Application"] --> API["REST Controllers / GraphQL DataFetchers"]
-    API --> Contracts["Api Contracts And Pagination"]
-    Contracts --> Services["Domain Query Services"]
-    Services --> Repositories["Mongo Repositories"]
-    Repositories --> Database[("MongoDB")]
diff --git a/docs/diagrams/architecture/api-domain-filters-dtos-2.mmd b/docs/diagrams/architecture/api-domain-filters-dtos-2.mmd
deleted file mode 100644
index 238250c63..000000000
--- a/docs/diagrams/architecture/api-domain-filters-dtos-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    LogFilterCriteria["LogFilterCriteria"] --> DateRange["Date Range"]
-    LogFilterCriteria --> EventTypes["Event Types"]
-    LogFilterCriteria --> ToolTypes["Tool Types"]
-    LogFilterCriteria --> Severities["Severities"]
-    LogFilterCriteria --> Organizations["Organization IDs"]
-    LogFilterCriteria --> Device["Device ID"]
diff --git a/docs/diagrams/architecture/api-domain-filters-dtos-3.mmd b/docs/diagrams/architecture/api-domain-filters-dtos-3.mmd
deleted file mode 100644
index feae0ce16..000000000
--- a/docs/diagrams/architecture/api-domain-filters-dtos-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    DeviceFilterCriteria["DeviceFilterCriteria"] --> Statuses["Device Statuses"]
-    DeviceFilterCriteria --> Types["Device Types"]
-    DeviceFilterCriteria --> OsTypes["OS Types"]
-    DeviceFilterCriteria --> Orgs["Organization IDs"]
-    DeviceFilterCriteria --> Tags["Tag Keys / Values"]
diff --git a/docs/diagrams/architecture/api-domain-filters-dtos-4.mmd b/docs/diagrams/architecture/api-domain-filters-dtos-4.mmd
deleted file mode 100644
index 278d589a8..000000000
--- a/docs/diagrams/architecture/api-domain-filters-dtos-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Organization["Organization (Mongo Document)"] --> OrganizationResponse["OrganizationResponse DTO"]
-    OrganizationResponse --> RestAPI["REST API"]
-    OrganizationResponse --> GraphQL["GraphQL API"]
diff --git a/docs/diagrams/architecture/api-domain-filters-dtos-5.mmd b/docs/diagrams/architecture/api-domain-filters-dtos-5.mmd
deleted file mode 100644
index 779b2cc46..000000000
--- a/docs/diagrams/architecture/api-domain-filters-dtos-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    GraphQLInput["GraphQL Filter Input"] --> Criteria["FilterCriteria DTO"]
-    Criteria --> Service["Query Service"]
-    Service --> MongoFilter["Mongo Query Filter"]
diff --git a/docs/diagrams/architecture/api-domain-filters-dtos-6.mmd b/docs/diagrams/architecture/api-domain-filters-dtos-6.mmd
deleted file mode 100644
index ced28036e..000000000
--- a/docs/diagrams/architecture/api-domain-filters-dtos-6.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    DeviceFilterCriteria --> DeviceQueryFilter["DeviceQueryFilter"]
-    EventFilterCriteria --> EventQueryFilter["EventQueryFilter"]
-    ToolFilterCriteria --> ToolQueryFilter["ToolQueryFilter"]
diff --git a/docs/diagrams/architecture/api-domain-filters-dtos.mmd b/docs/diagrams/architecture/api-domain-filters-dtos.mmd
deleted file mode 100644
index 5a45aaf4d..000000000
--- a/docs/diagrams/architecture/api-domain-filters-dtos.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    Client["Client (REST or GraphQL)"] --> ApiInput["GraphQL Input / REST Request"]
-    ApiInput --> DomainFilter["Api Domain Filters Dtos"]
-    DomainFilter --> QueryLayer["Mongo Query Filters"]
-    QueryLayer --> Repository["Mongo Repositories"]
-    Repository --> Database[("MongoDB")]
diff --git a/docs/diagrams/architecture/api-lib-core-services-2.mmd b/docs/diagrams/architecture/api-lib-core-services-2.mmd
deleted file mode 100644
index 8f71addba..000000000
--- a/docs/diagrams/architecture/api-lib-core-services-2.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    DataLoader["InstalledAgentDataLoader"] --> Service["InstalledAgentService"]
-    Service --> Repo["InstalledAgentRepository"]
-    Repo --> Mongo[("MongoDB")]
diff --git a/docs/diagrams/architecture/api-lib-core-services-3.mmd b/docs/diagrams/architecture/api-lib-core-services-3.mmd
deleted file mode 100644
index 5a2e40ac8..000000000
--- a/docs/diagrams/architecture/api-lib-core-services-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    ToolDataLoader["ToolConnectionDataLoader"] --> ToolService["ToolConnectionService"]
-    ToolService --> ToolRepo["ToolConnectionRepository"]
-    ToolRepo --> Mongo[("MongoDB")]
diff --git a/docs/diagrams/architecture/api-lib-core-services-4.mmd b/docs/diagrams/architecture/api-lib-core-services-4.mmd
deleted file mode 100644
index 45ae4bcf6..000000000
--- a/docs/diagrams/architecture/api-lib-core-services-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    API["API Layer"] --> TicketService["TicketQueryService"]
-    TicketService --> QueryFilter["TicketQueryFilter"]
-    TicketService --> Repo["TicketRepository"]
-    Repo --> Mongo[("MongoDB")]
diff --git a/docs/diagrams/architecture/api-lib-core-services-5.mmd b/docs/diagrams/architecture/api-lib-core-services-5.mmd
deleted file mode 100644
index d07ad4a9b..000000000
--- a/docs/diagrams/architecture/api-lib-core-services-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Save["Save KnowledgeBaseItem"] --> MongoEvent["BeforeConvertEvent"]
-    MongoEvent --> Listener["KnowledgeBasePublishLifecycleListener"]
-    Listener --> Stamp["Set publishedAt if null"]
-    Stamp --> Persist[("MongoDB")]
diff --git a/docs/diagrams/architecture/api-lib-core-services-6.mmd b/docs/diagrams/architecture/api-lib-core-services-6.mmd
deleted file mode 100644
index 7181e803f..000000000
--- a/docs/diagrams/architecture/api-lib-core-services-6.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart LR
-    DeviceStatusUpdate["Machine Status Updated"] --> Processor["DeviceStatusProcessor"]
-    Processor --> DefaultImpl["DefaultDeviceStatusProcessor"]
diff --git a/docs/diagrams/architecture/api-lib-core-services-7.mmd b/docs/diagrams/architecture/api-lib-core-services-7.mmd
deleted file mode 100644
index 91e5a1f40..000000000
--- a/docs/diagrams/architecture/api-lib-core-services-7.mmd
+++ /dev/null
@@ -1,13 +0,0 @@
-flowchart TD
-    Client["GraphQL Client"] --> DataFetcher["MachineDataFetcher"]
-    DataFetcher --> AgentLoader["InstalledAgentDataLoader"]
-    DataFetcher --> ToolLoader["ToolConnectionDataLoader"]
-
-    AgentLoader --> AgentService["InstalledAgentService"]
-    ToolLoader --> ToolService["ToolConnectionService"]
-
-    AgentService --> AgentRepo["InstalledAgentRepository"]
-    ToolService --> ToolRepo["ToolConnectionRepository"]
-
-    AgentRepo --> Mongo[("MongoDB")]
-    ToolRepo --> Mongo
diff --git a/docs/diagrams/architecture/api-lib-core-services.mmd b/docs/diagrams/architecture/api-lib-core-services.mmd
deleted file mode 100644
index 86fb571e2..000000000
--- a/docs/diagrams/architecture/api-lib-core-services.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Controllers["REST Controllers"] --> Services["Api Lib Core Services"]
-    DataFetchers["GraphQL Data Fetchers"] --> Services
-    Services --> Repositories["Mongo Repositories"]
-    Repositories --> MongoDB[("MongoDB")]
-
-    Services --> Processors["Domain Processors"]
diff --git a/docs/diagrams/architecture/api-organization-mapping-2.mmd b/docs/diagrams/architecture/api-organization-mapping-2.mmd
deleted file mode 100644
index 7964c3000..000000000
--- a/docs/diagrams/architecture/api-organization-mapping-2.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    Request["CreateOrganizationRequest"] --> MapperCreate["toEntity()"]
-    MapperCreate --> GenId["Generate UUID"]
-    MapperCreate --> MapFields["Map Scalar Fields"]
-    MapperCreate --> MapContact["Map Contact Information"]
-    MapContact --> MapAddress["Map Address"]
-    MapContact --> MapContacts["Map Contact Persons"]
-    GenId --> OrgEntity["Organization Entity"]
-    MapFields --> OrgEntity
-    MapContact --> OrgEntity
diff --git a/docs/diagrams/architecture/api-organization-mapping-3.mmd b/docs/diagrams/architecture/api-organization-mapping-3.mmd
deleted file mode 100644
index 4b4b0d04a..000000000
--- a/docs/diagrams/architecture/api-organization-mapping-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    UpdateRequest["UpdateOrganizationRequest"] --> CheckField["Field != null?"]
-    CheckField -->|"Yes"| ApplyUpdate["Set Field on Entity"]
-    CheckField -->|"No"| Skip["Keep Existing Value"]
-    ApplyUpdate --> OrgEntity["Updated Organization"]
-    Skip --> OrgEntity
diff --git a/docs/diagrams/architecture/api-organization-mapping-4.mmd b/docs/diagrams/architecture/api-organization-mapping-4.mmd
deleted file mode 100644
index 24ccc880a..000000000
--- a/docs/diagrams/architecture/api-organization-mapping-4.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart LR
-    OrgEntity["Organization Entity"] --> MapperResponse["toResponse()"]
-    MapperResponse --> MapScalars["Map Scalar Fields"]
-    MapperResponse --> MapStatus["Enum to String"]
-    MapperResponse --> MapNested["Map Contact Information DTO"]
-    MapScalars --> Response["OrganizationResponse"]
-    MapStatus --> Response
-    MapNested --> Response
diff --git a/docs/diagrams/architecture/api-organization-mapping-5.mmd b/docs/diagrams/architecture/api-organization-mapping-5.mmd
deleted file mode 100644
index 1a2d95abc..000000000
--- a/docs/diagrams/architecture/api-organization-mapping-5.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Dto["ContactInformationDto"] --> CheckFlag{{"Same As Physical?"}}
-    CheckFlag -->|"Yes"| CopyAddr["Copy Physical Address"]
-    CheckFlag -->|"No"| MapMail["Map Mailing Address"]
-    CopyAddr --> Entity["ContactInformation Entity"]
-    MapMail --> Entity
diff --git a/docs/diagrams/architecture/api-organization-mapping-6.mmd b/docs/diagrams/architecture/api-organization-mapping-6.mmd
deleted file mode 100644
index 46c956ee5..000000000
--- a/docs/diagrams/architecture/api-organization-mapping-6.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-flowchart LR
-    Client["Client App"] --> RestAPI["REST or GraphQL API"]
-    RestAPI --> MapperCreate["OrganizationMapper"]
-    MapperCreate --> Service["Organization Service"]
-    Service --> Repo["Mongo Repository"]
-    Repo --> DB["MongoDB"]
-    DB --> Repo
-    Repo --> Service
-    Service --> MapperResponse["OrganizationMapper"]
-    MapperResponse --> RestAPI
-    RestAPI --> Client
diff --git a/docs/diagrams/architecture/api-organization-mapping.mmd b/docs/diagrams/architecture/api-organization-mapping.mmd
deleted file mode 100644
index 38fda5d45..000000000
--- a/docs/diagrams/architecture/api-organization-mapping.mmd
+++ /dev/null
@@ -1,23 +0,0 @@
-flowchart LR
-    subgraph ApiLayer["API Layer"]
-        RestController["OrganizationController"]
-        GraphQLFetcher["OrganizationDataFetcher"]
-    end
-
-    Mapper["OrganizationMapper"]
-
-    subgraph DomainLayer["Domain & Persistence"]
-        OrgEntity["Organization Entity"]
-        MongoRepo["Mongo Repository"]
-    end
-
-    RestController -->|"Create/Update Request"| Mapper
-    GraphQLFetcher -->|"Mutation Input"| Mapper
-
-    Mapper -->|"Entity"| OrgEntity
-    OrgEntity --> MongoRepo
-
-    MongoRepo --> OrgEntity
-    OrgEntity -->|"Response DTO"| Mapper
-    Mapper -->|"OrganizationResponse"| RestController
-    Mapper -->|"GraphQL DTO"| GraphQLFetcher
diff --git a/docs/diagrams/architecture/api-service-core-config-and-security-2.mmd b/docs/diagrams/architecture/api-service-core-config-and-security-2.mmd
deleted file mode 100644
index 1d4c2908b..000000000
--- a/docs/diagrams/architecture/api-service-core-config-and-security-2.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Request["HTTP Request"] --> Security["OAuth2 Resource Server"]
-    Security --> Controller["Controller Method"]
-    Controller --> Resolver["AuthPrincipalArgumentResolver"]
-    Resolver --> Principal["AuthPrincipal Injected"]
diff --git a/docs/diagrams/architecture/api-service-core-config-and-security-3.mmd b/docs/diagrams/architecture/api-service-core-config-and-security-3.mmd
deleted file mode 100644
index 5c7317a24..000000000
--- a/docs/diagrams/architecture/api-service-core-config-and-security-3.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    Incoming["Incoming Request with JWT"] --> ExtractIssuer["Extract iss Claim"]
-    ExtractIssuer --> CacheCheck["Check JwtAuthenticationProvider Cache"]
-    CacheCheck -->|"Miss"| CreateDecoder["Create JwtDecoder from Issuer"]
-    CreateDecoder --> StoreCache["Store in Caffeine Cache"]
-    CacheCheck -->|"Hit"| UseProvider["Reuse Cached Provider"]
-    StoreCache --> Authenticate["Authenticate JWT"]
-    UseProvider --> Authenticate
-    Authenticate --> Principal["SecurityContext Updated"]
diff --git a/docs/diagrams/architecture/api-service-core-config-and-security-4.mmd b/docs/diagrams/architecture/api-service-core-config-and-security-4.mmd
deleted file mode 100644
index da7c9a7a1..000000000
--- a/docs/diagrams/architecture/api-service-core-config-and-security-4.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Startup["Application Startup"] --> LoadProps["Read OAuth Properties"]
-    LoadProps --> QueryRepo["Find Client by ID"]
-    QueryRepo -->|"Exists"| CompareSecret["Compare Secrets"]
-    CompareSecret -->|"Different"| UpdateSecret["Update and Save"]
-    CompareSecret -->|"Same"| Skip["No Action"]
-    QueryRepo -->|"Missing"| CreateClient["Create OAuthClient"]
diff --git a/docs/diagrams/architecture/api-service-core-config-and-security-5.mmd b/docs/diagrams/architecture/api-service-core-config-and-security-5.mmd
deleted file mode 100644
index e5f850975..000000000
--- a/docs/diagrams/architecture/api-service-core-config-and-security-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    GraphQLInput["GraphQL Query Input"] --> Scalar["Custom Scalar Coercing"]
-    Scalar --> Validation["Format Validation"]
-    Validation --> Parsed["Java Type (LocalDate / Instant / Long)"]
-    Parsed --> DataFetcher["Data Fetcher Execution"]
diff --git a/docs/diagrams/architecture/api-service-core-config-and-security-6.mmd b/docs/diagrams/architecture/api-service-core-config-and-security-6.mmd
deleted file mode 100644
index 265582add..000000000
--- a/docs/diagrams/architecture/api-service-core-config-and-security-6.mmd
+++ /dev/null
@@ -1,14 +0,0 @@
-sequenceDiagram
-    participant Client
-    participant Gateway
-    participant Api as "API Service"
-    participant Security as "SecurityConfig"
-    participant Controller
-
-    Client->>Gateway: Request with Cookie or Token
-    Gateway->>Gateway: Validate JWT
-    Gateway->>Api: Forward request with Authorization header
-    Api->>Security: Resolve issuer and authenticate
-    Security->>Api: Populate SecurityContext
-    Api->>Controller: Invoke handler
-    Controller->>Controller: Inject AuthPrincipal
diff --git a/docs/diagrams/architecture/api-service-core-config-and-security.mmd b/docs/diagrams/architecture/api-service-core-config-and-security.mmd
deleted file mode 100644
index da769acb9..000000000
--- a/docs/diagrams/architecture/api-service-core-config-and-security.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart LR
-    Gateway["Gateway Service"] -->|"JWT Forwarded"| ApiService["API Service Runtime"]
-    ApiService -->|"Uses"| ConfigModule["Api Service Core Config And Security"]
-    ApiService --> Controllers["REST Controllers"]
-    ApiService --> GraphQL["GraphQL Data Fetchers"]
-    ApiService --> Services["Domain Services"]
-    Services --> DataLayer["Mongo / Kafka / Redis"]
diff --git a/docs/diagrams/architecture/api-service-core-dataloaders-2.mmd b/docs/diagrams/architecture/api-service-core-dataloaders-2.mmd
deleted file mode 100644
index 0d3879f3c..000000000
--- a/docs/diagrams/architecture/api-service-core-dataloaders-2.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-sequenceDiagram
-    participant Resolver as "GraphQL Resolver"
-    participant Loader as "DataLoader"
-    participant Service as "Service/Repository"
-
-    Resolver->>Loader: load([id1, id2, id3])
-    Loader->>Service: Batch fetch entities
-    Service-->>Loader: List of entities
-    Loader-->>Resolver: Ordered results
diff --git a/docs/diagrams/architecture/api-service-core-dataloaders-3.mmd b/docs/diagrams/architecture/api-service-core-dataloaders-3.mmd
deleted file mode 100644
index 8533426d6..000000000
--- a/docs/diagrams/architecture/api-service-core-dataloaders-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Resolver --> InstalledAgentDataLoader
-    InstalledAgentDataLoader --> InstalledAgentService
-    InstalledAgentService --> Mongo
diff --git a/docs/diagrams/architecture/api-service-core-dataloaders-4.mmd b/docs/diagrams/architecture/api-service-core-dataloaders-4.mmd
deleted file mode 100644
index f66c56913..000000000
--- a/docs/diagrams/architecture/api-service-core-dataloaders-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Resolver --> KnowledgeBaseItemDataLoader
-    KnowledgeBaseItemDataLoader --> KnowledgeBaseItemRepository
-    KnowledgeBaseItemRepository --> Mongo
diff --git a/docs/diagrams/architecture/api-service-core-dataloaders-5.mmd b/docs/diagrams/architecture/api-service-core-dataloaders-5.mmd
deleted file mode 100644
index 85557302f..000000000
--- a/docs/diagrams/architecture/api-service-core-dataloaders-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Resolver --> OrganizationDataLoader
-    OrganizationDataLoader --> OrganizationRepository
-    OrganizationRepository --> Mongo
diff --git a/docs/diagrams/architecture/api-service-core-dataloaders-6.mmd b/docs/diagrams/architecture/api-service-core-dataloaders-6.mmd
deleted file mode 100644
index a624e2aa6..000000000
--- a/docs/diagrams/architecture/api-service-core-dataloaders-6.mmd
+++ /dev/null
@@ -1,20 +0,0 @@
-flowchart TD
-    subgraph graphql_layer["GraphQL Layer"]
-        DF["Data Fetchers"]
-        DL["DataLoaders"]
-    end
-
-    subgraph service_layer["Service Layer"]
-        SVC["Domain Services"]
-    end
-
-    subgraph data_layer["Data Layer"]
-        REPO["Mongo Repositories"]
-        DB[("MongoDB")]
-    end
-
-    DF --> DL
-    DL --> SVC
-    DL --> REPO
-    SVC --> DB
-    REPO --> DB
diff --git a/docs/diagrams/architecture/api-service-core-dataloaders.mmd b/docs/diagrams/architecture/api-service-core-dataloaders.mmd
deleted file mode 100644
index bc6df6f13..000000000
--- a/docs/diagrams/architecture/api-service-core-dataloaders.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Client["GraphQL Client"] --> GQL["GraphQL Data Fetchers"]
-    GQL --> DL["Api Service Core Dataloaders"]
-    DL --> Service["Domain Services"]
-    DL --> Repo["Mongo Repositories"]
-    Service --> Mongo[("MongoDB")]
-    Repo --> Mongo
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-2.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-2.mmd
deleted file mode 100644
index 75dcb15cb..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Query["GraphQL Query"] --> Args["ConnectionArgs"]
-    Args --> Pagination["CursorPaginationCriteria"]
-    Pagination --> ServiceQuery["Service.query(...)"]
-    ServiceQuery --> Result["QueryResult"]
-    Result --> Mapper["GraphQL Mapper"]
-    Mapper --> Connection["Relay Connection"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-3.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-3.mmd
deleted file mode 100644
index 39727fc93..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-3.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart LR
-    Query["devices query"] --> DeviceFetcher
-    DeviceFetcher --> DeviceService
-    DeviceFetcher --> MachineNode["Machine"]
-    MachineNode -->|"tags"| TagLoader
-    MachineNode -->|"installedAgents"| AgentLoader
-    TagLoader --> TagService
-    AgentLoader --> InstalledAgentService
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-4.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-4.mmd
deleted file mode 100644
index 679e3471f..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Mutation["createArticle"] --> GetUser["Extract JWT User"]
-    GetUser --> Mapper
-    Mapper --> Service["KnowledgeBaseService"]
-    Service --> DB["Mongo Repository"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-5.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-5.mmd
deleted file mode 100644
index 7b60b20bd..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-5.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    NodeQuery["node(id)"] --> Decode["Relay.fromGlobalId"]
-    Decode --> TypeSwitch["NodeType enum"]
-    TypeSwitch --> DeviceService
-    TypeSwitch --> OrganizationService
-    TypeSwitch --> EventService
-    TypeSwitch --> ToolService
-    TypeSwitch --> TagService
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-6.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-6.mmd
deleted file mode 100644
index cf844476a..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-6.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Query["notifications"] --> CurrentRecipient
-    CurrentRecipient --> Principal["AuthPrincipal"]
-    Principal --> NotificationService
-    NotificationService --> ReadStateService
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-7.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-7.mmd
deleted file mode 100644
index 24a82acbb..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-7.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    NotificationContext --> Resolver
-    Resolver -->|"type discriminator"| TypeMap
-    TypeMap --> GraphQLType
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-8.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers-8.mmd
deleted file mode 100644
index cf75e6de7..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers-8.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    GraphQL["GraphQL DataFetchers"] --> Services
-    Services --> Domain["Domain Models"]
-    Services --> Repositories
-    Services --> Messaging["NATS / Kafka"]
-    Services --> Cache["Redis"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-datafetchers.mmd b/docs/diagrams/architecture/api-service-core-graphql-datafetchers.mmd
deleted file mode 100644
index fe7cec603..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-datafetchers.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-flowchart LR
-    Client["GraphQL Client"] --> Schema["GraphQL Schema"]
-    Schema --> DataFetchers["DGS DataFetchers"]
-    DataFetchers --> Mappers["GraphQL Mappers"]
-    DataFetchers --> Services["Application Services"]
-    Services --> Repositories["Mongo / Pinot / Cassandra Repositories"]
-
-    DataFetchers --> DataLoaders["DataLoaders (Batching)"]
-    DataLoaders --> Services
-
-    DataFetchers --> Security["SecurityContext + JWT"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-dtos-2.mmd b/docs/diagrams/architecture/api-service-core-graphql-dtos-2.mmd
deleted file mode 100644
index 149360786..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-dtos-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart LR
-    Query["GraphQL Query"] --> Args["Connection Arguments"]
-    Args --> Fetcher["Data Fetcher"]
-    Fetcher --> Service["Service Layer"]
-    Service --> Edge["GenericEdge<T>"]
-    Edge --> Connection["CountedGenericConnection"]
-    Connection --> Client["GraphQL Client"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-dtos-3.mmd b/docs/diagrams/architecture/api-service-core-graphql-dtos-3.mmd
deleted file mode 100644
index 402106ef8..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-dtos-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    GraphQLInput["GraphQL Filter Input"] --> DataFetcher["Data Fetcher"]
-    DataFetcher --> Criteria["Domain Filter Criteria"]
-    Criteria --> Repository["Custom Repository"]
-    Repository --> Results["Domain Documents"]
-    Results --> Connection["Connection DTO"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-dtos-4.mmd b/docs/diagrams/architecture/api-service-core-graphql-dtos-4.mmd
deleted file mode 100644
index c3ebeb57e..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-dtos-4.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Client["GraphQL Mutation"] --> Input["Mutation Input DTO"]
-    Input --> Validation["Bean Validation"]
-    Validation --> Processor["Service or Processor"]
-    Processor --> Repository["Mongo Repository"]
-    Repository --> Response["Response DTO"]
diff --git a/docs/diagrams/architecture/api-service-core-graphql-dtos-5.mmd b/docs/diagrams/architecture/api-service-core-graphql-dtos-5.mmd
deleted file mode 100644
index fb0a10865..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-dtos-5.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    UI["Frontend UI"] --> Query["GraphQL Query or Mutation"]
-    Query --> DTOIn["Input DTO"]
-    DTOIn --> Fetcher["Data Fetcher"]
-    Fetcher --> Service["Core Service"]
-    Service --> Repo["Mongo Repository"]
-    Repo --> Domain["Domain Document"]
-    Domain --> DTOOut["Edge or Response DTO"]
-    DTOOut --> Connection["CountedGenericConnection"]
-    Connection --> UI
diff --git a/docs/diagrams/architecture/api-service-core-graphql-dtos.mmd b/docs/diagrams/architecture/api-service-core-graphql-dtos.mmd
deleted file mode 100644
index 0a767217f..000000000
--- a/docs/diagrams/architecture/api-service-core-graphql-dtos.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Client["GraphQL Client"] --> Schema["GraphQL Schema"]
-    Schema --> DataFetcher["GraphQL Data Fetchers"]
-    DataFetcher --> Dtos["Api Service Core Graphql Dtos"]
-    Dtos --> Services["Core Services"]
-    Services --> Repositories["Mongo Repositories"]
-    Repositories --> Database[("Database")]
diff --git a/docs/diagrams/architecture/api-service-core-relay-type-resolution-2.mmd b/docs/diagrams/architecture/api-service-core-relay-type-resolution-2.mmd
deleted file mode 100644
index 4e1ad0da6..000000000
--- a/docs/diagrams/architecture/api-service-core-relay-type-resolution-2.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    Input["AssignableTarget Object"] --> CheckOrg{"Organization?"}
-    CheckOrg -->|"Yes"| Org["Return Organization"]
-    CheckOrg -->|"No"| CheckMachine{"Machine?"}
-    CheckMachine -->|"Yes"| Machine["Return Machine"]
-    CheckMachine -->|"No"| CheckTicket{"Ticket?"}
-    CheckTicket -->|"Yes"| Ticket["Return Ticket"]
-    CheckTicket -->|"No"| CheckKB{"KnowledgeBaseItem?"}
-    CheckKB -->|"Yes"| KB["Return KnowledgeBaseItem"]
-    CheckKB -->|"No"| Error["Throw IllegalArgumentException"]
diff --git a/docs/diagrams/architecture/api-service-core-relay-type-resolution-3.mmd b/docs/diagrams/architecture/api-service-core-relay-type-resolution-3.mmd
deleted file mode 100644
index 5341a0d37..000000000
--- a/docs/diagrams/architecture/api-service-core-relay-type-resolution-3.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    NodeInput["Node Object"] --> CheckMachine{"Machine?"}
-    CheckMachine -->|"Yes"| ReturnMachine["Return Machine"]
-    CheckMachine -->|"No"| CheckOrg{"Organization?"}
-    CheckOrg -->|"Yes"| ReturnOrg["Return Organization"]
-    CheckOrg -->|"No"| CheckEvent{"Event?"}
-    CheckEvent -->|"Yes"| ReturnEvent["Return Event"]
-    CheckEvent -->|"No"| Continue["Other instanceof checks"]
-    Continue --> ReturnType["Return Matching Type"]
diff --git a/docs/diagrams/architecture/api-service-core-relay-type-resolution-4.mmd b/docs/diagrams/architecture/api-service-core-relay-type-resolution-4.mmd
deleted file mode 100644
index d122b76ab..000000000
--- a/docs/diagrams/architecture/api-service-core-relay-type-resolution-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    DataFetcher["DataFetcher"] --> Domain["Domain Object"]
-    Domain --> Resolver["Node or AssignableTarget Resolver"]
-    Resolver --> SchemaType["GraphQL Schema Type"]
-    SchemaType --> Response["GraphQL Response"]
diff --git a/docs/diagrams/architecture/api-service-core-relay-type-resolution-5.mmd b/docs/diagrams/architecture/api-service-core-relay-type-resolution-5.mmd
deleted file mode 100644
index 60885d35a..000000000
--- a/docs/diagrams/architecture/api-service-core-relay-type-resolution-5.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart TB
-    DomainModel["Mongo Domain Model"] --> RelayResolver["Relay Type Resolver"]
-    RelayResolver --> GraphQLSchema["GraphQL Schema Types"]
diff --git a/docs/diagrams/architecture/api-service-core-relay-type-resolution.mmd b/docs/diagrams/architecture/api-service-core-relay-type-resolution.mmd
deleted file mode 100644
index df97025e3..000000000
--- a/docs/diagrams/architecture/api-service-core-relay-type-resolution.mmd
+++ /dev/null
@@ -1,14 +0,0 @@
-flowchart TD
-    Client["GraphQL Client"] --> Query["GraphQL Query"]
-    Query --> DGS["DGS Runtime"]
-    DGS --> Resolver["Type Resolver"]
-    Resolver --> DomainObj["Domain Object"]
-    DomainObj --> GraphQLType["GraphQL Type Name"]
-
-    subgraph relay_layer["Relay Type Resolution Layer"]
-        Resolver
-    end
-
-    subgraph domain_layer["Mongo Domain Model"]
-        DomainObj
-    end
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-10.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-10.mmd
deleted file mode 100644
index 93e3f4c68..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-10.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Admin["Admin"] --> Controller["UserController"]
-    Controller --> Service["UserService"]
-    Service --> Repo["User Repository"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-11.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-11.mmd
deleted file mode 100644
index d45884088..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-11.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Request["Incoming HTTP Request"] --> Filter["JWT Filter"]
-    Filter --> Principal["AuthPrincipal"]
-    Principal --> Controller["REST Controller"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-2.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-2.mmd
deleted file mode 100644
index b7227563f..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-2.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-sequenceDiagram
-    participant Admin
-    participant Controller as AgentRegistrationSecretController
-    participant Service as AgentRegistrationSecretService
-
-    Admin->>Controller: POST /agent/registration-secret/generate
-    Controller->>Service: generateNewSecret()
-    Service-->>Controller: AgentRegistrationSecretResponse
-    Controller-->>Admin: 201 Created
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-3.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-3.mmd
deleted file mode 100644
index 38721fa21..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    User["Authenticated User"] --> Controller["ApiKeyController"]
-    Controller --> Service["ApiKeyService"]
-    Service --> Repo["BaseApiKeyRepository"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-4.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-4.mmd
deleted file mode 100644
index 8f96fb140..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Agent["Agent"] --> Controller["DeviceController"]
-    Controller --> Service["DeviceService"]
-    Service --> DeviceDoc["Device Document"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-5.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-5.mmd
deleted file mode 100644
index 41904c5b9..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-5.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    Admin["Admin Action"] --> Controller["ForceAgentController"]
-    Controller --> InstallSvc["ForceToolInstallationService"]
-    Controller --> UpdateSvc["ForceToolAgentUpdateService"]
-    Controller --> ClientSvc["ForceClientUpdateService"]
-
-    InstallSvc --> Kafka["Kafka Event"]
-    UpdateSvc --> Kafka
-    ClientSvc --> Kafka
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-6.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-6.mmd
deleted file mode 100644
index c5f8a4036..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-6.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-sequenceDiagram
-    participant Admin
-    participant Controller as InvitationController
-    participant Service as InvitationService
-
-    Admin->>Controller: POST /invitations
-    Controller->>Service: createInvitation(request)
-    Service-->>Controller: InvitationResponse
-    Controller-->>Admin: 201 Created
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-7.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-7.mmd
deleted file mode 100644
index bb0eb550e..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-7.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Request["GET /me"] --> AuthCheck["AuthPrincipal Present?"]
-    AuthCheck -->|"Yes"| Response["Return User Info"]
-    AuthCheck -->|"No"| Unauthorized["401 Unauthorized"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-8.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-8.mmd
deleted file mode 100644
index 5270d4876..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-8.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Admin["Admin"] --> Controller["OrganizationController"]
-    Controller --> CommandSvc["OrganizationCommandService"]
-    Controller --> DomainSvc["OrganizationService"]
-    CommandSvc --> Repo["Organization Repository"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers-9.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers-9.mmd
deleted file mode 100644
index 845810ee8..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers-9.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Admin["Admin"] --> Controller["SSOConfigController"]
-    Controller --> Service["SSOConfigService"]
-    Service --> Strategy["Provider Strategy"]
-    Strategy --> Provider["Google / Microsoft"]
diff --git a/docs/diagrams/architecture/api-service-core-rest-controllers.mmd b/docs/diagrams/architecture/api-service-core-rest-controllers.mmd
deleted file mode 100644
index 6feac1f96..000000000
--- a/docs/diagrams/architecture/api-service-core-rest-controllers.mmd
+++ /dev/null
@@ -1,29 +0,0 @@
-flowchart TD
-    Client["Client / UI / Agent"] --> Gateway["Gateway Service"]
-    Gateway --> ApiCore["API Service Core"]
-
-    subgraph rest_layer["REST Controller Layer"]
-        Controllers["Api Service Core Rest Controllers"]
-    end
-
-    subgraph service_layer["Service Layer"]
-        CommandServices["Command Services"]
-        QueryServices["Query Services"]
-        DomainProcessors["Domain Processors"]
-    end
-
-    subgraph data_layer["Data Layer"]
-        Mongo["Mongo Repositories"]
-        Redis["Redis Cache"]
-        Kafka["Kafka / Events"]
-    end
-
-    ApiCore --> Controllers
-    Controllers --> CommandServices
-    Controllers --> QueryServices
-    Controllers --> DomainProcessors
-
-    CommandServices --> Mongo
-    QueryServices --> Mongo
-    DomainProcessors --> Kafka
-    DomainProcessors --> Redis
diff --git a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-2.mmd b/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-2.mmd
deleted file mode 100644
index 9eb324363..000000000
--- a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-2.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-flowchart TD
-    Request["SSOConfigRequest"] --> Normalize["Normalize Domains"]
-    Normalize --> GenericCheck["validateGenericPublicDomain()"]
-    GenericCheck --> ExistsCheck["validateExists()"]
-    ExistsCheck --> Decision{"Auto Provision?"}
-    Decision -->|"No"| Save["Save Config"]
-    Decision -->|"Yes"| RequireDomain["Require At Least One Domain"]
-    RequireDomain --> MicrosoftCheck{"Microsoft?"}
-    MicrosoftCheck -->|"Yes"| RequireTenant["Require msTenantId"]
-    MicrosoftCheck -->|"No"| Save
-    RequireTenant --> Save
diff --git a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-3.mmd b/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-3.mmd
deleted file mode 100644
index 025f8d4a5..000000000
--- a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-3.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    ListUsers["listUsers()"] --> FetchPage["UserRepository.findAll()"]
-    FetchPage --> MapResponse["UserMapper.toResponse()"]
-    MapResponse --> PostProcess["UserProcessor.postProcessUserGet()"]
-
-    DeleteUser["softDeleteUser()"] --> ValidateSelf["Prevent Self Delete"]
-    ValidateSelf --> ValidateOwner["Prevent OWNER Delete"]
-    ValidateOwner --> MarkDeleted["Set Status DELETED"]
-    MarkDeleted --> SaveUser["UserRepository.save()"]
-    SaveUser --> PostDelete["UserProcessor.postProcessUserDeleted()"]
diff --git a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-4.mmd b/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-4.mmd
deleted file mode 100644
index 8c3ba9978..000000000
--- a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors-4.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    Upsert["upsertConfig()"] --> Exists{"Config Exists?"}
-    Exists -->|"Yes"| Update["Update Existing"]
-    Exists -->|"No"| Create["Create New"]
-    Update --> Encrypt["Encrypt Client Secret"]
-    Create --> Encrypt
-    Encrypt --> Save["SSOConfigRepository.save()"]
-    Save --> PostProcess["SSOConfigProcessor.postProcessConfigSaved()"]
diff --git a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors.mmd b/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors.mmd
deleted file mode 100644
index 5d8c79678..000000000
--- a/docs/diagrams/architecture/api-service-core-user-sso-services-and-processors.mmd
+++ /dev/null
@@ -1,18 +0,0 @@
-flowchart TD
-    Controller["REST / GraphQL Controllers"] --> UserService["UserService"]
-    Controller --> SSOService["SSOConfigService"]
-
-    UserService --> UserRepo["UserRepository"]
-    UserService --> UserProcessor["UserProcessor"]
-
-    SSOService --> SSORepo["SSOConfigRepository"]
-    SSOService --> Encryption["EncryptionService"]
-    SSOService --> DomainValidation["DomainValidationService"]
-    SSOService --> SSOProcessor["SSOConfigProcessor"]
-
-    subgraph processors_layer["Post-Processing Layer"]
-        UserProcessor --> DefaultUserProcessor["DefaultUserProcessor"]
-        SSOProcessor --> DefaultSSOProcessor["DefaultSSOConfigProcessor"]
-        InvitationProcessor --> DefaultInvitationProcessor["DefaultInvitationProcessor"]
-        AgentSecretProcessor --> DefaultAgentProcessor["DefaultAgentRegistrationSecretProcessor"]
-    end
diff --git a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-2.mmd b/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-2.mmd
deleted file mode 100644
index 61f25309b..000000000
--- a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-2.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-sequenceDiagram
-    participant Browser
-    participant Controller as InvitationRegistrationController
-    participant SSOService as SsoInvitationService
-    participant IdP as External IdP
-
-    Browser->>Controller: GET /invitations/accept/sso
-    Controller->>SSOService: startAccept(request)
-    SSOService-->>Controller: SsoAuthorizeData
-    Controller->>Browser: Set-Cookie + 303 Redirect
-    Browser->>IdP: OAuth2 Authorization Request
diff --git a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-3.mmd b/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-3.mmd
deleted file mode 100644
index b6038e501..000000000
--- a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-3.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Start["User Clicks Register with SSO"] --> Clear["Clear Auth State"]
-    Clear --> StartReg["SsoTenantRegistrationService.startRegistration()"]
-    StartReg --> Cookie["Set COOKIE_SSO_REG"]
-    Cookie --> Redirect["Redirect to IdP"]
diff --git a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-4.mmd b/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-4.mmd
deleted file mode 100644
index 5e5fca6db..000000000
--- a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    User["User enters email"] --> Controller["TenantDiscoveryController"]
-    Controller --> Service["TenantDiscoveryService"]
-    Service --> Response["TenantDiscoveryResponse"]
diff --git a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-5.mmd b/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-5.mmd
deleted file mode 100644
index 2b315124b..000000000
--- a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Controllers["Auth Controllers"] --> TenantLayer["Tenant Context Layer"]
-    Controllers --> SSOFlow["SSO Flow & Handlers"]
-    Controllers --> AuthServer["OAuth2 Authorization Server"]
-    AuthServer --> Persistence["Mongo Authorization Service"]
diff --git a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos.mmd b/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos.mmd
deleted file mode 100644
index 9ab0a2ede..000000000
--- a/docs/diagrams/architecture/authorization-service-core-auth-controllers-and-dtos.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    Client["Browser / Client App"] --> Controllers["Auth Controllers"]
-    Controllers --> Services["Domain Services"]
-    Services --> Persistence["Authorization & Tenant Persistence"]
-    Services --> Security["Spring Security / OAuth2"]
-    Security --> Client
diff --git a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-2.mmd b/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-2.mmd
deleted file mode 100644
index f417b8ed2..000000000
--- a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Start["Generate Key Pair"] --> InitRandom["Initialize SecureRandom"]
-    InitRandom --> InitGenerator["Initialize KeyPairGenerator"]
-    InitGenerator --> Generate["Generate RSA KeyPair"]
-    Generate --> ConvertPem["Convert to PEM"]
-    ConvertPem --> CreateKid["Create kid UUID"]
-    CreateKid --> Result["Return AuthenticationKeyPair"]
diff --git a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-3.mmd b/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-3.mmd
deleted file mode 100644
index e99c37703..000000000
--- a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-3.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-flowchart TD
-    Request["Request RSAKey for Tenant"] --> CheckActive["Check Active Key Count"]
-    CheckActive --> Found{"Active Key Exists?"}
-    Found -->|"Yes"| LoadDoc["Load TenantKey Document"]
-    Found -->|"No"| Create["Generate New Key"]
-    Create --> Encrypt["Encrypt Private PEM"]
-    Encrypt --> Save["Save TenantKey"]
-    Save --> LoadDoc
-    LoadDoc --> Parse["Parse PEM to RSA Keys"]
-    Parse --> BuildJwk["Build Nimbus RSAKey"]
-    BuildJwk --> Return["Return RSAKey"]
diff --git a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-4.mmd b/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-4.mmd
deleted file mode 100644
index 485dad1ca..000000000
--- a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    SaveCall["Save Authorization"] --> ExtractPkce["Extract PKCE Parameters"]
-    ExtractPkce --> MapEntity["Map to Mongo Entity"]
-    MapEntity --> Persist["Save to Mongo"]
-    Persist --> Verify["Debug Verify PKCE"]
diff --git a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-5.mmd b/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-5.mmd
deleted file mode 100644
index a88a11966..000000000
--- a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-5.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-flowchart TD
-    Lookup["Find By Token"] --> TypeCheck{"Token Type?"}
-    TypeCheck -->|"Access"| AccessQuery["Find By Access Token"]
-    TypeCheck -->|"Refresh"| RefreshQuery["Find By Refresh Token"]
-    TypeCheck -->|"Code"| CodeQuery["Find By Authorization Code"]
-    TypeCheck -->|"Null"| MultiQuery["Try All Token Fields"]
-    AccessQuery --> MapBack["Map to Domain"]
-    RefreshQuery --> MapBack
-    CodeQuery --> MapBack
-    MultiQuery --> MapBack
-    MapBack --> ReturnAuth["Return OAuth2Authorization"]
diff --git a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-6.mmd b/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-6.mmd
deleted file mode 100644
index 5d14b5009..000000000
--- a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence-6.mmd
+++ /dev/null
@@ -1,18 +0,0 @@
-sequenceDiagram
-    participant User
-    participant AuthServer
-    participant KeyService
-    participant AuthService
-    participant MongoDB
-
-    User->>AuthServer: Authorization Request with PKCE
-    AuthServer->>AuthService: Save OAuth2Authorization
-    AuthService->>MongoDB: Persist Authorization Code
-    AuthServer->>KeyService: Get Tenant Signing Key
-    KeyService->>MongoDB: Load or Create TenantKey
-    KeyService->>AuthServer: Return RSAKey
-    AuthServer->>User: Issue JWT Access Token
-    User->>AuthServer: Token Exchange
-    AuthServer->>AuthService: Find Authorization by Code
-    AuthService->>MongoDB: Retrieve Authorization
-    AuthServer->>User: Return Access and Refresh Tokens
diff --git a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence.mmd b/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence.mmd
deleted file mode 100644
index cdd77c54f..000000000
--- a/docs/diagrams/architecture/authorization-service-core-keys-and-authorization-persistence.mmd
+++ /dev/null
@@ -1,23 +0,0 @@
-flowchart TD
-    ClientApp["OAuth2 Client Application"] --> AuthServer["Authorization Server"]
-
-    subgraph key_layer["Tenant Key Layer"]
-        TenantKeyService["TenantKeyService"] --> KeyGenerator["RsaAuthenticationKeyPairGenerator"]
-        TenantKeyService --> PemUtil["PemUtil"]
-        TenantKeyService --> TenantKeyRepo["TenantKeyRepository"]
-        TenantKeyService --> EncryptionService["EncryptionService"]
-    end
-
-    subgraph client_layer["Client Registration Layer"]
-        RegisteredRepo["MongoRegisteredClientRepository"] --> MongoClientRepo["RegisteredClientMongoRepository"]
-    end
-
-    subgraph auth_layer["Authorization Persistence Layer"]
-        AuthService["MongoAuthorizationService"] --> AuthMapper["MongoAuthorizationMapper"]
-        AuthService --> MongoAuthRepo["MongoOAuth2AuthorizationRepository"]
-        AuthMapper --> MongoEntity["MongoOAuth2Authorization"]
-    end
-
-    AuthServer --> TenantKeyService
-    AuthServer --> RegisteredRepo
-    AuthServer --> AuthService
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-2.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-2.mmd
deleted file mode 100644
index eabc1c302..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-2.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Request["Incoming HTTP Request"] --> Filter["TenantContextFilter"]
-    Filter --> ThreadLocal["TenantContext ThreadLocal"]
-    ThreadLocal --> Services["UserService and Key Services"]
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-3.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-3.mmd
deleted file mode 100644
index 668f63b02..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-3.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Request["OAuth2 Endpoint Request"] --> Match["Authorization Endpoints Matcher"]
-    Match --> Authenticated["Require Authentication"]
-    Authenticated --> JWTValidation["JWT Resource Server Enabled"]
-    JWTValidation --> Response["OAuth2 Response"]
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-4.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-4.mmd
deleted file mode 100644
index 0fc1b3d3e..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    JWTRequest["JWKS or Token Signing"] --> TenantId["TenantContext.getTenantId()"]
-    TenantId --> KeyService["TenantKeyService.getOrCreateActiveKey"]
-    KeyService --> RSAKey["Tenant RSAKey"]
-    RSAKey --> JWKSet["JWKSet Returned"]
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-5.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-5.mmd
deleted file mode 100644
index 01f61db5e..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Auth["Authenticated Principal"] --> Lookup["UserService.findActiveByEmailAndTenant"]
-    Lookup --> Claims["Add Claims to JWT"]
-    Claims --> Token["Signed Access Token"]
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-6.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-6.mmd
deleted file mode 100644
index ae1c09e93..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-6.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    User["User Clicks SSO"] --> OAuthLogin["oauth2Login()"]
-    OAuthLogin --> Resolver["SsoAuthorizationRequestResolver"]
-    Resolver --> Provider["External IdP"]
-    Provider --> Callback["OIDC Callback"]
-    Callback --> OidcService["Custom OidcUserService"]
-    OidcService --> AutoProvision["Auto Provision If Needed"]
-    AutoProvision --> Success["AuthSuccessHandler"]
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-7.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-7.mmd
deleted file mode 100644
index cf74b4686..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-7.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    OAuthFlow["OAuth2 Login Request"] --> Repo["DynamicClientRegistrationRepository"]
-    Repo --> TenantCtx["TenantContext"]
-    TenantCtx --> DynamicSvc["DynamicClientRegistrationService"]
-    DynamicSvc --> ClientReg["ClientRegistration"]
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-8.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant-8.mmd
deleted file mode 100644
index 9532e7d9d..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant-8.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    Step1["Incoming Request"] --> Step2["TenantContextFilter Resolves Tenant"]
-    Step2 --> Step3{{"OAuth2 Endpoint?"}}
-    Step3 -->|"Yes"| Step4["AuthorizationServerConfig"]
-    Step3 -->|"No"| Step5["SecurityConfig"]
-    Step4 --> Step6["JWT Issued with Tenant Claims"]
-    Step5 --> Step7["Authenticated Session or SSO"]
-    Step6 --> EndNode["Response"]
-    Step7 --> EndNode
diff --git a/docs/diagrams/architecture/authorization-service-core-server-and-tenant.mmd b/docs/diagrams/architecture/authorization-service-core-server-and-tenant.mmd
deleted file mode 100644
index 93afcb216..000000000
--- a/docs/diagrams/architecture/authorization-service-core-server-and-tenant.mmd
+++ /dev/null
@@ -1,20 +0,0 @@
-flowchart TD
-    Client["Browser or API Client"] --> Gateway["Gateway Service"]
-    Gateway --> Authz["Authorization Service Core Server And Tenant"]
-
-    subgraph authz_core["Authorization Layer"]
-        TenantFilter["TenantContextFilter"]
-        AuthServerConfig["AuthorizationServerConfig"]
-        SecurityConfigBean["SecurityConfig"]
-        DynamicClientRepo["DynamicClientRegistrationRepository"]
-        TenantKeySvc["TenantKeyService"]
-    end
-
-    Authz --> TenantFilter
-    TenantFilter --> AuthServerConfig
-    TenantFilter --> SecurityConfigBean
-    AuthServerConfig --> TenantKeySvc
-    SecurityConfigBean --> DynamicClientRepo
-
-    AuthServerConfig --> JWKS["Per-Tenant JWKS"]
-    AuthServerConfig --> JWT["Signed JWT Tokens"]
diff --git a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-2.mmd b/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-2.mmd
deleted file mode 100644
index c1938fa0b..000000000
--- a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-2.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    OidcUser["OIDC User Claims"] --> Email["email"]
-    OidcUser --> Preferred["preferred_username"]
-    OidcUser --> Upn["upn"]
-    OidcUser --> Unique["unique_name"]
-
-    Email --> Resolved["Resolved Email"]
-    Preferred --> Resolved
-    Upn --> Resolved
-    Unique --> Resolved
diff --git a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-3.mmd b/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-3.mmd
deleted file mode 100644
index 0151dca81..000000000
--- a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-3.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Cookie["Invite Cookie"] --> Decode["Decode Invite Payload"]
-    Oidc["OIDC User"] --> Extract["Extract Names and Email"]
-    Decode --> BuildReq["Build InvitationRegistrationRequest"]
-    Extract --> BuildReq
-    BuildReq --> Register["InvitationRegistrationService.registerByInvitation"]
-    Register --> Redirect["Clear Cookie and Redirect"]
diff --git a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-4.mmd b/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-4.mmd
deleted file mode 100644
index 579d6dffa..000000000
--- a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-4.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    Cookie["Registration Cookie"] --> Decode["Decode Tenant Payload"]
-    Oidc["OIDC User"] --> Email["Resolve Email"]
-    Decode --> Validate["Validate Tenant Name and Domain"]
-    Email --> BuildReq["Build TenantRegistrationRequest"]
-    Validate --> BuildReq
-    BuildReq --> Register["TenantRegistrationService.registerTenant"]
-    Register --> Redirect["Clear Cookie and Redirect"]
diff --git a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-5.mmd b/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-5.mmd
deleted file mode 100644
index cc926f590..000000000
--- a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-5.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    SSOConfigService["SSO Config Service"] --> GoogleStrategy["Google Client Registration Strategy"]
-    SSOConfigService --> MicrosoftStrategy["Microsoft Client Registration Strategy"]
-
-    GoogleStrategy --> GoogleProps["Google SSO Properties"]
-    MicrosoftStrategy --> MicrosoftProps["Microsoft SSO Properties"]
diff --git a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-6.mmd b/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-6.mmd
deleted file mode 100644
index 12322027f..000000000
--- a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils-6.mmd
+++ /dev/null
@@ -1,14 +0,0 @@
-sequenceDiagram
-    participant Browser
-    participant AuthServer as "Authorization Server"
-    participant Success as "Auth Success Handler"
-    participant Flow as "SSO Flow Handler"
-    participant Service as "Registration Service"
-
-    Browser->>AuthServer: OAuth2 Login (Google or Microsoft)
-    AuthServer->>Success: onAuthenticationSuccess
-    Success->>Success: Update lastLogin
-    Success->>Flow: Delegate to flow handler
-    Flow->>Service: Register user or tenant
-    Service->>Flow: Return tenant context
-    Flow->>Browser: Redirect to target tenant
diff --git a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils.mmd b/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils.mmd
deleted file mode 100644
index ce65039e2..000000000
--- a/docs/diagrams/architecture/authorization-service-core-sso-flow-and-utils.mmd
+++ /dev/null
@@ -1,15 +0,0 @@
-flowchart TD
-    Browser["Browser"] -->|"OAuth2 Login"| AuthServer["Authorization Server"]
-    AuthServer -->|"Authentication Success"| AuthSuccessHandler["Auth Success Handler"]
-
-    AuthSuccessHandler -->|"Delegate"| SsoFlowHandlers["SSO Flow Handlers"]
-    AuthSuccessHandler -->|"Update User"| UserService["User Service"]
-
-    SsoFlowHandlers --> InviteHandler["Invite SSO Handler"]
-    SsoFlowHandlers --> TenantRegHandler["Tenant Registration SSO Handler"]
-
-    InviteHandler --> InvitationService["Invitation Registration Service"]
-    TenantRegHandler --> TenantRegService["Tenant Registration Service"]
-
-    AuthSuccessHandler --> RedirectsUtil["Redirect Utilities"]
-    AuthSuccessHandler --> AuthStateUtils["Auth State Utilities"]
diff --git a/docs/diagrams/architecture/data-kafka-configuration-and-retry-2.mmd b/docs/diagrams/architecture/data-kafka-configuration-and-retry-2.mmd
deleted file mode 100644
index 9ba2cc60f..000000000
--- a/docs/diagrams/architecture/data-kafka-configuration-and-retry-2.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    SpringBoot[Spring Boot] --> DefaultKafkaAutoConfig[KafkaAutoConfiguration]
-    DefaultKafkaAutoConfig -->|Excluded| OssKafkaConfig
-    OssKafkaConfig --> OssTenantKafkaAutoConfiguration
-    OssTenantKafkaAutoConfiguration --> ProducerFactory
-    OssTenantKafkaAutoConfiguration --> ConsumerFactory
-    OssTenantKafkaAutoConfiguration --> KafkaTemplate
-    OssTenantKafkaAutoConfiguration --> KafkaAdmin
diff --git a/docs/diagrams/architecture/data-kafka-configuration-and-retry-3.mmd b/docs/diagrams/architecture/data-kafka-configuration-and-retry-3.mmd
deleted file mode 100644
index 28fb95c63..000000000
--- a/docs/diagrams/architecture/data-kafka-configuration-and-retry-3.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    ConfigProps[KafkaTopicProperties] --> AdminBean[KafkaAdmin]
-    AdminBean --> TopicBuilder
-    TopicBuilder --> NewTopic
-    NewTopic --> KafkaCluster
diff --git a/docs/diagrams/architecture/data-kafka-configuration-and-retry-4.mmd b/docs/diagrams/architecture/data-kafka-configuration-and-retry-4.mmd
deleted file mode 100644
index 24014625a..000000000
--- a/docs/diagrams/architecture/data-kafka-configuration-and-retry-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    KafkaCluster --> ListenerContainer
-    ListenerContainer --> ConsumerFactory
-    ConsumerFactory --> JsonDeserializer
-    ListenerContainer --> AckMode[RECORD Ack Mode]
diff --git a/docs/diagrams/architecture/data-kafka-configuration-and-retry-5.mmd b/docs/diagrams/architecture/data-kafka-configuration-and-retry-5.mmd
deleted file mode 100644
index 7647e6808..000000000
--- a/docs/diagrams/architecture/data-kafka-configuration-and-retry-5.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    DebeziumMessage --> Payload
-    Payload --> Before[Before State]
-    Payload --> After[After State]
-    Payload --> Source
-    Payload --> Operation
-    Payload --> Timestamp
-    Source --> Database
-    Source --> Table
-    Source --> Connector
diff --git a/docs/diagrams/architecture/data-kafka-configuration-and-retry-6.mmd b/docs/diagrams/architecture/data-kafka-configuration-and-retry-6.mmd
deleted file mode 100644
index f36f73356..000000000
--- a/docs/diagrams/architecture/data-kafka-configuration-and-retry-6.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Producer --> KafkaCluster
-    KafkaCluster -->|Failure| RecoveryHandler
-    RecoveryHandler --> StructuredLog
diff --git a/docs/diagrams/architecture/data-kafka-configuration-and-retry.mmd b/docs/diagrams/architecture/data-kafka-configuration-and-retry.mmd
deleted file mode 100644
index b54be1cd0..000000000
--- a/docs/diagrams/architecture/data-kafka-configuration-and-retry.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    AppService[Application Service] --> KafkaInfra[Data Kafka Configuration And Retry]
-    KafkaInfra --> KafkaCluster[Kafka Cluster]
-    KafkaCluster --> StreamService[Stream Service Core]
-    KafkaCluster --> OtherConsumers[Other Consumers]
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories-2.mmd b/docs/diagrams/architecture/data-mongo-base-repositories-2.mmd
deleted file mode 100644
index aece0a12e..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories-2.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    ApiKey["API Key Document"] --> ApiKeyRepo["BaseApiKeyRepository"]
-    ApiKeyRepo --> UserScope["User-Scoped Queries"]
-    ApiKeyRepo --> Expiry["Expiration Queries"]
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories-3.mmd b/docs/diagrams/architecture/data-mongo-base-repositories-3.mmd
deleted file mode 100644
index 42408866f..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Tenant["Tenant Document"] --> TenantRepo["BaseTenantRepository"]
-    TenantRepo --> DomainLookup["Domain-Based Resolution"]
-    DomainLookup --> AuthLayer["Authorization & SSO"]
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories-4.mmd b/docs/diagrams/architecture/data-mongo-base-repositories-4.mmd
deleted file mode 100644
index 85b9e185f..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Tool["Integrated Tool Document"] --> ToolRepo["BaseIntegratedToolRepository"]
-    ToolRepo --> TypeLookup["Type-Based Resolution"]
-    TypeLookup --> Gateway["Gateway & Integration Layer"]
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories-5.mmd b/docs/diagrams/architecture/data-mongo-base-repositories-5.mmd
deleted file mode 100644
index de3fabd01..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    UserDoc["User Document"] --> UserRepo["BaseUserRepository"]
-    UserRepo --> EmailLookup["Email-Based Lookup"]
-    UserRepo --> StatusCheck["Status Validation"]
-    StatusCheck --> Security["Authentication & Access Control"]
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories-6.mmd b/docs/diagrams/architecture/data-mongo-base-repositories-6.mmd
deleted file mode 100644
index 19d21ead5..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories-6.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Request["Incoming Request"] --> DomainExtract["Extract Domain"]
-    DomainExtract --> TenantRepo["BaseTenantRepository"]
-    TenantRepo --> TenantResolved["Tenant Context Established"]
-    TenantResolved --> UserRepo["BaseUserRepository"]
-    UserRepo --> AuthResult["User Validated"]
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories-7.mmd b/docs/diagrams/architecture/data-mongo-base-repositories-7.mmd
deleted file mode 100644
index 8d3041b86..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories-7.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    Base["Data Mongo Base Repositories"] --> SyncImpl["Mongo Sync Implementations"]
-    Base --> ReactiveImpl["Mongo Reactive Implementations"]
-    SyncImpl --> ServiceLayer["Service Layer"]
-    ReactiveImpl --> ServiceLayer
diff --git a/docs/diagrams/architecture/data-mongo-base-repositories.mmd b/docs/diagrams/architecture/data-mongo-base-repositories.mmd
deleted file mode 100644
index da1da35d2..000000000
--- a/docs/diagrams/architecture/data-mongo-base-repositories.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Domain["Mongo Domain Model"] --> BaseRepo["Data Mongo Base Repositories"]
-    BaseRepo --> Blocking["Blocking Repositories"]
-    BaseRepo --> Reactive["Reactive Repositories"]
-
-    Blocking --> Services["Application Services"]
-    Reactive --> Services
diff --git a/docs/diagrams/architecture/data-mongo-domain-model-2.mmd b/docs/diagrams/architecture/data-mongo-domain-model-2.mmd
deleted file mode 100644
index a298cd876..000000000
--- a/docs/diagrams/architecture/data-mongo-domain-model-2.mmd
+++ /dev/null
@@ -1,22 +0,0 @@
-classDiagram
-    class User {
-        id
-        email
-        firstName
-        lastName
-        roles
-        status
-        createdAt
-        updatedAt
-    }
-
-    class AuthUser {
-        tenantId
-        passwordHash
-        loginProvider
-        externalUserId
-        lastLogin
-        imageUrl
-    }
-
-    User <|-- AuthUser
diff --git a/docs/diagrams/architecture/data-mongo-domain-model-3.mmd b/docs/diagrams/architecture/data-mongo-domain-model-3.mmd
deleted file mode 100644
index 1f61e011e..000000000
--- a/docs/diagrams/architecture/data-mongo-domain-model-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-stateDiagram-v2
-    [*] --> ACTIVE
-    ACTIVE --> OFFLINE
-    OFFLINE --> ACTIVE
-    ACTIVE --> MAINTENANCE
-    MAINTENANCE --> ACTIVE
diff --git a/docs/diagrams/architecture/data-mongo-domain-model-4.mmd b/docs/diagrams/architecture/data-mongo-domain-model-4.mmd
deleted file mode 100644
index 9fcd8cbc2..000000000
--- a/docs/diagrams/architecture/data-mongo-domain-model-4.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Ticket["Ticket"] --> Note["TicketNote"]
-    Ticket --> Attachment["TicketAttachment"]
-    Ticket --> User["User (Assigned)"]
-    Ticket --> Device["Device"]
-    Ticket --> Org["Organization"]
diff --git a/docs/diagrams/architecture/data-mongo-domain-model-5.mmd b/docs/diagrams/architecture/data-mongo-domain-model-5.mmd
deleted file mode 100644
index dfbf696fa..000000000
--- a/docs/diagrams/architecture/data-mongo-domain-model-5.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart TD
-    Notification["Notification"] --> ReadState["NotificationReadState"]
-    ReadState --> Recipient["User or Organization"]
diff --git a/docs/diagrams/architecture/data-mongo-domain-model-6.mmd b/docs/diagrams/architecture/data-mongo-domain-model-6.mmd
deleted file mode 100644
index 86de08803..000000000
--- a/docs/diagrams/architecture/data-mongo-domain-model-6.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    TagAssignment["TagAssignment"] --> Device
-    TagAssignment --> Ticket
-    TagAssignment --> Organization
diff --git a/docs/diagrams/architecture/data-mongo-domain-model.mmd b/docs/diagrams/architecture/data-mongo-domain-model.mmd
deleted file mode 100644
index 6171a289c..000000000
--- a/docs/diagrams/architecture/data-mongo-domain-model.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    Gateway["Gateway Service"] --> ApiService["API Service Core"]
-    ApiService --> DomainModel["Data Mongo Domain Model"]
-    AuthService["Authorization Service"] --> DomainModel
-    StreamService["Stream Service"] --> DomainModel
-    ManagementService["Management Service"] --> DomainModel
-    ExternalApi["External API Service"] --> DomainModel
-
-    DomainModel --> MongoDB[("MongoDB")]
diff --git a/docs/diagrams/architecture/data-mongo-query-filters-2.mmd b/docs/diagrams/architecture/data-mongo-query-filters-2.mmd
deleted file mode 100644
index 631c49dee..000000000
--- a/docs/diagrams/architecture/data-mongo-query-filters-2.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Filter["EventQueryFilter"] --> ByUser["userIds"]
-    Filter --> ByType["eventTypes"]
-    Filter --> ByStart["startDate"]
-    Filter --> ByEnd["endDate"]
diff --git a/docs/diagrams/architecture/data-mongo-query-filters-3.mmd b/docs/diagrams/architecture/data-mongo-query-filters-3.mmd
deleted file mode 100644
index af95d5ac1..000000000
--- a/docs/diagrams/architecture/data-mongo-query-filters-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    OrgFilter["OrganizationQueryFilter"] --> SizeRange["Employee Range"]
-    OrgFilter --> Contract["Active Contract"]
-    OrgFilter --> Status["Organization Status"]
diff --git a/docs/diagrams/architecture/data-mongo-query-filters-4.mmd b/docs/diagrams/architecture/data-mongo-query-filters-4.mmd
deleted file mode 100644
index 2e3aebcb4..000000000
--- a/docs/diagrams/architecture/data-mongo-query-filters-4.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    TicketFilter["TicketQueryFilter"] --> Statuses["TicketStatus List"]
-    TicketFilter --> OrgScope["Organization IDs"]
-    TicketFilter --> Assignees["Assignee IDs"]
-    TicketFilter --> Labels["Label IDs"]
-    TicketFilter --> Devices["Device IDs"]
-    TicketFilter --> Source["Creation Sources"]
-    TicketFilter --> TimeFrom["createdAtFrom"]
-    TicketFilter --> TimeTo["createdAtTo"]
diff --git a/docs/diagrams/architecture/data-mongo-query-filters-5.mmd b/docs/diagrams/architecture/data-mongo-query-filters-5.mmd
deleted file mode 100644
index 3e677a756..000000000
--- a/docs/diagrams/architecture/data-mongo-query-filters-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    UserFilter["UserQueryFilter"] --> Email["emailRegex"]
-    UserFilter --> Name["nameRegex"]
-    UserFilter --> Status["UserStatus"]
diff --git a/docs/diagrams/architecture/data-mongo-query-filters-6.mmd b/docs/diagrams/architecture/data-mongo-query-filters-6.mmd
deleted file mode 100644
index 17d98509a..000000000
--- a/docs/diagrams/architecture/data-mongo-query-filters-6.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    ServiceLayer["Service Layer"] --> QueryFilter["Query Filter"]
-    QueryFilter --> CustomRepository["Custom Repository Impl"]
-    CustomRepository --> CriteriaBuilder["Mongo Criteria Builder"]
-    CriteriaBuilder --> Mongo[("MongoDB Collection")]
diff --git a/docs/diagrams/architecture/data-mongo-query-filters.mmd b/docs/diagrams/architecture/data-mongo-query-filters.mmd
deleted file mode 100644
index 8dc0be82a..000000000
--- a/docs/diagrams/architecture/data-mongo-query-filters.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart LR
-    ApiLayer["API Layer\nREST + GraphQL"] --> FilterDTOs["Filter Input DTOs"]
-    FilterDTOs --> QueryFilters["Data Mongo Query Filters"]
-    QueryFilters --> CustomRepos["Custom Mongo Repositories"]
-    CustomRepos --> MongoDB[("MongoDB")]
-
-    DomainModel["Domain Documents"] --> CustomRepos
diff --git a/docs/diagrams/architecture/data-mongo-reactive-repositories-2.mmd b/docs/diagrams/architecture/data-mongo-reactive-repositories-2.mmd
deleted file mode 100644
index 14dd06f78..000000000
--- a/docs/diagrams/architecture/data-mongo-reactive-repositories-2.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-sequenceDiagram
-    participant Service as "Auth Service"
-    participant Repo as "ReactiveOAuthClientRepository"
-    participant DB as "MongoDB"
-
-    Service->>Repo: findByClientId(clientId)
-    Repo->>DB: Reactive query
-    DB-->>Repo: OAuthClient document
-    Repo-->>Service: Mono<OAuthClient>
diff --git a/docs/diagrams/architecture/data-mongo-reactive-repositories-3.mmd b/docs/diagrams/architecture/data-mongo-reactive-repositories-3.mmd
deleted file mode 100644
index 6c8b5f7c2..000000000
--- a/docs/diagrams/architecture/data-mongo-reactive-repositories-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    BaseRepo["BaseUserRepository"] --> ReactiveRepo["ReactiveUserRepository"]
-    ReactiveMongo["ReactiveMongoRepository"] --> ReactiveRepo
-    ReactiveRepo --> UserDoc["User Document"]
diff --git a/docs/diagrams/architecture/data-mongo-reactive-repositories.mmd b/docs/diagrams/architecture/data-mongo-reactive-repositories.mmd
deleted file mode 100644
index 86ebbcd15..000000000
--- a/docs/diagrams/architecture/data-mongo-reactive-repositories.mmd
+++ /dev/null
@@ -1,12 +0,0 @@
-flowchart TD
-    App["Application Context"] --> Config["MongoReactiveConfig"]
-    Config -->|"@EnableReactiveMongoRepositories"| Scan["Reactive Repository Scan"]
-
-    Scan --> OAuthRepo["ReactiveOAuthClientRepository"]
-    Scan --> UserRepo["ReactiveUserRepository"]
-
-    OAuthRepo --> OAuthClient["OAuthClient Document"]
-    UserRepo --> UserDoc["User Document"]
-
-    OAuthClient --> MongoDB[("MongoDB")]
-    UserDoc --> MongoDB
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-2.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-2.mmd
deleted file mode 100644
index 82524c587..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-2.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Factory["MongoDatabaseFactory"] --> Resolver["DefaultDbRefResolver"]
-    Resolver --> Converter["MappingMongoConverter"]
-    Conversions["MongoCustomConversions"] --> Converter
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-3.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-3.mmd
deleted file mode 100644
index 8150f2900..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Startup["Application Startup"] --> EnsureIndexes["Ensure Required Indexes"]
-    EnsureIndexes --> DropLegacy["Drop Stale Indexes"]
-    DropLegacy --> LogResult["Log Success Or Skip"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-4.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-4.mmd
deleted file mode 100644
index d94e29831..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-4.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    ClientRequest["Client Request With Cursor"] --> ParseCursor["Parse ObjectId"]
-    ParseCursor --> LoadCursorDoc["Load Cursor Document"]
-    LoadCursorDoc --> CompareSortField["Compare Sort Field"]
-    CompareSortField --> AddCriteria["Add $or Criteria"]
-    AddCriteria --> ApplySort["Sort By Field And _id"]
-    ApplySort --> Limit["Apply Limit"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-5.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-5.mmd
deleted file mode 100644
index c303aee69..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Match["Match itemId"] --> Group["Group By targetType"]
-    Group --> Count["Count"]
-    Count --> MapResult["Map To EnumMap"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-6.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-6.mmd
deleted file mode 100644
index 093df5ca8..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-6.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    SearchCriteria["Search OR Criteria"] --> Combine
-    CursorCriteria["Cursor OR Criteria"] --> Combine
-    Combine["Combine Using $and"] --> FinalQuery["Final Query"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-7.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-7.mmd
deleted file mode 100644
index a321e8c2d..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-7.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    FetchReadStates["Fetch NotificationReadState"] --> ExtractIds
-    ExtractIds["Extract Notification IDs"] --> FetchNotifications
-    FetchNotifications["Fetch Notification Documents"] --> Merge["Merge With Status"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-8.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-8.mmd
deleted file mode 100644
index fb0f8a57d..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-8.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart LR
-    MatchResolved["Match Resolved Tickets"] --> ProjectDiff["Compute resolvedAt - createdAt"]
-    ProjectDiff --> GroupAvg["Average Resolution Time"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-9.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-9.mmd
deleted file mode 100644
index 306ed7466..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories-9.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    RetryStart["Retry Attempt"] --> OnError["onError()"]
-    OnError --> LogWarn["Log Warning"]
-    RetryEnd["Retry Complete"] --> Close
-    Close --> SuccessOrFail["Log Success Or Error"]
diff --git a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories.mmd b/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories.mmd
deleted file mode 100644
index b4114df5b..000000000
--- a/docs/diagrams/architecture/data-mongo-sync-config-and-custom-repositories.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    ApiLayer["API Service Layer"] --> RepositoryLayer["Custom Repositories"]
-    RepositoryLayer --> MongoTemplate["MongoTemplate"]
-    MongoTemplate --> MongoDB[("MongoDB")]
-
-    DomainModel["Domain Documents"] --> RepositoryLayer
-    QueryFilters["Query Filter DTOs"] --> RepositoryLayer
-
-    Config["Mongo Sync Config"] --> RepositoryLayer
-    IndexConfig["Mongo Index Config"] --> MongoDB
diff --git a/docs/diagrams/architecture/data-nats-notifications-2.mmd b/docs/diagrams/architecture/data-nats-notifications-2.mmd
deleted file mode 100644
index 1f9f77542..000000000
--- a/docs/diagrams/architecture/data-nats-notifications-2.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    Start["Broadcast Request"] --> Validate["Validate NotificationCommand"]
-    Validate --> Persist["Persist Notification"]
-    Persist --> CreateReadStates["Create Read States"]
-    CreateReadStates --> Publish["Publish to NATS"]
-    Publish --> End["Complete"]
-
-    CreateReadStates -->|"failure"| Rollback["Delete Notification"]
diff --git a/docs/diagrams/architecture/data-nats-notifications-3.mmd b/docs/diagrams/architecture/data-nats-notifications-3.mmd
deleted file mode 100644
index bd2f7d461..000000000
--- a/docs/diagrams/architecture/data-nats-notifications-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    Cmd["NotificationCommand"] --> Build["Build Notification"]
-    Build --> Save["Save to Repository"]
-    Save --> Category["Resolve Category"]
-    Category --> RS["Create Read States"]
-    RS --> Publish["Publish Per Recipient"]
diff --git a/docs/diagrams/architecture/data-nats-notifications-4.mmd b/docs/diagrams/architecture/data-nats-notifications-4.mmd
deleted file mode 100644
index 07c44667a..000000000
--- a/docs/diagrams/architecture/data-nats-notifications-4.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    Doc["Notification Document"] --> Msg["NotificationMessage"]
-
-    Msg --> Id["id"]
-    Msg --> Severity["severity"]
-    Msg --> Title["title"]
-    Msg --> Desc["description"]
-    Msg --> Created["createdAt"]
-    Msg --> Context["context"]
diff --git a/docs/diagrams/architecture/data-nats-notifications-5.mmd b/docs/diagrams/architecture/data-nats-notifications-5.mmd
deleted file mode 100644
index 4dbe3a60f..000000000
--- a/docs/diagrams/architecture/data-nats-notifications-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Persist["Persist Notification"] --> Durable["Durable Storage"]
-    Durable --> RealTime["Real-Time Publish"]
-
-    RealTime -->|"failure"| CatchUp["Client Catch-Up via API"]
diff --git a/docs/diagrams/architecture/data-nats-notifications-6.mmd b/docs/diagrams/architecture/data-nats-notifications-6.mmd
deleted file mode 100644
index c34ee6d92..000000000
--- a/docs/diagrams/architecture/data-nats-notifications-6.mmd
+++ /dev/null
@@ -1,13 +0,0 @@
-sequenceDiagram
-    participant Service
-    participant Broadcaster
-    participant Mongo
-    participant NATS
-    participant Client
-
-    Service->>Broadcaster: broadcast(command)
-    Broadcaster->>Mongo: save(notification)
-    Broadcaster->>Mongo: createReadStates()
-    Broadcaster->>NATS: publish(subject, message)
-    NATS->>Client: deliver real-time event
-    Client->>Mongo: query for reconciliation
diff --git a/docs/diagrams/architecture/data-nats-notifications.mmd b/docs/diagrams/architecture/data-nats-notifications.mmd
deleted file mode 100644
index 15eddc886..000000000
--- a/docs/diagrams/architecture/data-nats-notifications.mmd
+++ /dev/null
@@ -1,13 +0,0 @@
-flowchart TD
-    Caller["Application Service"] --> Command["NotificationCommand"]
-    Command --> Broadcaster["NotificationBroadcaster"]
-
-    Broadcaster --> Repo["NotificationRepository"]
-    Broadcaster --> ReadState["NotificationReadStateService"]
-    Broadcaster --> Registry["NotificationContextDescriptorRegistry"]
-
-    Broadcaster -->|"optional"| Publisher["NotificationNatsPublisher"]
-    Publisher --> Nats["NATS Server"]
-
-    Repo --> Mongo[("MongoDB")]
-    ReadState --> Mongo
diff --git a/docs/diagrams/architecture/data-pinot-repositories-2.mmd b/docs/diagrams/architecture/data-pinot-repositories-2.mmd
deleted file mode 100644
index d1b088f2f..000000000
--- a/docs/diagrams/architecture/data-pinot-repositories-2.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    AppConfig["Spring Context"] --> PinotConfig["PinotConfig"]
-    PinotConfig --> BrokerConn["pinotBrokerConnection()"]
-    PinotConfig --> ControllerConn["pinotControllerConnection()"]
-    BrokerConn --> PinotCluster["Pinot Broker"]
-    ControllerConn --> PinotController["Pinot Controller"]
diff --git a/docs/diagrams/architecture/data-pinot-repositories-3.mmd b/docs/diagrams/architecture/data-pinot-repositories-3.mmd
deleted file mode 100644
index f1a0d62fd..000000000
--- a/docs/diagrams/architecture/data-pinot-repositories-3.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    Start["Facet Request"] --> BuildQuery["PinotQueryBuilder"]
-    BuildQuery --> ApplyFilters["applyDeviceFilters()"]
-    ApplyFilters --> ExcludeField{"Exclude Facet Field?"}
-    ExcludeField -->|"Yes"| SkipFilter["Skip That Filter"]
-    ExcludeField -->|"No"| ApplyFilter["Apply Filter"]
-    SkipFilter --> GroupBy["GROUP BY facetField"]
-    ApplyFilter --> GroupBy
-    GroupBy --> Execute["executeKeyCountQuery()"]
diff --git a/docs/diagrams/architecture/data-pinot-repositories-4.mmd b/docs/diagrams/architecture/data-pinot-repositories-4.mmd
deleted file mode 100644
index 45bd4e272..000000000
--- a/docs/diagrams/architecture/data-pinot-repositories-4.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart LR
-    Request["Log Query Request"] --> Builder["PinotQueryBuilder"]
-    Builder --> DateRange["whereDateRange()"]
-    DateRange --> Filters["whereIn() / whereEquals()"]
-    Filters --> Search["whereRelevanceLogSearch()"]
-    Search --> Cursor["whereCursor()"]
-    Cursor --> Sorting["orderBySortInput()"]
-    Sorting --> Limit["limit()"]
-    Limit --> Execute["executeLogQuery()"]
diff --git a/docs/diagrams/architecture/data-pinot-repositories-5.mmd b/docs/diagrams/architecture/data-pinot-repositories-5.mmd
deleted file mode 100644
index 2868297f8..000000000
--- a/docs/diagrams/architecture/data-pinot-repositories-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Query["Incoming Query"] --> TenantFilter["Apply tenantId"]
-    TenantFilter --> PinotExec["Execute on Shared Table"]
-    PinotExec --> TenantScoped["Tenant Scoped Result"]
diff --git a/docs/diagrams/architecture/data-pinot-repositories-6.mmd b/docs/diagrams/architecture/data-pinot-repositories-6.mmd
deleted file mode 100644
index 263641427..000000000
--- a/docs/diagrams/architecture/data-pinot-repositories-6.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart LR
-    Client["UI / API Request"] --> ApiService["API Service"]
-    ApiService --> LogRepo["PinotClientLogRepository"]
-    LogRepo --> PinotBroker["Pinot Broker"]
-    PinotBroker --> PinotServer["Pinot Servers"]
-    PinotServer --> PinotBroker
-    PinotBroker --> LogRepo
-    LogRepo --> ApiService
-    ApiService --> Client
diff --git a/docs/diagrams/architecture/data-pinot-repositories.mmd b/docs/diagrams/architecture/data-pinot-repositories.mmd
deleted file mode 100644
index 5bedb0d88..000000000
--- a/docs/diagrams/architecture/data-pinot-repositories.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    StreamService["Stream Service Core Kafka And Handlers"] -->|"Ingest Events"| PinotCluster["Apache Pinot Cluster"]
-    MongoDB["Data Mongo Domain Model"] -->|"Transactional Data"| Services["API & Management Services"]
-    PinotCluster -->|"Analytical Queries"| PinotRepos["Data Pinot Repositories"]
-    PinotRepos -->|"Facet Counts & Logs"| Services
diff --git a/docs/diagrams/architecture/data-redis-cache-2.mmd b/docs/diagrams/architecture/data-redis-cache-2.mmd
deleted file mode 100644
index 03a831121..000000000
--- a/docs/diagrams/architecture/data-redis-cache-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Start["Application Startup"] --> RedisEnabled{"Redis Enabled?"}
-    RedisEnabled -->|Yes| CreateManager["Create RedisCacheManager"]
-    RedisEnabled -->|No| Skip["Skip Redis Cache Config"]
-    CreateManager --> DefaultConfig["Apply Default TTL 6h"]
-    DefaultConfig --> FleetOverride["Override Fleet TTL 1h"]
-    FleetOverride --> Ready["CacheManager Ready"]
diff --git a/docs/diagrams/architecture/data-redis-cache-3.mmd b/docs/diagrams/architecture/data-redis-cache-3.mmd
deleted file mode 100644
index 4ce667c3d..000000000
--- a/docs/diagrams/architecture/data-redis-cache-3.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart LR
-    TenantA["Tenant A"] --> KeyBuilder
-    TenantB["Tenant B"] --> KeyBuilder
-    KeyBuilder --> RedisKeyA["tenantA:deviceCache::123"]
-    KeyBuilder --> RedisKeyB["tenantB:deviceCache::123"]
-    RedisKeyA --> RedisServer[("Redis")]
-    RedisKeyB --> RedisServer
diff --git a/docs/diagrams/architecture/data-redis-cache.mmd b/docs/diagrams/architecture/data-redis-cache.mmd
deleted file mode 100644
index e90265500..000000000
--- a/docs/diagrams/architecture/data-redis-cache.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    AppServices["Application Services"] --> CacheAbstraction["Spring Cache Abstraction"]
-    CacheAbstraction --> CacheManager["RedisCacheManager"]
-    CacheManager --> RedisConnection["RedisConnectionFactory"]
-    CacheManager --> KeyBuilder["OpenframeRedisKeyBuilder"]
-    RedisConnection --> RedisServer[("Redis Server")]
-
-    ReactiveServices["Reactive Services"] --> ReactiveTemplate["ReactiveRedisTemplate"]
-    ReactiveTemplate --> ReactiveConnection["ReactiveRedisConnectionFactory"]
-    ReactiveConnection --> RedisServer
diff --git a/docs/diagrams/architecture/external-api-service-core-2.mmd b/docs/diagrams/architecture/external-api-service-core-2.mmd
deleted file mode 100644
index f12ed4f87..000000000
--- a/docs/diagrams/architecture/external-api-service-core-2.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Request["GET /api/v1/devices"] --> Criteria["DeviceFilterCriteria"]
-    Criteria --> Pagination["CursorPaginationCriteria"]
-    Pagination --> Query["DeviceService.queryDevices()"]
-    Query --> Result["Query Result"]
-    Result --> Mapper["DeviceMapper"]
-    Mapper --> Response["DevicesResponse"]
diff --git a/docs/diagrams/architecture/external-api-service-core-3.mmd b/docs/diagrams/architecture/external-api-service-core-3.mmd
deleted file mode 100644
index ab70d3f39..000000000
--- a/docs/diagrams/architecture/external-api-service-core-3.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    EventRequest["GET /api/v1/events"] --> Filter["EventFilterCriteria"]
-    Filter --> Service["EventService.queryEvents()"]
-    Service --> Mapper["EventMapper"]
-    Mapper --> EventsResponse["EventsResponse"]
diff --git a/docs/diagrams/architecture/external-api-service-core-4.mmd b/docs/diagrams/architecture/external-api-service-core-4.mmd
deleted file mode 100644
index 67917cb93..000000000
--- a/docs/diagrams/architecture/external-api-service-core-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    OrgRequest["Organization Request"] --> QueryService["OrganizationQueryService"]
-    OrgRequest --> CommandService["OrganizationCommandService"]
-    CommandService --> Validation["Archive Rules"]
diff --git a/docs/diagrams/architecture/external-api-service-core-5.mmd b/docs/diagrams/architecture/external-api-service-core-5.mmd
deleted file mode 100644
index 821c7120d..000000000
--- a/docs/diagrams/architecture/external-api-service-core-5.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Client["External Client"] --> ProxyController["IntegrationController"]
-    ProxyController --> RestProxyService["RestProxyService"]
-    RestProxyService --> ToolRepo["IntegratedToolRepository"]
-    RestProxyService --> Resolver["ProxyUrlResolver"]
-    Resolver --> TargetTool["Integrated Tool API"]
diff --git a/docs/diagrams/architecture/external-api-service-core.mmd b/docs/diagrams/architecture/external-api-service-core.mmd
deleted file mode 100644
index 1e702571b..000000000
--- a/docs/diagrams/architecture/external-api-service-core.mmd
+++ /dev/null
@@ -1,16 +0,0 @@
-flowchart LR
-    Client["External Client"] -->|"X-API-Key"| ExternalAPI["External Api Service Core"]
-
-    ExternalAPI --> DeviceService["Device Service"]
-    ExternalAPI --> EventService["Event Service"]
-    ExternalAPI --> LogService["Log Service"]
-    ExternalAPI --> OrganizationService["Organization Services"]
-    ExternalAPI --> ToolService["Tool Service"]
-
-    ExternalAPI --> ProxyService["Rest Proxy Service"]
-    ProxyService --> IntegratedTool["Integrated Tool"]
-
-    DeviceService --> MongoDB[("MongoDB")]
-    EventService --> MongoDB
-    LogService --> Pinot[("Apache Pinot")]
-    ToolService --> MongoDB
diff --git a/docs/diagrams/architecture/gateway-service-core-security-and-routing-2.mmd b/docs/diagrams/architecture/gateway-service-core-security-and-routing-2.mmd
deleted file mode 100644
index 1fb4bf101..000000000
--- a/docs/diagrams/architecture/gateway-service-core-security-and-routing-2.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    Request["Incoming Request"] --> Origin["OriginSanitizerFilter"]
-    Origin --> AuthHeader["AddAuthorizationHeaderFilter"]
-    AuthHeader --> JwtValidation["JWT Authentication"]
-    JwtValidation --> RoleCheck["Role Authorization Rules"]
-    RoleCheck --> ApiKeyCheck{"External API Path?"}
-    ApiKeyCheck -->|Yes| ApiKeyFilter["ApiKeyAuthenticationFilter"]
-    ApiKeyCheck -->|No| Continue["Continue Routing"]
-    ApiKeyFilter --> Continue
-    Continue --> Controller["Controller / Route"]
diff --git a/docs/diagrams/architecture/gateway-service-core-security-and-routing-3.mmd b/docs/diagrams/architecture/gateway-service-core-security-and-routing-3.mmd
deleted file mode 100644
index 8a4cf108f..000000000
--- a/docs/diagrams/architecture/gateway-service-core-security-and-routing-3.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    Req["/external-api/**"] --> CheckKey["Check X-API-Key Header"]
-    CheckKey --> Valid{"Valid Key?"}
-    Valid -->|No| Reject401["Return 401"]
-    Valid -->|Yes| RateCheck["RateLimitService.isAllowed"]
-    RateCheck --> Allowed{"Allowed?"}
-    Allowed -->|No| Reject429["Return 429 + Retry-After"]
-    Allowed -->|Yes| AddHeaders["Add RateLimit Headers"]
-    AddHeaders --> AddContext["Inject X-User-Id + X-Api-Key-Id"]
-    AddContext --> Forward["Forward to External API"]
diff --git a/docs/diagrams/architecture/gateway-service-core-security-and-routing-4.mmd b/docs/diagrams/architecture/gateway-service-core-security-and-routing-4.mmd
deleted file mode 100644
index dda93d4dd..000000000
--- a/docs/diagrams/architecture/gateway-service-core-security-and-routing-4.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart LR
-    Request["Tool Request"] --> Registry["ToolUpstreamResolverRegistry"]
-    Registry -->|Specific Tool| Mesh["MeshCentralUpstreamResolver"]
-    Registry -->|Specific Tool| Tactical["TacticalRmmUpstreamResolver"]
-    Registry -->|Fallback| Default["DefaultToolUpstreamResolver"]
-    Mesh --> Proxy
-    Tactical --> Proxy
-    Default --> Proxy
diff --git a/docs/diagrams/architecture/gateway-service-core-security-and-routing-5.mmd b/docs/diagrams/architecture/gateway-service-core-security-and-routing-5.mmd
deleted file mode 100644
index 44f992bcd..000000000
--- a/docs/diagrams/architecture/gateway-service-core-security-and-routing-5.mmd
+++ /dev/null
@@ -1,12 +0,0 @@
-flowchart TD
-    Client --> Gateway
-    Gateway --> OriginFilter
-    OriginFilter --> AuthHeader
-    AuthHeader --> JwtResolver
-    JwtResolver --> RoleAuth
-    RoleAuth --> RouteDecision
-    RouteDecision -->|REST| IntegrationController
-    RouteDecision -->|WebSocket| WebSocketGatewayConfig
-    IntegrationController --> UpstreamResolver
-    WebSocketGatewayConfig --> UpstreamResolver
-    UpstreamResolver --> IntegratedTool
diff --git a/docs/diagrams/architecture/gateway-service-core-security-and-routing.mmd b/docs/diagrams/architecture/gateway-service-core-security-and-routing.mmd
deleted file mode 100644
index 7b597a83e..000000000
--- a/docs/diagrams/architecture/gateway-service-core-security-and-routing.mmd
+++ /dev/null
@@ -1,20 +0,0 @@
-flowchart TD
-    Client["Client / Agent / UI"] --> Gateway["Gateway Service Core Security And Routing"]
-
-    subgraph security_layer["Security Layer"]
-        AuthHeader["AddAuthorizationHeaderFilter"]
-        JwtConfig["JwtAuthConfig"]
-        SecurityConfig["GatewaySecurityConfig"]
-        ApiKeyFilter["ApiKeyAuthenticationFilter"]
-        OriginFilter["OriginSanitizerFilter"]
-    end
-
-    subgraph routing_layer["Routing & Proxy Layer"]
-        IntegrationCtrl["IntegrationController"]
-        WsConfig["WebSocketGatewayConfig"]
-        UpstreamResolvers["ToolUpstreamResolvers"]
-    end
-
-    Gateway --> security_layer
-    security_layer --> routing_layer
-    routing_layer --> Upstream["Integrated Tools / NATS / Services"]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-2.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-2.mmd
deleted file mode 100644
index 1c674ad9f..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-2.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Scheduler["Scheduled Job"] --> LockProvider["RedisLockProvider"]
-    LockProvider --> Redis[("Redis")]
-    Redis --> LockKey["Tenant Scoped Lock Key"]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-3.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-3.mmd
deleted file mode 100644
index 2762a6a25..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-3.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Start["Application Startup"] --> SecretInit["AgentRegistrationSecretInitializer"]
-    SecretInit --> Service["AgentRegistrationSecretManagementService"]
-    Service --> Create["createInitialSecret()"]
-    Create --> Processor["DefaultAgentRegistrationSecretManagementProcessor"]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-4.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-4.mmd
deleted file mode 100644
index b31c2e02b..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Init["NatsStreamConfigurationInitializer"] --> DefaultStreams["Default Stream Configurations"]
-    Init --> Additional["AdditionalStreamConfigurationProvider"]
-    DefaultStreams --> NatsService["NatsStreamManagementService"]
-    Additional --> NatsService
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-5.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-5.mmd
deleted file mode 100644
index beb2eac54..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-5.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Startup["Application Startup"] --> LoadTool["Load Tactical RMM Tool"]
-    LoadTool --> FetchScripts["Fetch Existing Scripts"]
-    FetchScripts --> Compare["Compare by Name"]
-    Compare -->|"Missing"| Create["Create Script"]
-    Compare -->|"Exists"| Update["Update Script"]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-6.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-6.mmd
deleted file mode 100644
index 6b701a8a0..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-6.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Tick["Scheduled Tick"] --> ClientCheck["Check Client PublishState"]
-    ClientCheck --> RetryClient["Publish If Needed"]
-    Tick --> AgentCheck["Check Tool Agents"]
-    AgentCheck --> RetryAgent["Publish If Needed"]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-7.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-7.mmd
deleted file mode 100644
index d13f80b57..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-7.mmd
+++ /dev/null
@@ -1,3 +0,0 @@
-flowchart LR
-    Scheduler["Heartbeat Scheduler"] --> Service["DeviceHeartbeatOfflineDetectionService"]
-    Service --> Mongo[("MongoDB Device Records")]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-8.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-8.mmd
deleted file mode 100644
index 434e76c29..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-8.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Client["API Client"] --> Controller["IntegratedToolController"]
-    Controller --> Save["IntegratedToolService.saveTool()"]
-    Save --> TenantCheck["TenantIdProvider"]
-    TenantCheck -->|"Registered"| Debezium["DebeziumService"]
-    Save --> Hooks["IntegratedToolPostSaveHook"]
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-9.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-9.mmd
deleted file mode 100644
index f545d4e47..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers-9.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Boot["Application Boot"] --> Initializers
-    Initializers --> Messaging["NATS Streams Ready"]
-    Messaging --> Schedulers
-    Schedulers --> External["External Systems"]
-    Controllers --> External
diff --git a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers.mmd b/docs/diagrams/architecture/management-service-core-initializers-and-schedulers.mmd
deleted file mode 100644
index 7da107187..000000000
--- a/docs/diagrams/architecture/management-service-core-initializers-and-schedulers.mmd
+++ /dev/null
@@ -1,33 +0,0 @@
-flowchart TD
-    subgraph ConfigLayer["Configuration Layer"]
-        MgmtConfig["ManagementConfiguration"]
-        RetryConfig["RetryConfiguration"]
-        ShedLock["ShedLockConfig"]
-    end
-
-    subgraph Initializers["Startup Initializers"]
-        SecretInit["AgentRegistrationSecretInitializer"]
-        AgentInit["IntegratedToolAgentInitializer"]
-        NatsInit["NatsStreamConfigurationInitializer"]
-        ClientInit["OpenFrameClientConfigurationInitializer"]
-        TacticalInit["TacticalRmmScriptsInitializer"]
-    end
-
-    subgraph Schedulers["Background Schedulers"]
-        VersionFallback["AgentVersionUpdatePublishFallbackScheduler"]
-        ApiKeySync["ApiKeyStatsSyncScheduler"]
-        Heartbeat["DeviceHeartbeatOfflineDetectionScheduler"]
-        FleetMdm["FleetMdmSetupScheduler"]
-    end
-
-    subgraph Controllers["Operational Controllers"]
-        ToolCtrl["IntegratedToolController"]
-        PinotCtrl["DevicePinotResyncController"]
-        ReleaseCtrl["ReleaseVersionController"]
-    end
-
-    MgmtConfig --> Initializers
-    ShedLock --> Schedulers
-    RetryConfig --> Schedulers
-    Controllers --> Schedulers
-    Initializers --> Schedulers
diff --git a/docs/diagrams/architecture/processors-2.mmd b/docs/diagrams/architecture/processors-2.mmd
deleted file mode 100644
index f5990ef98..000000000
--- a/docs/diagrams/architecture/processors-2.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    Generator["Secret Generation Logic"] --> Persist["Persist AgentRegistrationSecret"]
-    Persist --> ProcessorCall["postProcessSecretGenerated()"]
-    ProcessorCall --> DefaultProcessor["DefaultAgentRegistrationSecretProcessor"]
diff --git a/docs/diagrams/architecture/processors-3.mmd b/docs/diagrams/architecture/processors-3.mmd
deleted file mode 100644
index 6a9ee343e..000000000
--- a/docs/diagrams/architecture/processors-3.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    InvitationService["Invitation Service"] --> SaveInvitation["Persist Invitation"]
-    SaveInvitation --> ProcessorHook["postProcessInvitationCreated()"]
-    ProcessorHook --> DefaultInvitationProcessor["DefaultInvitationProcessor"]
diff --git a/docs/diagrams/architecture/processors-4.mmd b/docs/diagrams/architecture/processors-4.mmd
deleted file mode 100644
index 695fd9f01..000000000
--- a/docs/diagrams/architecture/processors-4.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    SSOService["SSOConfigService"] --> SaveConfig["Persist SSOConfig"]
-    SaveConfig --> ProcessorHook["postProcessConfigSaved()"]
-    ProcessorHook --> DefaultSSOProcessor["DefaultSSOConfigProcessor"]
diff --git a/docs/diagrams/architecture/processors-5.mmd b/docs/diagrams/architecture/processors-5.mmd
deleted file mode 100644
index e24006f05..000000000
--- a/docs/diagrams/architecture/processors-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    UserController["UserController"] --> UserService["UserService"]
-    UserService --> PersistUser["Persist User"]
-    PersistUser --> ProcessorHook["postProcessUserUpdated()"]
-    ProcessorHook --> DefaultUserProcessor["DefaultUserProcessor"]
diff --git a/docs/diagrams/architecture/processors-6.mmd b/docs/diagrams/architecture/processors-6.mmd
deleted file mode 100644
index e738e3e2e..000000000
--- a/docs/diagrams/architecture/processors-6.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart TD
-    SpringContext["Spring Application Context"] --> CheckCustom["Custom Bean Present?"]
-    CheckCustom -->|"Yes"| UseCustom["Use Custom Implementation"]
-    CheckCustom -->|"No"| UseDefault["Use Default Implementation"]
diff --git a/docs/diagrams/architecture/processors-7.mmd b/docs/diagrams/architecture/processors-7.mmd
deleted file mode 100644
index 13c39d0d0..000000000
--- a/docs/diagrams/architecture/processors-7.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    Services["Services Module"] -->|"Business Logic"| Domain["Domain Model"]
-    Services -->|"Calls"| Processors["Processors Module"]
-    Processors -->|"Side Effects"| ExternalSystems["External Systems"]
diff --git a/docs/diagrams/architecture/processors-8.mmd b/docs/diagrams/architecture/processors-8.mmd
deleted file mode 100644
index 6394e195e..000000000
--- a/docs/diagrams/architecture/processors-8.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    API["API Layer"] --> ServiceLayer["Service Layer"]
-    ServiceLayer --> RepositoryLayer["Repository Layer"]
-    ServiceLayer --> ProcessorLayer["Processors"]
-    ProcessorLayer --> Integration["Integrations / Events / Audit"]
diff --git a/docs/diagrams/architecture/processors.mmd b/docs/diagrams/architecture/processors.mmd
deleted file mode 100644
index 8b6c815e4..000000000
--- a/docs/diagrams/architecture/processors.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    Controller["REST or GraphQL Controller"] --> Service["Core Service"]
-    Service --> DomainModel["Domain Model"]
-    Service --> Processor["Processor Interface"]
-    Processor --> DefaultImpl["Default Implementation"]
-    Processor --> CustomImpl["Custom Implementation (Optional)"]
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-2.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-2.mmd
deleted file mode 100644
index 7ee915858..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-2.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-flowchart TD
-    JwtConfig["JwtConfig"] -->|"loadPublicKey()"| PublicKey["RSAPublicKey"]
-    JwtConfig -->|"loadPrivateKey()"| PrivateKey["RSAPrivateKey"]
-
-    PublicKey --> RsaKey["RSAKey Builder"]
-    PrivateKey --> RsaKey
-
-    RsaKey --> JwkSet["JWKSet"]
-    JwkSet --> JwtEncoder["NimbusJwtEncoder"]
-
-    PublicKey --> JwtDecoder["NimbusJwtDecoder"]
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-3.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-3.mmd
deleted file mode 100644
index 682c32589..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    PemString["PEM Private Key"] --> StripHeaders["Remove BEGIN/END markers"]
-    StripHeaders --> Base64Decode["Base64 Decode"]
-    Base64Decode --> KeySpec["PKCS8EncodedKeySpec"]
-    KeySpec --> KeyFactory["KeyFactory RSA"]
-    KeyFactory --> RsaPrivate["RSAPrivateKey"]
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-4.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-4.mmd
deleted file mode 100644
index 57de5ec02..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-4.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart TD
-    Verifier["Code Verifier (random 32 bytes)"] --> Hash["SHA-256"]
-    Hash --> Challenge["Base64URL Encode"]
-
-    Challenge -->|"Sent to Authorization Server"| AuthServer["Authorization Server"]
-    Verifier -->|"Stored by BFF"| BffStore["State JWT / Cookie"]
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-5.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-5.mmd
deleted file mode 100644
index 6508a734f..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-5.mmd
+++ /dev/null
@@ -1,12 +0,0 @@
-sequenceDiagram
-    participant Browser
-    participant BFF as OAuth BFF Controller
-    participant Auth as Authorization Server
-
-    Browser->>BFF: GET /oauth/login
-    BFF->>Auth: Redirect with state and PKCE challenge
-    Auth->>Browser: Login UI
-    Auth->>BFF: Callback with code and state
-    BFF->>Auth: Exchange code for tokens
-    Auth->>BFF: Access and Refresh tokens
-    BFF->>Browser: Set HttpOnly cookies and redirect
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-6.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-6.mmd
deleted file mode 100644
index 32886c510..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-6.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-sequenceDiagram
-    participant Browser
-    participant BFF
-    participant Auth as Authorization Server
-
-    Browser->>BFF: POST /oauth/refresh
-    BFF->>Auth: Refresh token request
-    Auth->>BFF: New tokens
-    BFF->>Browser: Set new cookies
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-7.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-7.mmd
deleted file mode 100644
index 76d03d47e..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-7.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-sequenceDiagram
-    participant Browser
-    participant BFF
-    participant Auth as Authorization Server
-
-    Browser->>BFF: GET /oauth/logout
-    BFF->>Auth: Revoke refresh token
-    BFF->>Browser: Clear auth cookies
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff-8.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff-8.mmd
deleted file mode 100644
index add9b4272..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff-8.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Requested["Requested redirectTo"] -->|"Has value"| UseRequested["Use requested value"]
-    Requested -->|"Empty"| RefererCheck["Check Referer header"]
-    RefererCheck -->|"Present"| UseReferer["Use Referer"]
-    RefererCheck -->|"Missing"| DefaultRoot["Use /"]
diff --git a/docs/diagrams/architecture/security-core-and-oauth-bff.mmd b/docs/diagrams/architecture/security-core-and-oauth-bff.mmd
deleted file mode 100644
index 6b9d48043..000000000
--- a/docs/diagrams/architecture/security-core-and-oauth-bff.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart LR
-    Browser["Browser Client"] -->|"GET /oauth/login"| Bff["OAuth BFF Controller"]
-    Bff -->|"Redirect to authorize"| AuthServer["Authorization Server"]
-    AuthServer -->|"Callback with code"| Bff
-    Bff -->|"Exchange code for tokens"| AuthServer
-    Bff -->|"Set HttpOnly Cookies"| Browser
-
-    Browser -->|"API calls with cookies"| Gateway["Gateway Service"]
-    Gateway -->|"Validate JWT"| JwtDecoder["JwtDecoder Bean"]
diff --git a/docs/diagrams/architecture/services-2.mmd b/docs/diagrams/architecture/services-2.mmd
deleted file mode 100644
index cf3d02dd0..000000000
--- a/docs/diagrams/architecture/services-2.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    Request["User Update Request"] --> Load["Load User from Repository"]
-    Load --> Check{"User Exists?"}
-    Check -->|"No"| Error["Throw IllegalArgumentException"]
-    Check -->|"Yes"| Modify["Apply Field Updates"]
-    Modify --> Save["Save via UserRepository"]
-    Save --> PostProcess["UserProcessor.postProcessUserUpdated()"]
-    PostProcess --> Response["Return UserResponse"]
diff --git a/docs/diagrams/architecture/services-3.mmd b/docs/diagrams/architecture/services-3.mmd
deleted file mode 100644
index 0dcbea462..000000000
--- a/docs/diagrams/architecture/services-3.mmd
+++ /dev/null
@@ -1,9 +0,0 @@
-flowchart TD
-    DeleteRequest["Soft Delete Request"] --> LoadUser["Load User"]
-    LoadUser --> SelfCheck{"Requester == Target?"}
-    SelfCheck -->|"Yes"| SelfError["Throw Self Delete Exception"]
-    SelfCheck -->|"No"| OwnerCheck{"Has OWNER Role?"}
-    OwnerCheck -->|"Yes"| OwnerError["Throw OperationNotAllowedException"]
-    OwnerCheck -->|"No"| MarkDeleted["Set Status = DELETED"]
-    MarkDeleted --> SaveDeleted["Save User"]
-    SaveDeleted --> PostDelete["UserProcessor.postProcessUserDeleted()"]
diff --git a/docs/diagrams/architecture/services-4.mmd b/docs/diagrams/architecture/services-4.mmd
deleted file mode 100644
index 38db55be0..000000000
--- a/docs/diagrams/architecture/services-4.mmd
+++ /dev/null
@@ -1,8 +0,0 @@
-flowchart TD
-    AdminRequest["Upsert SSOConfigRequest"] --> Validate["validateAutoProvision()"]
-    Validate --> Normalize["Normalize Domains"]
-    Normalize --> DomainValidation["DomainValidationService.validate*"]
-    DomainValidation --> Encrypt["Encrypt Client Secret"]
-    Encrypt --> SaveConfig["Save via SSOConfigRepository"]
-    SaveConfig --> PostProcess["SSOConfigProcessor.postProcessConfigSaved()"]
-    PostProcess --> ReturnResponse["Return SSOConfigResponse"]
diff --git a/docs/diagrams/architecture/services-5.mmd b/docs/diagrams/architecture/services-5.mmd
deleted file mode 100644
index d5f4c90fe..000000000
--- a/docs/diagrams/architecture/services-5.mmd
+++ /dev/null
@@ -1,4 +0,0 @@
-flowchart LR
-    DomainService["DomainValidationService"] --> Interface["DomainExistenceValidator"]
-    Interface --> DefaultImpl["DefaultDomainExistenceValidator"]
-    Interface --> CustomImpl["SaaS Override Implementation"]
diff --git a/docs/diagrams/architecture/services-6.mmd b/docs/diagrams/architecture/services-6.mmd
deleted file mode 100644
index 5627a721f..000000000
--- a/docs/diagrams/architecture/services-6.mmd
+++ /dev/null
@@ -1,11 +0,0 @@
-sequenceDiagram
-    participant Controller
-    participant Service
-    participant Repository
-    participant Processor
-
-    Controller->>Service: Update Request
-    Service->>Repository: Save Entity
-    Repository-->>Service: Saved Entity
-    Service->>Processor: postProcess(...)
-    Service-->>Controller: Response DTO
diff --git a/docs/diagrams/architecture/services-7.mmd b/docs/diagrams/architecture/services-7.mmd
deleted file mode 100644
index 9ffceb5d9..000000000
--- a/docs/diagrams/architecture/services-7.mmd
+++ /dev/null
@@ -1,7 +0,0 @@
-flowchart TD
-    Client["Client Application"] --> Gateway["Gateway Service"]
-    Gateway --> ApiCore["API Service Core"]
-    ApiCore --> ServicesNode["Services Module"]
-    ServicesNode --> Mongo[("MongoDB")]
-    ServicesNode --> Authz["Authorization Service"]
-    ServicesNode --> Crypto["Encryption Service"]
diff --git a/docs/diagrams/architecture/services.mmd b/docs/diagrams/architecture/services.mmd
deleted file mode 100644
index b3c9c9b9e..000000000
--- a/docs/diagrams/architecture/services.mmd
+++ /dev/null
@@ -1,26 +0,0 @@
-flowchart LR
-    subgraph Controllers["API Layer"]
-        RestControllers["REST Controllers"]
-        GraphQL["GraphQL DataFetchers"]
-    end
-
-    subgraph ServicesLayer["Services Module"]
-        UserServiceNode["UserService"]
-        SSOServiceNode["SSOConfigService"]
-        DomainValidator["DefaultDomainExistenceValidator"]
-    end
-
-    subgraph Processors["Processors"]
-        UserProcessorNode["UserProcessor"]
-        SSOProcessorNode["SSOConfigProcessor"]
-    end
-
-    subgraph DataLayer["Data Layer"]
-        UserRepo["UserRepository"]
-        SSORepo["SSOConfigRepository"]
-        MongoDocs["Mongo Domain Models"]
-    end
-
-    Controllers --> ServicesLayer
-    ServicesLayer --> Processors
-    ServicesLayer --> DataLayer
diff --git a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-2.mmd b/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-2.mmd
deleted file mode 100644
index 90b3c0db9..000000000
--- a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-2.mmd
+++ /dev/null
@@ -1,10 +0,0 @@
-flowchart TD
-    A["Kafka Debezium Event"] --> B["JsonKafkaListener"]
-    B --> C["GenericJsonMessageProcessor"]
-    C --> D["Tool-Specific Deserializer"]
-    D --> E["Unified DeserializedDebeziumMessage"]
-    E --> F["IntegratedToolDataEnrichmentService"]
-    F --> G["EventTypeMapper"]
-    G --> H["DebeziumMessageHandler"]
-    H --> I["Destination Handler"]
-    I --> J["Cassandra or Kafka"]
diff --git a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-3.mmd b/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-3.mmd
deleted file mode 100644
index e3f6fdecd..000000000
--- a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-3.mmd
+++ /dev/null
@@ -1,6 +0,0 @@
-flowchart LR
-    ActivityTopic["Fleet Activities"] --> Join
-    HostActivityTopic["Fleet Host Activities"] --> Join
-    Join["Left Join (5s Window)"] --> Enriched["Enriched ActivityMessage"]
-    Enriched --> HeaderAdder["Add MESSAGE_TYPE_HEADER"]
-    HeaderAdder --> OutputTopic["Fleet MDM Events Topic"]
diff --git a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-4.mmd b/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-4.mmd
deleted file mode 100644
index 021b220e7..000000000
--- a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-4.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart LR
-    ToolType["IntegratedToolType"] --> Key
-    SourceType["Source Event Type"] --> Key
-    Key["tool:sourceType"] --> Mapper["EventTypeMapper"]
-    Mapper --> Unified["UnifiedEventType"]
diff --git a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-5.mmd b/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-5.mmd
deleted file mode 100644
index 260c90f84..000000000
--- a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers-5.mmd
+++ /dev/null
@@ -1,5 +0,0 @@
-flowchart TD
-    Event["DeserializedDebeziumMessage"] --> MachineLookup["MachineIdCacheService"]
-    MachineLookup --> OrgLookup["Organization Cache"]
-    OrgLookup --> TenantResolution["TenantIdProvider or ClusterTenantIdResolver"]
-    TenantResolution --> Enriched["IntegratedToolEnrichedData"]
diff --git a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers.mmd b/docs/diagrams/architecture/stream-service-core-kafka-and-handlers.mmd
deleted file mode 100644
index 27fcc8807..000000000
--- a/docs/diagrams/architecture/stream-service-core-kafka-and-handlers.mmd
+++ /dev/null
@@ -1,43 +0,0 @@
-flowchart LR
-    subgraph Tools["Integrated Tools"]
-        MeshCentral["MeshCentral"]
-        Tactical["Tactical RMM"]
-        Fleet["Fleet MDM"]
-    end
-
-    subgraph KafkaIn["Inbound Kafka Topics"]
-        InTopics["Debezium Topics"]
-    end
-
-    subgraph StreamCore["Stream Service Core Kafka And Handlers"]
-        Listener["JsonKafkaListener"]
-        Processor["GenericJsonMessageProcessor"]
-        Deserializer["Tool Event Deserializers"]
-        Enrichment["IntegratedToolDataEnrichmentService"]
-        Mapper["EventTypeMapper"]
-        Handler["DebeziumMessageHandler"]
-        CassandraHandler["DebeziumCassandraMessageHandler"]
-        TenantKafkaHandler["TenantDebeziumKafkaMessageHandler"]
-    end
-
-    subgraph Storage["Storage & Downstream"]
-        Cassandra["Cassandra UnifiedLogEvent"]
-        KafkaOut["Outbound Kafka Topics"]
-    end
-
-    MeshCentral --> InTopics
-    Tactical --> InTopics
-    Fleet --> InTopics
-
-    InTopics --> Listener
-    Listener --> Processor
-    Processor --> Deserializer
-    Deserializer --> Enrichment
-    Enrichment --> Mapper
-    Mapper --> Handler
-
-    Handler --> CassandraHandler
-    Handler --> TenantKafkaHandler
-
-    CassandraHandler --> Cassandra
-    TenantKafkaHandler --> KafkaOut
diff --git a/docs/getting-started/.gitignore b/docs/getting-started/.gitignore
deleted file mode 100644
index a5d01be52..000000000
--- a/docs/getting-started/.gitignore
+++ /dev/null
@@ -1,7 +0,0 @@
-# VoltAgent temp files
-temp/
-
-# JSON intermediate files (except schema/config)
-*.json
-!*-schema.json
-!*-config.json
diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md
deleted file mode 100644
index a9bcf6f73..000000000
--- a/docs/getting-started/first-steps.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# First Steps
-
-After completing the [Quick Start](quick-start.md), here are the first five things to explore in **openframe-oss-lib** to become productive quickly.
-
----
-
-## 1. Understand the Module Structure
-
-The repository is a Maven multi-module project. Each module is independently deployable and follows a consistent pattern:
-
-```text
-openframe-<module-name>/
-├── src/
-│   ├── main/java/com/openframe/...   # Production code
-│   └── test/java/com/openframe/...   # Unit and integration tests
-└── pom.xml                            # Module POM (inherits parent)
-```
-
-Start by reviewing the parent POM at the repository root to understand the full module list and shared dependency versions:
-
-```bash
-cat pom.xml
-```
-
-Key properties to note:
-
-| Property | Value |
-|----------|-------|
-| `revision` | Current unified version (`5.79.3`) |
-| `java.version` | `21` |
-| `spring-boot-starter-parent` | `3.3.0` |
-| `spring-cloud.version` | `2023.0.3` |
-
----
-
-## 2. Explore the Core Domain Model
-
-The best entry point for understanding the data model is `openframe-data-mongo-common`. This module defines all MongoDB documents:
-
-```bash
-ls openframe-data-mongo-common/src/main/java/com/openframe/data/document/
-```
-
-Key domain areas:
-
-| Package | Domain |
-|---------|--------|
-| `device/` | `Device`, `Machine`, `DeviceHealth` |
-| `organization/` | `Organization`, `ContactInformation` |
-| `user/` | `User`, `AuthUser`, `Invitation` |
-| `ticket/` | `Ticket`, `TicketNote`, `TicketAttachment` |
-| `tool/` | `IntegratedTool`, `ToolConnection`, `ToolCredentials` |
-| `notification/` | `Notification`, `NotificationContext`, `ReadStatus` |
-| `tenant/` | `Tenant`, `TenantKey`, `SSOPerTenantConfig` |
-| `oauth/` | `MongoRegisteredClient`, `OAuthToken` |
-
-Read the domain model reference documentation for a full data-flow diagram and entity relationships:
-[./reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md](./reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md)
-
----
-
-## 3. Try the Security Modules
-
-The security stack is a critical foundation for any OpenFrame service. Explore:
-
-### `openframe-security-core`
-
-Provides JWT signing and verification:
-
-```java
-// Inject the JwtService to sign or validate tokens
-@Autowired
-private JwtService jwtService;
-```
-
-Properties to configure (in `application.yml`):
-
-```yaml
-jwt:
-  public-key: classpath:keys/public.pem
-  private-key: classpath:keys/private.pem
-  issuer: https://your-tenant.openframe.ai
-  audience: openframe-api
-```
-
-### `openframe-security-oauth`
-
-The OAuth BFF module provides ready-made endpoints for browser-based OAuth flows. To enable:
-
-```yaml
-openframe:
-  gateway:
-    oauth:
-      enable: true
-```
-
-Exposed endpoints automatically:
-
-- `GET /oauth/login`
-- `GET /oauth/callback`
-- `POST /oauth/refresh`
-- `GET /oauth/logout`
-
----
-
-## 4. Run Your First Integration Test
-
-The `openframe-data-mongo-sync` module has a comprehensive integration test suite using Testcontainers. Run it to verify your local Docker setup:
-
-```bash
-# Start Docker first, then run integration tests
-mvn verify -pl openframe-data-mongo-sync -Pfailsafe
-```
-
-Testcontainers will automatically:
-1. Pull the MongoDB Docker image
-2. Start a containerized MongoDB instance
-3. Run all `*IT.java` tests against it
-4. Tear down the container on completion
-
-Integration test classes follow the `*IT.java` naming convention (configured in the parent `maven-surefire-plugin`).
-
----
-
-## 5. Explore the Gateway Module
-
-The gateway is the entry point for all service traffic. Review:
-
-```bash
-ls openframe-gateway-service-core/src/main/java/com/openframe/gateway/
-```
-
-Key files to read:
-
-| File | Purpose |
-|------|---------|
-| `security/GatewaySecurityConfig.java` | Main reactive security filter chain |
-| `security/filter/ApiKeyAuthenticationFilter.java` | API key authentication + rate limiting |
-| `config/ws/WebSocketGatewayConfig.java` | WebSocket routing configuration |
-| `upstream/DefaultToolUpstreamResolver.java` | Tool proxy URL resolution |
-
-The gateway supports these route patterns:
-
-```text
-/api/**          → ADMIN role required
-/tools/agent/**  → AGENT role required
-/ws/tools/**     → WebSocket proxy to integrated tools
-/external-api/** → API key authentication
-```
-
----
-
-## Where to Get Help
-
-| Resource | Link |
-|----------|------|
-| OpenMSP Community (Slack) | [https://www.openmsp.ai/](https://www.openmsp.ai/) |
-| OpenFrame Platform | [https://openframe.ai](https://openframe.ai) |
-| Flamingo | [https://flamingo.run](https://flamingo.run) |
-| Reference Architecture | [./reference/architecture/README.md](./reference/architecture/README.md) |
-
-> **Note:** We use Slack for all community support and discussions. Please join the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) instead of creating GitHub Issues.
-
----
-
-## What to Explore Next
-
-Once comfortable with the basics:
-
-- Review the **Authorization Service** to understand multi-tenant JWT issuance
-- Explore **Stream Service Core** for Kafka / Debezium event processing
-- Look at **Management Service Core** for startup initializers and schedulers
-- Check the **External API Service** for integration patterns
-
-All reference documentation is available under:
-[./reference/architecture/](./reference/architecture/)
-
-[![OpenFrame v0.3.7 - Enhanced Developer Experience](https://img.youtube.com/vi/O8hbBO5Mym8/maxresdefault.jpg)](https://www.youtube.com/watch?v=O8hbBO5Mym8)
diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md
deleted file mode 100644
index 1bcf37af4..000000000
--- a/docs/getting-started/introduction.md
+++ /dev/null
@@ -1,136 +0,0 @@
-# OpenFrame OSS Lib — Introduction
-
-**openframe-oss-lib** is the foundational backend library powering the [OpenFrame](https://openframe.ai) platform — the AI-driven, open-source MSP infrastructure stack built by [Flamingo](https://flamingo.run).
-
-This repository provides the **shared Spring Boot libraries** that every OpenFrame service is built upon: authentication, API layers, gateway routing, streaming, persistence, and more.
-
-[![OpenFrame Product Walkthrough (Beta Access)](https://img.youtube.com/vi/awc-yAnkhIo/maxresdefault.jpg)](https://www.youtube.com/watch?v=awc-yAnkhIo)
-
----
-
-## What Is OpenFrame OSS Lib?
-
-OpenFrame OSS Lib is a multi-module Maven project (Java 21, Spring Boot 3.3) that delivers the **core backend infrastructure** for the OpenFrame MSP platform. Rather than a standalone application, it is a set of reusable modules consumed by every service deployed inside an OpenFrame installation.
-
-The library covers:
-
-- **Multi-tenant authentication and authorization** — OAuth2 Authorization Server, per-tenant RSA key pairs, JWT issuance, SSO integration
-- **API service layers** — REST controllers and Relay-compliant GraphQL execution
-- **Gateway routing and security** — reactive edge gateway, API key rate limiting, WebSocket proxying
-- **Event ingestion and streaming** — Kafka / Debezium CDC processing, Kafka Streams enrichment
-- **Real-time messaging** — NATS publish/subscribe for device and tool notifications
-- **Polyglot persistence** — MongoDB (sync + reactive), Redis caching, Apache Pinot analytics, Cassandra log storage
-- **Management initializers and schedulers** — distributed ShedLock-based cluster-safe schedulers, startup bootstrapping
-- **External REST API** — API key–authenticated integration surface for third parties
-- **SDKs** — Fleet MDM and Tactical RMM Java clients
-
----
-
-## Key Features & Benefits
-
-| Feature | Description |
-|---------|-------------|
-| Multi-tenant by default | Every module is designed with tenant isolation: scoped keys, scoped caches, scoped scheduler locks |
-| Spring Boot 3.3 / Java 21 | Latest LTS Java with virtual threads ready, modern Spring Security |
-| Modular Maven structure | 30+ independent modules — include only what you need |
-| Open source, GitHub Packages | Published to GitHub Maven Packages with unified versioning |
-| Tool integrations | First-class support for Tactical RMM, Fleet MDM, MeshCentral |
-| AI-ready event model | Unified event type model enables Mingo AI and Fae agent consumption |
-| GraphQL + REST | Relay-compliant GraphQL for the internal API and versioned REST for external integrations |
-| Reactive gateway | Spring Cloud Gateway + WebFlux + Netty for high-concurrency proxying |
-
----
-
-## Target Audience
-
-This library is intended for:
-
-- **Platform engineers** building or extending OpenFrame microservices
-- **MSP developers** integrating their tooling with the OpenFrame event model
-- **Open-source contributors** improving the Flamingo/OpenFrame ecosystem
-
-> **Community:** Questions, discussions, and support happen on the [OpenMSP Slack Community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA). We don't use GitHub Issues.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    Client["Client / Browser / Agent"] --> Gateway["Gateway Service Core"]
-    Gateway --> ExternalAPI["External API Service"]
-    Gateway --> ApiCore["API Service Core (GraphQL + REST)"]
-
-    ApiCore --> Authz["Authorization Service Core"]
-    ApiCore --> Stream["Stream Service Core (Kafka)"]
-    ApiCore --> Management["Management Service Core"]
-
-    Authz --> Mongo["MongoDB"]
-    ApiCore --> Mongo
-    Stream --> Kafka["Kafka / Debezium"]
-    Stream --> Pinot["Apache Pinot"]
-    ApiCore --> Redis["Redis"]
-    Management --> NATS["NATS"]
-```
-
----
-
-## Module Overview
-
-The library is organized into functional groups:
-
-```mermaid
-graph LR
-    subgraph apiFoundation["API Foundation"]
-        A1["openframe-api-lib"]
-        A2["openframe-api-service-core"]
-    end
-    subgraph auth["Authorization"]
-        B1["openframe-authorization-service-core"]
-        B2["openframe-security-core"]
-        B3["openframe-security-oauth"]
-    end
-    subgraph gateway["Gateway"]
-        C1["openframe-gateway-service-core"]
-    end
-    subgraph data["Data Layer"]
-        D1["openframe-data-mongo-*"]
-        D2["openframe-data-redis"]
-        D3["openframe-data-kafka"]
-        D4["openframe-data-nats"]
-        D5["openframe-data-cassandra"]
-        D6["openframe-data-pinot"]
-    end
-    subgraph tools["Tool SDKs"]
-        E1["sdk/fleetmdm"]
-        E2["sdk/tacticalrmm"]
-    end
-    subgraph management["Management"]
-        F1["openframe-management-service-core"]
-        F2["openframe-stream-service-core"]
-    end
-```
-
----
-
-## Current Version
-
-The current library version is **5.79.3** — published to [GitHub Packages](https://github.com/flamingo-stack/openframe-oss-lib).
-
----
-
-## Links & Resources
-
-- **OpenFrame Platform:** [https://openframe.ai](https://openframe.ai)
-- **Flamingo:** [https://flamingo.run](https://flamingo.run)
-- **GitHub Repository:** [https://github.com/flamingo-stack/openframe-oss-lib](https://github.com/flamingo-stack/openframe-oss-lib)
-- **OpenMSP Community (Slack):** [https://www.openmsp.ai/](https://www.openmsp.ai/)
-- **Reference Architecture Docs:** [./reference/architecture/README.md](./reference/architecture/README.md)
-
----
-
-## Next Steps
-
-- Review the [Prerequisites Guide](prerequisites.md) for environment requirements
-- Follow the [Quick Start Guide](quick-start.md) to set up the library
-- Explore [First Steps](first-steps.md) to understand the key modules
diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md
deleted file mode 100644
index 8a194c1e6..000000000
--- a/docs/getting-started/prerequisites.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# Prerequisites
-
-Before working with **openframe-oss-lib**, ensure your development environment meets all requirements below.
-
----
-
-## Required Software
-
-| Tool | Minimum Version | Purpose |
-|------|----------------|---------|
-| Java (JDK) | 21 | Required by all modules (Spring Boot 3.3 baseline) |
-| Apache Maven | 3.9+ | Build and dependency management |
-| Git | 2.x | Source code management |
-| Docker | 24.x | Running integration test containers |
-| Node.js | 20+ | Required for the documentation tooling (`package.json` present) |
-
----
-
-## Java Version
-
-This library targets **Java 21** (LTS). Ensure your `JAVA_HOME` points to a Java 21 JDK:
-
-```bash
-java -version
-# Should output: openjdk 21.x.x ...
-```
-
-Recommended distributions:
-
-- [Eclipse Temurin 21](https://adoptium.net/)
-- [Amazon Corretto 21](https://aws.amazon.com/corretto/)
-- [GraalVM 21](https://www.graalvm.org/)
-
----
-
-## Maven
-
-Maven 3.9 or higher is required:
-
-```bash
-mvn -version
-# Apache Maven 3.9.x ...
-```
-
-The project uses the `flatten-maven-plugin` for CI-friendly versioning (`${revision}`), so Maven 3.9+ is required for proper resolution.
-
----
-
-## GitHub Packages Access
-
-The library is published to **GitHub Maven Packages**. To consume it as a dependency in downstream services you need a GitHub Personal Access Token (PAT) with `read:packages` permission.
-
-Add to `~/.m2/settings.xml`:
-
-```xml
-<settings>
-  <servers>
-    <server>
-      <id>github</id>
-      <username>YOUR_GITHUB_USERNAME</username>
-      <password>YOUR_GITHUB_PAT</password>
-    </server>
-  </servers>
-</settings>
-```
-
-> Your `GITHUB_PAT` must have the `read:packages` scope to resolve dependencies, and `write:packages` to publish new versions.
-
----
-
-## Infrastructure Services (for Integration Tests)
-
-Some modules run integration tests against live services via Testcontainers. Ensure Docker is running and the following images can be pulled:
-
-| Service | Used By |
-|---------|---------|
-| MongoDB | `openframe-data-mongo-sync`, `openframe-api-service-core` integration tests |
-| NATS | `openframe-data-nats` integration tests |
-
-Testcontainers will automatically spin up and tear down containers during integration test execution. The only requirement is a running Docker daemon.
-
-```bash
-docker info
-# Should not return an error
-```
-
----
-
-## Environment Variables
-
-The following environment variables may be needed depending on which modules you are developing:
-
-| Variable | Required For | Description |
-|----------|-------------|-------------|
-| `GITHUB_ACTOR` | Publishing | GitHub username for package publishing |
-| `GITHUB_TOKEN` | Publishing | GitHub PAT for package publishing |
-
-For local development without publishing, only local Maven settings are needed.
-
----
-
-## Recommended IDE
-
-| IDE | Notes |
-|-----|-------|
-| IntelliJ IDEA (Ultimate or Community) | Best support for Spring Boot, Maven multi-module, Lombok |
-| VS Code + Java Extension Pack | Alternative for lighter setup |
-
-### IntelliJ Setup Checklist
-
-1. Import as **Maven project** (not Gradle)
-2. Set **Project SDK** to Java 21
-3. Enable **Annotation Processors** for Lombok support
-4. Set Maven delegate: `Settings → Build Tools → Maven → Runner → Delegate IDE build/run actions to Maven`
-
----
-
-## Verification Commands
-
-Run these checks before beginning development:
-
-```bash
-# Verify Java version
-java -version
-
-# Verify Maven version
-mvn -version
-
-# Verify Docker is running
-docker info
-
-# Verify Git configuration
-git config user.name
-git config user.email
-
-# Verify GitHub Packages access (requires settings.xml configured)
-mvn dependency:resolve -pl openframe-core -q
-```
-
----
-
-## System Requirements
-
-| Resource | Minimum | Recommended |
-|----------|---------|-------------|
-| RAM | 8 GB | 16 GB |
-| Disk | 5 GB free | 20 GB free |
-| CPU | 4 cores | 8+ cores |
-| OS | macOS, Linux, Windows (WSL2) | macOS or Linux |
-
-> Building the entire repository (`mvn install`) compiles 30+ modules. Sufficient RAM (especially heap) prevents OOM during compilation.
-
-To increase Maven heap:
-
-```bash
-export MAVEN_OPTS="-Xmx4g -XX:MaxMetaspaceSize=512m"
-```
-
----
-
-## Community & Support
-
-If you run into setup issues, reach out on the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA).
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
deleted file mode 100644
index 8237d6d25..000000000
--- a/docs/getting-started/quick-start.md
+++ /dev/null
@@ -1,200 +0,0 @@
-# Quick Start
-
-Get up and running with **openframe-oss-lib** in 5 minutes.
-
----
-
-## TL;DR
-
-```bash
-# 1. Clone the repository
-git clone https://github.com/flamingo-stack/openframe-oss-lib.git
-cd openframe-oss-lib
-
-# 2. Build the full library (skip tests for speed)
-mvn install -DskipTests
-
-# 3. Verify the build
-mvn verify -pl openframe-core -DskipTests
-```
-
----
-
-## Step 1 — Clone the Repository
-
-```bash
-git clone https://github.com/flamingo-stack/openframe-oss-lib.git
-cd openframe-oss-lib
-```
-
-The repository contains 30+ Maven modules under a single parent POM at the root.
-
----
-
-## Step 2 — Configure GitHub Packages (Required for Dependency Resolution)
-
-Add your GitHub credentials to `~/.m2/settings.xml`:
-
-```xml
-<settings>
-  <servers>
-    <server>
-      <id>github</id>
-      <username>YOUR_GITHUB_USERNAME</username>
-      <password>YOUR_GITHUB_PAT</password>
-    </server>
-  </servers>
-</settings>
-```
-
-> A GitHub Personal Access Token (PAT) with `read:packages` scope is required. See the [Prerequisites Guide](prerequisites.md) for details.
-
----
-
-## Step 3 — Build the Library
-
-Build all modules without running tests for the fastest initial setup:
-
-```bash
-mvn install -DskipTests
-```
-
-Expected output:
-
-```text
-[INFO] Reactor Summary for OpenFrame OSS Libraries 5.79.3:
-[INFO]
-[INFO] openframe-exception ....................  SUCCESS [  3.5 s]
-[INFO] openframe-core ........................  SUCCESS [  2.1 s]
-[INFO] openframe-core-crypto .................  SUCCESS [  1.8 s]
-[INFO] openframe-data-mongo-common ...........  SUCCESS [  4.2 s]
-...
-[INFO] BUILD SUCCESS
-```
-
----
-
-## Step 4 — Add a Module as a Dependency
-
-To use a specific module in your own Spring Boot service, add the parent BOM and the desired dependency to your `pom.xml`:
-
-```xml
-<dependencyManagement>
-  <dependencies>
-    <!-- Import the OpenFrame OSS BOM -->
-    <dependency>
-      <groupId>com.openframe.oss</groupId>
-      <artifactId>openframe-oss-lib</artifactId>
-      <version>5.79.3</version>
-      <type>pom</type>
-      <scope>import</scope>
-    </dependency>
-  </dependencies>
-</dependencyManagement>
-
-<dependencies>
-  <!-- Example: Add core module -->
-  <dependency>
-    <groupId>com.openframe.oss</groupId>
-    <artifactId>openframe-core</artifactId>
-  </dependency>
-
-  <!-- Example: Add MongoDB sync support -->
-  <dependency>
-    <groupId>com.openframe.oss</groupId>
-    <artifactId>openframe-data-mongo-sync</artifactId>
-  </dependency>
-
-  <!-- Example: Add API service core -->
-  <dependency>
-    <groupId>com.openframe.oss</groupId>
-    <artifactId>openframe-api-service-core</artifactId>
-  </dependency>
-</dependencies>
-```
-
----
-
-## Step 5 — Run Tests for a Specific Module
-
-To run tests for a single module:
-
-```bash
-# Run unit tests only for a specific module
-mvn test -pl openframe-core
-
-# Run integration tests (requires Docker)
-mvn verify -pl openframe-data-mongo-sync
-```
-
-> Integration tests use Testcontainers and require a running Docker daemon.
-
----
-
-## Available Modules — Quick Reference
-
-| Module | GroupId | Description |
-|--------|---------|-------------|
-| `openframe-core` | `com.openframe.oss` | Core utilities, pagination, validation |
-| `openframe-exception` | `com.openframe.oss` | Standard exception hierarchy |
-| `openframe-core-crypto` | `com.openframe.oss` | Encryption utilities |
-| `openframe-security-core` | `com.openframe.oss` | JWT, PKCE, cookie service |
-| `openframe-security-oauth` | `com.openframe.oss` | OAuth2 BFF layer |
-| `openframe-authorization-service-core` | `com.openframe.oss` | Multi-tenant OAuth2 auth server |
-| `openframe-api-lib` | `com.openframe.oss` | API contracts, filter DTOs |
-| `openframe-api-service-core` | `com.openframe.oss` | REST + GraphQL API service layer |
-| `openframe-gateway-service-core` | `com.openframe.oss` | Reactive gateway, routing, security |
-| `openframe-data-mongo-common` | `com.openframe.oss` | MongoDB domain documents |
-| `openframe-data-mongo-sync` | `com.openframe.oss` | Synchronous MongoDB repositories |
-| `openframe-data-mongo-reactive` | `com.openframe.oss` | Reactive MongoDB repositories |
-| `openframe-data-redis` | `com.openframe.oss` | Redis cache configuration |
-| `openframe-data-kafka` | `com.openframe.oss` | Kafka multi-tenant configuration |
-| `openframe-data-nats` | `com.openframe.oss` | NATS real-time messaging |
-| `openframe-data-cassandra` | `com.openframe.oss` | Cassandra log storage |
-| `openframe-data-pinot` | `com.openframe.oss` | Apache Pinot analytics |
-| `openframe-management-service-core` | `com.openframe.oss` | Schedulers, initializers |
-| `openframe-stream-service-core` | `com.openframe.oss` | Kafka streams, event enrichment |
-| `openframe-external-api-service-core` | `com.openframe.oss` | External REST API |
-| `sdk/fleetmdm` | `com.openframe.oss` | Fleet MDM Java SDK |
-| `sdk/tacticalrmm` | `com.openframe.oss` | Tactical RMM Java SDK |
-
----
-
-## Expected Results
-
-After a successful `mvn install -DskipTests` you should see:
-
-```text
-[INFO] BUILD SUCCESS
-[INFO] Total time: 2-4 minutes (depending on hardware)
-[INFO] Finished at: ...
-```
-
-All modules are installed into your local Maven repository (`~/.m2/repository/com/openframe/oss/`).
-
----
-
-## Video Walkthrough
-
-[![Getting Started with OpenFrame - Organization Setup Basics](https://img.youtube.com/vi/-_56_qYvMWk/maxresdefault.jpg)](https://www.youtube.com/watch?v=-_56_qYvMWk)
-
----
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|---------|
-| `Could not resolve dependencies` | Check `~/.m2/settings.xml` for GitHub credentials |
-| `OutOfMemoryError` during build | Set `export MAVEN_OPTS="-Xmx4g"` |
-| Integration tests fail | Ensure Docker daemon is running |
-| `flatten-maven-plugin` errors | Upgrade Maven to 3.9+ |
-
----
-
-## Next Steps
-
-After building successfully, explore:
-
-- [First Steps Guide](first-steps.md) for key module walkthroughs
-- [Development Environment Setup](../development/setup/environment.md) for IDE configuration
-- [Architecture Overview](../development/architecture/README.md) for system design patterns
diff --git a/docs/reference/architecture/.gitignore b/docs/reference/architecture/.gitignore
deleted file mode 100644
index b4f4c7a6c..000000000
--- a/docs/reference/architecture/.gitignore
+++ /dev/null
@@ -1,8 +0,0 @@
-# CodeWiki temp files (dependency graphs can be 7GB+)
-temp/
-dependency_graphs/
-
-# JSON intermediate files (except schema/config)
-*.json
-!*-schema.json
-!*-config.json
diff --git a/docs/reference/architecture/README.md b/docs/reference/architecture/README.md
deleted file mode 100644
index 3d2a87c5d..000000000
--- a/docs/reference/architecture/README.md
+++ /dev/null
@@ -1,447 +0,0 @@
-# OpenFrame OSS Lib – Repository Overview
-
-The **openframe-oss-lib** repository contains the foundational backend libraries powering the OpenFrame platform. It provides:
-
-- Multi-tenant authentication and authorization
-- API service layers (REST + GraphQL)
-- Gateway routing and security
-- Event ingestion and streaming (Kafka)
-- Real-time messaging (NATS)
-- Polyglot persistence (MongoDB, Redis, Pinot)
-- Management initializers and distributed schedulers
-
-This repository represents the **core backend infrastructure stack** of OpenFrame and is designed to be modular, extensible, and multi-tenant by default.
-
----
-
-# High-Level Architecture
-
-OpenFrame follows a layered, service-oriented architecture with strong separation between:
-
-- Identity & Authorization
-- API Surface (Internal + External)
-- Gateway & Edge Security
-- Stream Processing
-- Data Access Layer
-- Caching & Messaging
-- Management & Operations
-
-```mermaid
-flowchart TD
-    Client["Client / Browser / Agent"] --> Gateway["Gateway Service Core"]
-    Gateway --> ExternalAPI["External API Service"]
-    Gateway --> ApiCore["API Service Core"]
-
-    ApiCore --> Authz["Authorization Service Core"]
-    ApiCore --> Stream["Stream Service Core"]
-    ApiCore --> Management["Management Service Core"]
-
-    Authz --> Mongo["MongoDB"]
-    ApiCore --> Mongo
-    Stream --> Kafka["Kafka"]
-    Stream --> Pinot["Pinot"]
-    ApiCore --> Redis["Redis"]
-    Management --> NATS["NATS"]
-```
-
----
-
-# Core Modules
-
-Below is a structured overview of the major modules contained in this repository.
-
----
-
-## 1. API Foundation
-
-### 🔹 `api-contracts-and-pagination`
-Defines reusable API contracts:
-
-- Relay-style pagination (`ConnectionArgs`, cursors)
-- Count-aware query results
-- Opaque cursor encoding (`CursorCodec`)
-- Standard mutation inputs
-
-📄 Core Docs:  
-- `CountedGenericQueryResult`
-- `ConnectionArgs`
-- `CursorCodec`
-- `MutationDeleteInput`
-
----
-
-### 🔹 `api-domain-filters-dtos`
-Strongly-typed filter DTOs for:
-
-- Devices
-- Events
-- Logs
-- Knowledge Base
-- Organizations
-- Tools
-
-Bridges API input → Mongo query filters.
-
----
-
-### 🔹 `api-lib-core-services`
-Reusable domain services:
-
-- Installed agent resolution
-- Tool connections
-- Ticket queries
-- Knowledge base lifecycle hooks
-- Device status processors
-
-Optimized for DataLoader and GraphQL batching.
-
----
-
-## 2. API Service Core
-
-### 🔹 REST Controllers
-Internal operational endpoints:
-
-- Organizations
-- Devices
-- Users
-- Invitations
-- SSO Config
-- API Keys
-- Release versions
-- Agent lifecycle control
-
-📄 Module: `api-service-core-rest-controllers`
-
----
-
-### 🔹 GraphQL Layer
-Relay-compliant GraphQL execution layer:
-
-- Data fetchers
-- DataLoaders
-- Relay Node resolution
-- Cursor-based pagination
-- Polymorphic type resolution
-
-📄 Modules:
-- `api-service-core-graphql-datafetchers`
-- `api-service-core-dataloaders`
-- `api-service-core-graphql-dtos`
-- `api-service-core-relay-type-resolution`
-
----
-
-### 🔹 Security & Config
-Provides:
-
-- JWT resource server config
-- Multi-issuer support
-- Custom GraphQL scalars
-- OAuth client initialization
-- Argument resolvers
-
-📄 Module: `api-service-core-config-and-security`
-
----
-
-## 3. Authorization Service Core
-
-Multi-tenant OAuth2 Authorization Server.
-
-### Capabilities
-
-- Per-tenant RSA key pairs
-- JWT issuance with `tenant_id`
-- Dynamic client registration
-- SSO flows (Google, Microsoft)
-- PKCE support
-- Invitation-based onboarding
-- Tenant discovery & registration
-
-```mermaid
-flowchart TD
-    Browser --> AuthController["Auth Controllers"]
-    AuthController --> TenantContext["TenantContextFilter"]
-    TenantContext --> AuthServer["AuthorizationServerConfig"]
-    AuthServer --> TenantKeyService["TenantKeyService"]
-    TenantKeyService --> Mongo
-    AuthServer --> JWT["Signed JWT"]
-```
-
-📄 Modules:
-- `authorization-service-core-server-and-tenant`
-- `authorization-service-core-auth-controllers-and-dtos`
-- `authorization-service-core-keys-and-authorization-persistence`
-- `authorization-service-core-sso-flow-and-utils`
-
----
-
-## 4. Gateway Service Core
-
-Reactive edge gateway built on Spring Cloud Gateway + WebFlux.
-
-### Responsibilities
-
-- JWT validation (multi-issuer)
-- Role-based authorization
-- API key authentication + rate limiting
-- WebSocket proxying
-- Tool upstream resolution
-- Origin sanitization
-- CORS enforcement
-
-```mermaid
-flowchart TD
-    Request --> OriginSanitizer
-    OriginSanitizer --> JwtAuth
-    JwtAuth --> RoleCheck
-    RoleCheck --> RouteDecision
-    RouteDecision --> ToolResolver
-    ToolResolver --> UpstreamTool
-```
-
-📄 Module: `gateway-service-core-security-and-routing`
-
----
-
-## 5. Stream Service Core (Kafka)
-
-Event ingestion and normalization backbone.
-
-### Responsibilities
-
-- Consume Debezium CDC events
-- Tool-specific deserialization
-- Event enrichment (tenant, device, org)
-- Unified event type mapping
-- Cassandra persistence
-- Kafka republishing
-- Kafka Streams enrichment
-
-```mermaid
-flowchart TD
-    DebeziumEvent --> Deserializer
-    Deserializer --> Enrichment
-    Enrichment --> EventTypeMapper
-    EventTypeMapper --> Cassandra
-    EventTypeMapper --> KafkaOut
-```
-
-📄 Module: `stream-service-core-kafka-and-handlers`
-
----
-
-## 6. Data Layer
-
-### MongoDB
-
-- Domain documents (`User`, `Organization`, `Device`, `Ticket`, etc.)
-- Base repositories (sync + reactive)
-- Custom query repositories
-- Cursor pagination logic
-- Index configuration
-
-📄 Modules:
-- `data-mongo-domain-model`
-- `data-mongo-query-filters`
-- `data-mongo-base-repositories`
-- `data-mongo-sync-config-and-custom-repositories`
-- `data-mongo-reactive-repositories`
-
----
-
-### Redis
-
-- Tenant-aware cache key prefixing
-- Spring Cache integration
-- Reactive + blocking templates
-
-📄 Module: `data-redis-cache`
-
----
-
-### Kafka
-
-- Tenant-scoped Kafka configuration
-- Topic auto-provisioning
-- Debezium message modeling
-- Retry & recovery handling
-
-📄 Module: `data-kafka-configuration-and-retry`
-
----
-
-### NATS (Real-Time Notifications)
-
-- Persist-first notification strategy
-- Read-state tracking
-- Per-recipient NATS publish
-- Graceful degradation if NATS disabled
-
-📄 Module: `data-nats-notifications`
-
----
-
-### Pinot (Analytics)
-
-- Log exploration
-- Device faceted filtering
-- High-performance aggregation queries
-
-```mermaid
-flowchart LR
-    StreamService --> PinotCluster
-    PinotCluster --> PinotRepositories
-    PinotRepositories --> ApiService
-```
-
-📄 Module: `data-pinot-repositories`
-
----
-
-## 7. Management Service Core
-
-Operational backbone of the platform.
-
-### Startup Initializers
-
-- Agent registration secret bootstrap
-- NATS stream provisioning
-- Client configuration loading
-- Tactical RMM script initialization
-
-### Distributed Schedulers (ShedLock + Redis)
-
-- Offline device detection
-- API key stats sync
-- Fleet MDM setup
-- Version publish fallback
-
-```mermaid
-flowchart TD
-    Startup --> Initializers
-    Initializers --> StreamsReady
-    StreamsReady --> Schedulers
-    Schedulers --> ExternalSystems
-```
-
-📄 Module: `management-service-core-initializers-and-schedulers`
-
----
-
-## 8. External API Service Core
-
-Public REST interface for third-party integrations.
-
-- API key–based authentication
-- Cursor-based pagination
-- Device / Event / Log / Organization APIs
-- Tool proxy endpoints
-- OpenAPI documentation
-
-📄 Module: `external-api-service-core`
-
----
-
-## 9. Security Core & OAuth BFF
-
-Frontend-safe OAuth2 BFF layer.
-
-- PKCE utilities
-- JWT encoder/decoder
-- OAuth login flow
-- Token refresh & revocation
-- HttpOnly cookie management
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant BFF
-    participant AuthServer
-
-    Browser->>BFF: GET /oauth/login
-    BFF->>AuthServer: Redirect with PKCE
-    AuthServer->>BFF: Callback with code
-    BFF->>AuthServer: Exchange code
-    BFF->>Browser: Set cookies
-```
-
-📄 Module: `security-core-and-oauth-bff`
-
----
-
-# End-to-End System View
-
-```mermaid
-flowchart TD
-    Client --> Gateway
-    Gateway --> ExternalAPI
-    Gateway --> ApiCore
-
-    ApiCore --> Authz
-    ApiCore --> Mongo
-    ApiCore --> Redis
-    ApiCore --> Pinot
-
-    Authz --> Mongo
-    Authz --> JWT
-
-    Stream --> Kafka
-    Stream --> Cassandra
-    Stream --> Pinot
-
-    Management --> Redis
-    Management --> NATS
-```
-
----
-
-# Design Principles
-
-The repository follows consistent architectural principles:
-
-1. **Multi-Tenancy First**
-   - Tenant ID embedded in JWT
-   - Tenant-scoped keys and locks
-   - Tenant-aware caching
-
-2. **Separation of Concerns**
-   - Domain model isolated from transport
-   - Query filters separate from API DTOs
-   - Gateway isolated from business logic
-
-3. **Polyglot Persistence**
-   - MongoDB → transactional
-   - Pinot → analytical
-   - Redis → caching
-   - Kafka → streaming
-   - NATS → real-time
-
-4. **Event-Driven Architecture**
-   - Debezium ingestion
-   - Kafka normalization
-   - Unified event model
-
-5. **Extensibility**
-   - Conditional beans
-   - Processor hooks
-   - Strategy patterns
-   - Pluggable resolvers
-
----
-
-# Conclusion
-
-The **openframe-oss-lib** repository is the foundational backend library stack of OpenFrame. It provides:
-
-- A multi-tenant OAuth2 authorization server
-- Internal and external API layers
-- A reactive gateway
-- Event streaming and normalization
-- Analytics querying
-- Distributed management workflows
-- Secure OAuth BFF flows
-- Polyglot data infrastructure
-
-Together, these modules form a production-grade, scalable, multi-tenant backend architecture that powers the OpenFrame platform end-to-end.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-contracts-and-pagination/api-contracts-and-pagination.md b/docs/reference/architecture/api-contracts-and-pagination/api-contracts-and-pagination.md
deleted file mode 100644
index 8072b0290..000000000
--- a/docs/reference/architecture/api-contracts-and-pagination/api-contracts-and-pagination.md
+++ /dev/null
@@ -1,329 +0,0 @@
-# Api Contracts And Pagination
-
-## Overview
-
-The **Api Contracts And Pagination** module defines the foundational API data contracts used across OpenFrame services, with a strong focus on:
-
-- Relay-style cursor-based pagination
-- Count-aware query results
-- Opaque cursor encoding and decoding
-- Standardized mutation input structures
-
-This module sits at the boundary between transport layers (REST and GraphQL) and domain/query services. It ensures consistent, predictable API behavior across the platform while hiding internal persistence details (such as MongoDB identifiers or composite keys) from API consumers.
-
----
-
-## Core Responsibilities
-
-The Api Contracts And Pagination module provides:
-
-1. **Generic query result wrappers** with total/filtered counts
-2. **Relay-compliant pagination arguments**
-3. **Opaque cursor encoding/decoding utilities**
-4. **Standard mutation input contracts (e.g., delete by ID)**
-
-These contracts are reused by:
-
-- GraphQL data fetchers
-- REST controllers
-- Domain query services
-- MongoDB custom repositories
-
----
-
-## Architectural Positioning
-
-The module acts as a shared contract layer between API entry points and data/query layers.
-
-```mermaid
-flowchart TD
-    Client["Client Application"] --> API["REST Controllers / GraphQL DataFetchers"]
-    API --> Contracts["Api Contracts And Pagination"]
-    Contracts --> Services["Domain Query Services"]
-    Services --> Repositories["Mongo Repositories"]
-    Repositories --> Database[("MongoDB")]
-```
-
-### Key Characteristics
-
-- **Transport-agnostic**: Works with both REST and GraphQL.
-- **Persistence-agnostic**: Does not expose internal database identifiers.
-- **Validation-aware**: Uses Jakarta validation annotations for input constraints.
-- **Relay-compliant**: Follows the GraphQL Relay Connection specification patterns.
-
----
-
-# Core Components
-
-## 1. CountedGenericQueryResult
-
-**Class:** `CountedGenericQueryResult<T>`  
-**Extends:** `GenericQueryResult<T>`  
-
-### Purpose
-
-Adds a `filteredCount` field to a generic query result, allowing APIs to return:
-
-- The current page of results
-- Total elements (from base class)
-- Filtered result count (after applying search/filter criteria)
-
-### Structure
-
-```text
-CountedGenericQueryResult<T>
- ├─ List<T> results
- ├─ int totalCount
- └─ int filteredCount
-```
-
-### Why It Matters
-
-This structure enables:
-
-- Efficient UI pagination
-- Accurate result counts after filtering
-- Consistent response shape across domains (devices, events, users, etc.)
-
-### Example Usage Flow
-
-```mermaid
-flowchart LR
-    Request["Query Request with Filters"] --> Service["Query Service"]
-    Service --> Repo["Custom Repository"]
-    Repo --> Result["CountedGenericQueryResult<T>"]
-    Result --> API["Serialized API Response"]
-```
-
-The `filteredCount` is especially important when:
-
-- Full dataset size is large
-- Filters significantly reduce results
-- UI must display: "Showing 10 of 245 filtered results"
-
----
-
-## 2. ConnectionArgs
-
-**Class:** `ConnectionArgs`
-
-### Purpose
-
-Defines Relay-style pagination arguments used primarily in GraphQL connections.
-
-Supports:
-
-- Forward pagination: `first` + `after`
-- Backward pagination: `last` + `before`
-
-### Field Definitions
-
-```text
-ConnectionArgs
- ├─ Integer first   (min 1, max 100)
- ├─ String after
- ├─ Integer last    (min 1, max 100)
- └─ String before
-```
-
-### Validation Rules
-
-- `first` and `last` must be between 1 and 100.
-- Validation is enforced via Jakarta annotations.
-- Prevents excessive data loading and abuse.
-
-### Pagination Model
-
-```mermaid
-flowchart TD
-    Client["Client"] --> Args["ConnectionArgs"]
-    Args --> Decode["CursorCodec.decode()"]
-    Decode --> Query["Repository Query with Limit"]
-    Query --> Encode["CursorCodec.encode()"]
-    Encode --> Response["Connection Response with Edges"]
-```
-
-### Design Principles
-
-- Hard limit (100) protects backend resources.
-- Supports bi-directional pagination.
-- Compatible with Relay Connection pattern.
-
----
-
-## 3. CursorCodec
-
-**Class:** `CursorCodec`
-
-### Purpose
-
-Encodes and decodes opaque pagination cursors using Base64.
-
-This ensures that internal cursor values such as:
-
-- MongoDB ObjectIds
-- Composite keys (e.g., "timestamp_eventId")
-- Internal database offsets
-
-are not exposed directly to API consumers.
-
-### Encoding Flow
-
-```mermaid
-flowchart LR
-    Raw["Raw Internal Cursor"] --> Encode["Base64 Encode"]
-    Encode --> Opaque["Opaque Cursor String"]
-```
-
-### Decoding Flow
-
-```mermaid
-flowchart LR
-    Opaque["Opaque Cursor"] --> Decode["Base64 Decode"]
-    Decode --> Raw["Raw Internal Cursor"]
-```
-
-### Key Behaviors
-
-- Returns `null` for null or empty input.
-- Gracefully handles invalid Base64 input.
-- Hides implementation details from clients.
-
-### Example
-
-```text
-Raw Cursor:  665fae2b3a91c87b12345678
-Encoded:     NjY1ZmFlMmIzYTkxYzg3YjEyMzQ1Njc4
-```
-
-This pattern guarantees that clients cannot infer database structure or ordering logic.
-
----
-
-## 4. MutationDeleteInput
-
-**Class:** `MutationDeleteInput`
-
-### Purpose
-
-Defines a standard mutation input structure for delete operations.
-
-### Structure
-
-```text
-MutationDeleteInput
- └─ String id  (must not be blank)
-```
-
-### Design Rationale
-
-- Enforces explicit ID-based deletion.
-- Aligns with GraphQL mutation input patterns.
-- Supports validation via `@NotBlank`.
-
-### Mutation Flow
-
-```mermaid
-flowchart TD
-    Client["Client Mutation"] --> Input["MutationDeleteInput"]
-    Input --> Validate["Validation Layer"]
-    Validate --> Service["Domain Service"]
-    Service --> Repo["Repository Delete by ID"]
-    Repo --> Response["Mutation Result"]
-```
-
----
-
-# Pagination Strategy in the Platform
-
-The Api Contracts And Pagination module supports two complementary patterns:
-
-## 1. Cursor-Based Pagination (GraphQL)
-
-Used for connection-based queries:
-
-- Forward and backward navigation
-- Opaque cursors
-- Relay compliance
-
-Benefits:
-
-- Stable pagination even with concurrent inserts
-- No reliance on numeric offsets
-- Efficient indexed queries
-
-## 2. Counted Query Results (REST or Hybrid)
-
-Used where:
-
-- UI requires total/filtered counts
-- Offset-based or filtered queries are needed
-- Simpler REST-style pagination is sufficient
-
----
-
-# End-to-End Data Flow Example
-
-Below is a complete pagination lifecycle example.
-
-```mermaid
-flowchart TD
-    Step1["Client Requests first 20 after Cursor"] --> Step2["ConnectionArgs Validated"]
-    Step2 --> Step3["CursorCodec.decode()"]
-    Step3 --> Step4["Repository Query with Limit 21"]
-    Step4 --> Step5["Determine hasNextPage"]
-    Step5 --> Step6["CursorCodec.encode() for Edges"]
-    Step6 --> Step7["Return Connection Response"]
-```
-
-### Why Fetch 21 for a Limit of 20?
-
-To determine if:
-
-- There is a next page
-- `hasNextPage` should be true
-
-This pattern ensures efficient and correct pagination semantics.
-
----
-
-# Design Principles
-
-The Api Contracts And Pagination module follows these core principles:
-
-1. **Consistency Across Domains**  
-   Devices, events, users, organizations, and tools all use uniform contracts.
-
-2. **Opaque by Default**  
-   Clients never see internal IDs or composite keys.
-
-3. **Validation at the Edge**  
-   Input constraints are enforced before hitting service layers.
-
-4. **Resource Safety**  
-   Pagination limits prevent unbounded queries.
-
-5. **Transport Layer Neutrality**  
-   Usable by both REST controllers and GraphQL data fetchers.
-
----
-
-# Summary
-
-The **Api Contracts And Pagination** module is a foundational contract layer for OpenFrame APIs.
-
-It standardizes:
-
-- How lists are queried
-- How pagination works
-- How cursors are encoded
-- How deletions are requested
-
-By centralizing these patterns, the platform achieves:
-
-- Predictable API behavior
-- Secure data exposure boundaries
-- Efficient pagination at scale
-- Strong validation guarantees
-
-This module underpins consistent API design across the entire OpenFrame ecosystem.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-domain-filters-dtos/api-domain-filters-dtos.md b/docs/reference/architecture/api-domain-filters-dtos/api-domain-filters-dtos.md
deleted file mode 100644
index 9cead9cef..000000000
--- a/docs/reference/architecture/api-domain-filters-dtos/api-domain-filters-dtos.md
+++ /dev/null
@@ -1,366 +0,0 @@
-# Api Domain Filters Dtos
-
-The **Api Domain Filters Dtos** module defines the domain-level Data Transfer Objects (DTOs) used to:
-
-- Express filtering criteria for core entities (Devices, Events, Logs, Knowledge Base, Organizations, Tools)
-- Provide structured filter metadata for UI dropdowns and faceted search
-- Standardize list and response payloads shared across REST and GraphQL layers
-
-This module acts as a **contract layer** between:
-
-- GraphQL DataFetchers and REST Controllers
-- Core services and query layers
-- Mongo query filter builders and repositories
-
-It does not contain business logic. Instead, it provides strongly typed filter contracts that drive query construction in downstream modules.
-
----
-
-## Architectural Role
-
-At a high level, Api Domain Filters Dtos sits between API input DTOs and persistence query filters.
-
-```mermaid
-flowchart LR
-    Client["Client (REST or GraphQL)"] --> ApiInput["GraphQL Input / REST Request"]
-    ApiInput --> DomainFilter["Api Domain Filters Dtos"]
-    DomainFilter --> QueryLayer["Mongo Query Filters"]
-    QueryLayer --> Repository["Mongo Repositories"]
-    Repository --> Database[("MongoDB")]
-```
-
-### Responsibilities
-
-1. **Normalize filter structures** across APIs
-2. **Encapsulate filtering intent** in strongly typed criteria classes
-3. **Support UI filter metadata responses** (counts, labels, selectable options)
-4. **Bridge domain enums and database query filters**
-
----
-
-# Core Filter Patterns
-
-Across entities, this module follows consistent patterns:
-
-## 1. *FilterCriteria Classes*
-
-These represent the filtering rules submitted by the client.
-
-Examples:
-
-- `LogFilterCriteria`
-- `DeviceFilterCriteria`
-- `EventFilterCriteria`
-- `KnowledgeBaseFilterCriteria`
-- `ToolFilterCriteria`
-
-These classes typically include:
-
-- Date ranges (`startDate`, `endDate`)
-- Entity type filters
-- Status filters
-- Organization scoping
-- Tag-based filtering
-
-They are consumed by service/query layers to build Mongo queries.
-
----
-
-## 2. *Filters Classes (Faceted Responses)*
-
-These classes provide filter metadata for UI dropdowns and dashboards.
-
-Examples:
-
-- `LogFilters`
-- `DeviceFilters`
-- `EventFilters`
-- `ToolFilters`
-
-They usually contain:
-
-- Available filter values
-- Display labels
-- Optional counts per filter value
-
-These enable dynamic filtering experiences (faceted search).
-
----
-
-## 3. *List & Response DTOs*
-
-Used to standardize list responses and entity projections:
-
-- `OrganizationList`
-- `ToolList`
-- `OrganizationResponse`
-
-These are shared between:
-
-- GraphQL DTO layer
-- REST external API layer
-
----
-
-# Entity-Specific Filter Structures
-
-## Log Filtering
-
-### LogFilterCriteria
-
-Encapsulates audit log filtering rules:
-
-- `startDate` / `endDate`
-- `eventTypes`
-- `toolTypes`
-- `severities`
-- `organizationIds`
-- `deviceId`
-
-```mermaid
-flowchart TD
-    LogFilterCriteria["LogFilterCriteria"] --> DateRange["Date Range"]
-    LogFilterCriteria --> EventTypes["Event Types"]
-    LogFilterCriteria --> ToolTypes["Tool Types"]
-    LogFilterCriteria --> Severities["Severities"]
-    LogFilterCriteria --> Organizations["Organization IDs"]
-    LogFilterCriteria --> Device["Device ID"]
-```
-
-### LogFilters
-
-Provides available values for:
-
-- Tool types
-- Event types
-- Severities
-- Organizations (via `OrganizationFilterOption`)
-
-### OrganizationFilterOption
-
-Represents a selectable organization option:
-
-- `id`
-- `name`
-
-Used primarily for UI dropdown population.
-
----
-
-## Device Filtering
-
-### DeviceFilterCriteria
-
-Supports multi-dimensional filtering:
-
-- `statuses` (DeviceStatus enum)
-- `deviceTypes` (DeviceType enum)
-- `osTypes`
-- `organizationIds`
-- `tagKeys`
-- `tagValues`
-
-```mermaid
-flowchart TD
-    DeviceFilterCriteria["DeviceFilterCriteria"] --> Statuses["Device Statuses"]
-    DeviceFilterCriteria --> Types["Device Types"]
-    DeviceFilterCriteria --> OsTypes["OS Types"]
-    DeviceFilterCriteria --> Orgs["Organization IDs"]
-    DeviceFilterCriteria --> Tags["Tag Keys / Values"]
-```
-
-### DeviceFilters
-
-Faceted filter response containing:
-
-- `statuses`
-- `deviceTypes`
-- `osTypes`
-- `organizationIds`
-- `tagKeys`
-- `filteredCount`
-
-Each option is represented by:
-
-### DeviceFilterOption
-
-- `value`
-- `label`
-- `count`
-
-### TagFilterOption
-
-- `key`
-- `value`
-- `count`
-
-This enables advanced tag-based device filtering.
-
----
-
-## Event Filtering
-
-### EventFilterCriteria
-
-Filters system/user events by:
-
-- `userIds`
-- `eventTypes`
-- `startDate`
-- `endDate`
-
-### EventFilters
-
-Returns available:
-
-- User IDs
-- Event types
-
-This supports activity feed filtering and auditing dashboards.
-
----
-
-## Knowledge Base Filtering
-
-### KnowledgeBaseFilterCriteria
-
-Used to query hierarchical content:
-
-- `parentId`
-- `type` (KnowledgeBaseItemType enum)
-- `tagIds`
-- `statuses` (KnowledgeBaseArticleStatus enum)
-
-This enables:
-
-- Folder-level filtering
-- Tag-based content queries
-- Status-based moderation filtering
-
----
-
-## Organization Filtering & Responses
-
-### OrganizationFilterOptions
-
-Internal filtering structure for:
-
-- `category`
-- `minEmployees`
-- `maxEmployees`
-- `hasActiveContract`
-- `status`
-
-### OrganizationList
-
-Wrapper for returning multiple Organization documents.
-
-### OrganizationResponse
-
-Shared response DTO across GraphQL and REST.
-
-Contains:
-
-- Identity fields (`id`, `organizationId`)
-- Business metadata
-- Revenue and contract information
-- Lifecycle timestamps
-- Status fields
-
-```mermaid
-flowchart LR
-    Organization["Organization (Mongo Document)"] --> OrganizationResponse["OrganizationResponse DTO"]
-    OrganizationResponse --> RestAPI["REST API"]
-    OrganizationResponse --> GraphQL["GraphQL API"]
-```
-
----
-
-## Tool Filtering
-
-### ToolFilterCriteria
-
-Filters integrated tools by:
-
-- `enabled`
-- `type`
-- `category`
-- `platformCategory`
-
-### ToolFilters
-
-Provides available:
-
-- Tool types
-- Categories
-- Platform categories
-
-### ToolList
-
-Wrapper for returning a list of `IntegratedTool` domain documents.
-
----
-
-# Interaction with Other Layers
-
-## With GraphQL Layer
-
-GraphQL input DTOs are transformed into FilterCriteria objects, which are then passed to service/query layers.
-
-```mermaid
-flowchart LR
-    GraphQLInput["GraphQL Filter Input"] --> Criteria["FilterCriteria DTO"]
-    Criteria --> Service["Query Service"]
-    Service --> MongoFilter["Mongo Query Filter"]
-```
-
-## With Mongo Query Filters
-
-Each FilterCriteria maps conceptually to a corresponding Mongo query filter class in the query layer.
-
-Example conceptual mapping:
-
-```mermaid
-flowchart TD
-    DeviceFilterCriteria --> DeviceQueryFilter["DeviceQueryFilter"]
-    EventFilterCriteria --> EventQueryFilter["EventQueryFilter"]
-    ToolFilterCriteria --> ToolQueryFilter["ToolQueryFilter"]
-```
-
-The DTO layer remains persistence-agnostic, while query modules handle database-specific logic.
-
----
-
-# Design Principles
-
-The Api Domain Filters Dtos module follows these architectural principles:
-
-1. **Separation of Concerns**  
-   DTOs describe intent; services implement logic.
-
-2. **Strong Typing**  
-   Uses enums and structured lists instead of raw maps.
-
-3. **UI-Driven Design**  
-   Includes filter option and count DTOs for faceted filtering.
-
-4. **Cross-API Reusability**  
-   Shared response DTOs prevent duplication across REST and GraphQL.
-
-5. **Extensibility**  
-   New filter dimensions can be added without impacting existing consumers.
-
----
-
-# Summary
-
-The **Api Domain Filters Dtos** module provides the structured filtering and response contracts that power:
-
-- Device management
-- Audit logs
-- Event tracking
-- Knowledge base content
-- Organization management
-- Tool integrations
-
-It forms the backbone of query expressiveness across the OpenFrame API stack, enabling consistent filtering semantics across services, APIs, and persistence layers.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-lib-core-services/api-lib-core-services.md b/docs/reference/architecture/api-lib-core-services/api-lib-core-services.md
deleted file mode 100644
index f06349115..000000000
--- a/docs/reference/architecture/api-lib-core-services/api-lib-core-services.md
+++ /dev/null
@@ -1,298 +0,0 @@
-# Api Lib Core Services
-
-## Overview
-
-The **Api Lib Core Services** module provides the core business service layer for the OpenFrame API library. It sits between the API-facing layers (REST controllers and GraphQL data fetchers) and the persistence layer (Mongo repositories and domain documents).
-
-This module encapsulates reusable domain logic related to:
-
-- Installed agents per machine
-- Tool connections and integrations
-- Ticket querying and search
-- Knowledge base publication lifecycle
-- Device status post-processing
-
-It is designed to be:
-
-- ✅ Framework-aligned (Spring Boot, Spring Data)
-- ✅ Multi-tenant ready (delegating to repository-level filters)
-- ✅ GraphQL DataLoader-friendly (batch-oriented methods)
-- ✅ Extensible via conditional beans and processors
-
----
-
-## Architectural Position
-
-The Api Lib Core Services module acts as a **pure service layer** within the larger OpenFrame architecture.
-
-```mermaid
-flowchart TD
-    Controllers["REST Controllers"] --> Services["Api Lib Core Services"]
-    DataFetchers["GraphQL Data Fetchers"] --> Services
-    Services --> Repositories["Mongo Repositories"]
-    Repositories --> MongoDB[("MongoDB")]
-
-    Services --> Processors["Domain Processors"]
-```
-
-### Upstream Consumers
-
-- REST Controllers (API Service Core)
-- GraphQL Data Fetchers
-- DataLoaders (batch loading layer)
-
-### Downstream Dependencies
-
-- Mongo domain documents (Machine, Ticket, ToolConnection, InstalledAgent)
-- Spring Data repositories
-- Mongo event lifecycle hooks
-
-The module intentionally contains **no HTTP or GraphQL annotations**, ensuring reusability across different API surfaces.
-
----
-
-## Core Components
-
-### 1. InstalledAgentService
-
-**Purpose:**
-Provides read access and batch-loading logic for installed agents across machines.
-
-**Key Capabilities:**
-
-- Fetch installed agents for a single machine
-- Fetch installed agents for multiple machines (DataLoader optimized)
-- Lookup by ID
-- Lookup by machine and agent type
-
-```mermaid
-flowchart LR
-    DataLoader["InstalledAgentDataLoader"] --> Service["InstalledAgentService"]
-    Service --> Repo["InstalledAgentRepository"]
-    Repo --> Mongo[("MongoDB")]
-```
-
-#### Batch-Oriented Design
-
-The method:
-
-```java
-getInstalledAgentsForMachines(List<String> machineIds)
-```
-
-- Fetches all agents using `findByMachineIdIn`
-- Groups them in-memory by machine ID
-- Returns a list aligned with the original input order
-
-This structure avoids the **N+1 query problem** in GraphQL environments.
-
----
-
-### 2. ToolConnectionService
-
-**Purpose:**
-Manages retrieval of tool connection data associated with machines.
-
-**Responsibilities:**
-
-- Fetch tool connections by ID
-- Fetch tool connections per machine
-- Batch-fetch tool connections for multiple machines
-
-```mermaid
-flowchart LR
-    ToolDataLoader["ToolConnectionDataLoader"] --> ToolService["ToolConnectionService"]
-    ToolService --> ToolRepo["ToolConnectionRepository"]
-    ToolRepo --> Mongo[("MongoDB")]
-```
-
-Similar to InstalledAgentService, this service is optimized for batch resolution in GraphQL environments.
-
----
-
-### 3. TicketQueryService
-
-**Purpose:**
-Encapsulates ticket search and retrieval logic with filtering and cursor-based pagination support.
-
-**Key Methods:**
-
-- `findById(String ticketId)`
-- `searchTickets(TicketQueryFilter filter, String search, int limit)`
-
-```mermaid
-flowchart TD
-    API["API Layer"] --> TicketService["TicketQueryService"]
-    TicketService --> QueryFilter["TicketQueryFilter"]
-    TicketService --> Repo["TicketRepository"]
-    Repo --> Mongo[("MongoDB")]
-```
-
-#### Query Construction Flow
-
-1. Build a `Query` object using:
-   - Structured filter (`TicketQueryFilter`)
-   - Free-text search
-2. Delegate to repository method:
-   - `findTicketsWithCursor(...)`
-3. Apply default sorting:
-   - Field: `createdAt`
-   - Direction: `DESC`
-
-This service centralizes ticket query semantics and ensures consistent sorting behavior.
-
----
-
-### 4. KnowledgeBasePublishLifecycleListener
-
-**Purpose:**
-Automatically stamps `publishedAt` when a knowledge base article transitions into the `PUBLISHED` state for the first time.
-
-This is implemented as a:
-
-- Spring `@Component`
-- Extends `AbstractMongoEventListener<KnowledgeBaseItem>`
-- Hooks into `onBeforeConvert`
-
-```mermaid
-flowchart TD
-    Save["Save KnowledgeBaseItem"] --> MongoEvent["BeforeConvertEvent"]
-    MongoEvent --> Listener["KnowledgeBasePublishLifecycleListener"]
-    Listener --> Stamp["Set publishedAt if null"]
-    Stamp --> Persist[("MongoDB")]
-```
-
-### Semantic Guarantees
-
-- ✅ `publishedAt` is set only once
-- ✅ Unpublish/republish cycles do not overwrite the original timestamp
-- ✅ Aligns with Schema.org `datePublished` and Atom `published`
-
-This ensures historical integrity and stable audit semantics.
-
----
-
-### 5. DefaultDeviceStatusProcessor
-
-**Purpose:**
-Provides a default implementation for device status post-processing logic.
-
-It implements `DeviceStatusProcessor` and is registered with:
-
-- `@Component`
-- `@ConditionalOnMissingBean`
-
-```mermaid
-flowchart LR
-    DeviceStatusUpdate["Machine Status Updated"] --> Processor["DeviceStatusProcessor"]
-    Processor --> DefaultImpl["DefaultDeviceStatusProcessor"]
-```
-
-### Extensibility Model
-
-Because it is conditionally registered, applications can:
-
-- Provide a custom `DeviceStatusProcessor`
-- Override default behavior without modifying the core module
-
-The default implementation only logs status changes, making it safe and side-effect free.
-
----
-
-## Design Patterns Used
-
-### 1. Service Layer Pattern
-Encapsulates domain logic and shields API layers from persistence details.
-
-### 2. DataLoader-Friendly Batch APIs
-Both InstalledAgentService and ToolConnectionService provide:
-
-- `List<List<Entity>>` aligned responses
-- Deterministic ordering
-- Single query per batch
-
-### 3. Repository Delegation
-All query logic ultimately delegates to repositories responsible for:
-
-- Query construction
-- Pagination mechanics
-- Sorting logic
-
-### 4. Event-Driven Lifecycle Hooks
-KnowledgeBasePublishLifecycleListener demonstrates:
-
-- Mongo lifecycle event integration
-- Declarative business rules
-- Immutable publication timestamp semantics
-
-### 5. Conditional Bean Extension
-DefaultDeviceStatusProcessor enables pluggable domain behavior using Spring Boot auto-configuration conventions.
-
----
-
-## Data Flow Example: GraphQL Machine Query
-
-When querying machines with nested installed agents and tool connections:
-
-```mermaid
-flowchart TD
-    Client["GraphQL Client"] --> DataFetcher["MachineDataFetcher"]
-    DataFetcher --> AgentLoader["InstalledAgentDataLoader"]
-    DataFetcher --> ToolLoader["ToolConnectionDataLoader"]
-
-    AgentLoader --> AgentService["InstalledAgentService"]
-    ToolLoader --> ToolService["ToolConnectionService"]
-
-    AgentService --> AgentRepo["InstalledAgentRepository"]
-    ToolService --> ToolRepo["ToolConnectionRepository"]
-
-    AgentRepo --> Mongo[("MongoDB")]
-    ToolRepo --> Mongo
-```
-
-This ensures:
-
-- ✅ No N+1 queries
-- ✅ Deterministic batch resolution
-- ✅ Clean separation between data resolution and domain logic
-
----
-
-## Transaction and Consistency Model
-
-- Read-only services are annotated with `@Transactional(readOnly = true)`
-- Lifecycle listeners operate before persistence conversion
-- Repository layer enforces query-level consistency
-
-The module intentionally avoids complex transaction orchestration and instead relies on:
-
-- Repository atomic operations
-- Mongo consistency guarantees
-
----
-
-## Extension Guidelines
-
-When extending Api Lib Core Services:
-
-1. ✅ Keep services stateless
-2. ✅ Delegate persistence to repositories
-3. ✅ Provide batch-friendly APIs when used by GraphQL
-4. ✅ Use conditional beans for override points
-5. ✅ Keep lifecycle logic idempotent
-
----
-
-## Summary
-
-The **Api Lib Core Services** module is the domain-centric service backbone of the OpenFrame API stack.
-
-It provides:
-
-- Clean separation of concerns
-- Batch-optimized data access patterns
-- Event-driven lifecycle management
-- Extensible processing hooks
-- Consistent query semantics
-
-By centralizing domain service logic in this module, the broader OpenFrame platform maintains a modular, scalable, and extensible API architecture.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-organization-mapping/api-organization-mapping.md b/docs/reference/architecture/api-organization-mapping/api-organization-mapping.md
deleted file mode 100644
index 86fb3e3d8..000000000
--- a/docs/reference/architecture/api-organization-mapping/api-organization-mapping.md
+++ /dev/null
@@ -1,322 +0,0 @@
-# Api Organization Mapping
-
-The **Api Organization Mapping** module is responsible for translating between external API data transfer objects (DTOs) and the internal persistence model for organizations. It acts as the boundary layer between:
-
-- REST and GraphQL API contracts
-- Domain entities stored in MongoDB
-- Service-layer business logic
-
-At its core is the `OrganizationMapper`, a Spring component that ensures consistent, safe, and predictable conversion between request objects, domain entities, and response DTOs.
-
----
-
-## 1. Purpose and Responsibilities
-
-The Api Organization Mapping module provides:
-
-- ✅ Conversion from API request DTOs to `Organization` entities
-- ✅ Partial update (patch-style) entity updates
-- ✅ Conversion from `Organization` entities to response DTOs
-- ✅ Nested object mapping (contact information, addresses, contacts)
-- ✅ Controlled immutability for system-critical fields (e.g., `organizationId`)
-
-It centralizes mapping logic to avoid duplication across:
-
-- REST controllers
-- GraphQL data fetchers
-- Service layer components
-
----
-
-## 2. Core Component
-
-### OrganizationMapper
-
-Location:
-
-```text
-com.openframe.api.mapper.OrganizationMapper
-```
-
-Type:
-
-- Spring `@Component`
-- Stateless mapper
-- Shared across REST and GraphQL APIs
-
-### Primary Methods
-
-| Method | Purpose |
-|--------|----------|
-| `toEntity(CreateOrganizationRequest)` | Create new `Organization` entity |
-| `updateEntity(Organization, UpdateOrganizationRequest)` | Partial update of entity |
-| `toResponse(Organization)` | Convert entity to API response |
-
----
-
-## 3. High-Level Architecture
-
-The mapper sits between API contracts and the domain model.
-
-```mermaid
-flowchart LR
-    subgraph ApiLayer["API Layer"]
-        RestController["OrganizationController"]
-        GraphQLFetcher["OrganizationDataFetcher"]
-    end
-
-    Mapper["OrganizationMapper"]
-
-    subgraph DomainLayer["Domain & Persistence"]
-        OrgEntity["Organization Entity"]
-        MongoRepo["Mongo Repository"]
-    end
-
-    RestController -->|"Create/Update Request"| Mapper
-    GraphQLFetcher -->|"Mutation Input"| Mapper
-
-    Mapper -->|"Entity"| OrgEntity
-    OrgEntity --> MongoRepo
-
-    MongoRepo --> OrgEntity
-    OrgEntity -->|"Response DTO"| Mapper
-    Mapper -->|"OrganizationResponse"| RestController
-    Mapper -->|"GraphQL DTO"| GraphQLFetcher
-```
-
-### Related Modules
-
-- API contracts and DTO definitions: [Api Domain Filters Dtos](api-domain-filters-dtos.md)
-- REST layer: [Api Service Core Rest Controllers](api-service-core-rest-controllers.md)
-- GraphQL layer: [Api Service Core Graphql Datafetchers](api-service-core-graphql-datafetchers.md)
-- Persistence model: [Data Mongo Domain Model](data-mongo-domain-model.md)
-
----
-
-## 4. Create Flow Mapping
-
-### 4.1 Entity Creation
-
-`toEntity(CreateOrganizationRequest request)`:
-
-- Generates a new `organizationId` using UUID
-- Copies request fields into the entity
-- Sets `isDefault` to `false`
-- Converts nested contact structures
-
-```mermaid
-flowchart TD
-    Request["CreateOrganizationRequest"] --> MapperCreate["toEntity()"]
-    MapperCreate --> GenId["Generate UUID"]
-    MapperCreate --> MapFields["Map Scalar Fields"]
-    MapperCreate --> MapContact["Map Contact Information"]
-    MapContact --> MapAddress["Map Address"]
-    MapContact --> MapContacts["Map Contact Persons"]
-    GenId --> OrgEntity["Organization Entity"]
-    MapFields --> OrgEntity
-    MapContact --> OrgEntity
-```
-
-### 4.2 UUID Generation
-
-The organization ID is:
-
-- Generated internally
-- Immutable after creation
-- Independent from MongoDB primary key (`id`)
-
-This ensures:
-
-- External-safe identifier exposure
-- Decoupling from database implementation
-- Stable public references
-
----
-
-## 5. Partial Update Strategy
-
-### 5.1 Patch-Style Updates
-
-`updateEntity(existing, request)`:
-
-- Only updates fields that are **non-null** in the request
-- Leaves unspecified fields unchanged
-- Does **not** allow updating `organizationId`
-
-```mermaid
-flowchart TD
-    UpdateRequest["UpdateOrganizationRequest"] --> CheckField["Field != null?"]
-    CheckField -->|"Yes"| ApplyUpdate["Set Field on Entity"]
-    CheckField -->|"No"| Skip["Keep Existing Value"]
-    ApplyUpdate --> OrgEntity["Updated Organization"]
-    Skip --> OrgEntity
-```
-
-### 5.2 Immutability Rules
-
-The following field is intentionally immutable:
-
-- `organizationId`
-
-Reason:
-
-- Prevents identity mutation
-- Protects referential integrity across services
-- Ensures stable tenant-level references
-
----
-
-## 6. Response Mapping
-
-`toResponse(Organization organization)` converts the domain entity into `OrganizationResponse`.
-
-### 6.1 Field Transformations
-
-- `status` → converted to string via `status.name()`
-- `createdAt` and `updatedAt` preserved
-- Nested contact information mapped to DTO equivalents
-
-```mermaid
-flowchart LR
-    OrgEntity["Organization Entity"] --> MapperResponse["toResponse()"]
-    MapperResponse --> MapScalars["Map Scalar Fields"]
-    MapperResponse --> MapStatus["Enum to String"]
-    MapperResponse --> MapNested["Map Contact Information DTO"]
-    MapScalars --> Response["OrganizationResponse"]
-    MapStatus --> Response
-    MapNested --> Response
-```
-
----
-
-## 7. Nested Contact Mapping
-
-The mapper handles complex nested structures:
-
-### 7.1 ContactInformation
-
-Structure includes:
-
-- Contacts (list of `ContactPerson`)
-- Physical address
-- Mailing address
-- `mailingAddressSameAsPhysical` flag
-
-### 7.2 Mailing Address Copy Logic
-
-If `mailingAddressSameAsPhysical == true`:
-
-- Mailing address is a **copy** of physical address
-- Avoids shared object references
-- Prevents unintended mutation side effects
-
-```mermaid
-flowchart TD
-    Dto["ContactInformationDto"] --> CheckFlag{{"Same As Physical?"}}
-    CheckFlag -->|"Yes"| CopyAddr["Copy Physical Address"]
-    CheckFlag -->|"No"| MapMail["Map Mailing Address"]
-    CopyAddr --> Entity["ContactInformation Entity"]
-    MapMail --> Entity
-```
-
-This defensive copying ensures data integrity when updates occur later.
-
----
-
-## 8. Interaction with Other Modules
-
-### 8.1 REST Controllers
-
-Controllers such as `OrganizationController`:
-
-- Accept request DTOs
-- Call services
-- Use `OrganizationMapper` to convert entities to responses
-
-See: [Api Service Core Rest Controllers](api-service-core-rest-controllers.md)
-
-### 8.2 GraphQL Data Fetchers
-
-`OrganizationDataFetcher` uses the same mapper to:
-
-- Convert mutation inputs
-- Map domain entities to GraphQL DTOs
-
-See: [Api Service Core Graphql Datafetchers](api-service-core-graphql-datafetchers.md)
-
-### 8.3 Domain Model
-
-Entity involved:
-
-- `com.openframe.data.document.organization.Organization`
-
-Defined in: [Data Mongo Domain Model](data-mongo-domain-model.md)
-
----
-
-## 9. End-to-End Organization Lifecycle (Simplified)
-
-```mermaid
-flowchart LR
-    Client["Client App"] --> RestAPI["REST or GraphQL API"]
-    RestAPI --> MapperCreate["OrganizationMapper"]
-    MapperCreate --> Service["Organization Service"]
-    Service --> Repo["Mongo Repository"]
-    Repo --> DB["MongoDB"]
-    DB --> Repo
-    Repo --> Service
-    Service --> MapperResponse["OrganizationMapper"]
-    MapperResponse --> RestAPI
-    RestAPI --> Client
-```
-
-The Api Organization Mapping module ensures that:
-
-- API contracts remain stable
-- Domain entities remain clean and persistence-focused
-- Mapping rules are centralized and consistent
-
----
-
-## 10. Design Principles
-
-### 10.1 Single Responsibility
-
-The mapper:
-
-- Does not contain business logic
-- Does not access repositories
-- Does not perform validation
-
-It strictly transforms data structures.
-
-### 10.2 Stateless & Thread-Safe
-
-- No shared mutable state
-- No injected dependencies
-- Safe for concurrent use
-
-### 10.3 Explicit Mapping Over Reflection
-
-All fields are mapped explicitly rather than using reflection-based mapping frameworks.
-
-Benefits:
-
-- Better compile-time safety
-- Clear documentation of field transformations
-- Predictable behavior
-- Easier debugging
-
----
-
-## 11. Key Takeaways
-
-The **Api Organization Mapping** module:
-
-- Acts as the transformation boundary between API and domain
-- Protects immutable identity fields
-- Implements safe partial update semantics
-- Handles complex nested structures with defensive copying
-- Is shared across REST and GraphQL layers
-
-By centralizing organization mapping logic, the platform ensures consistent behavior across all API surfaces while keeping the domain model isolated from transport-layer concerns.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-service-core-config-and-security/api-service-core-config-and-security.md b/docs/reference/architecture/api-service-core-config-and-security/api-service-core-config-and-security.md
deleted file mode 100644
index 0c8137f06..000000000
--- a/docs/reference/architecture/api-service-core-config-and-security/api-service-core-config-and-security.md
+++ /dev/null
@@ -1,350 +0,0 @@
-# Api Service Core Config And Security
-
-The **Api Service Core Config And Security** module defines the foundational runtime configuration for the OpenFrame API service. It centralizes:
-
-- Core Spring Boot bean configuration
-- Authentication and argument resolution
-- OAuth client bootstrapping
-- GraphQL custom scalar definitions
-- Outbound HTTP client configuration
-- JWT resource server integration with issuer-based caching
-
-This module is intentionally lightweight in business logic. Its responsibility is to configure and secure the API runtime so that higher-level modules such as REST controllers, GraphQL data fetchers, and service layers can operate consistently and securely.
-
----
-
-## 1. Architectural Role in the System
-
-The Api Service Core Config And Security module sits at the heart of the API runtime. It wires together:
-
-- Spring Boot auto-configuration
-- Spring Security (OAuth2 Resource Server)
-- GraphQL DGS custom scalars
-- OAuth client initialization
-- Shared infrastructure beans (PasswordEncoder, RestTemplate)
-
-### High-Level Placement
-
-```mermaid
-flowchart LR
-    Gateway["Gateway Service"] -->|"JWT Forwarded"| ApiService["API Service Runtime"]
-    ApiService -->|"Uses"| ConfigModule["Api Service Core Config And Security"]
-    ApiService --> Controllers["REST Controllers"]
-    ApiService --> GraphQL["GraphQL Data Fetchers"]
-    ApiService --> Services["Domain Services"]
-    Services --> DataLayer["Mongo / Kafka / Redis"]
-```
-
-### Security Responsibility Split
-
-The API service does **not** perform full authentication enforcement. Instead:
-
-- The **Gateway Service**:
-  - Validates JWT tokens
-  - Handles public vs protected routes
-  - Injects `Authorization` headers from cookies
-- The **Api Service Core Config And Security** module:
-  - Enables OAuth2 Resource Server support
-  - Resolves JWT issuers dynamically
-  - Exposes `@AuthenticationPrincipal` support
-
-This layered approach keeps the API service stateless and focused on business logic.
-
----
-
-## 2. Core Configuration Components
-
-### 2.1 ApiApplicationConfig
-
-**Component:**
-- `ApiApplicationConfig`
-
-Provides shared infrastructure beans.
-
-#### PasswordEncoder Bean
-
-```java
-@Bean
-public PasswordEncoder passwordEncoder() {
-    return new BCryptPasswordEncoder();
-}
-```
-
-- Uses BCrypt for secure password hashing.
-- Shared across services handling credentials.
-- Ensures consistent hashing strategy across modules.
-
----
-
-### 2.2 AuthenticationConfig
-
-**Component:**
-- `AuthenticationConfig`
-
-Registers a custom Spring MVC argument resolver:
-
-- `AuthPrincipalArgumentResolver`
-
-This enables controller methods like:
-
-```java
-public ResponseEntity<?> getProfile(@AuthenticationPrincipal AuthPrincipal principal)
-```
-
-#### Flow
-
-```mermaid
-flowchart TD
-    Request["HTTP Request"] --> Security["OAuth2 Resource Server"]
-    Security --> Controller["Controller Method"]
-    Controller --> Resolver["AuthPrincipalArgumentResolver"]
-    Resolver --> Principal["AuthPrincipal Injected"]
-```
-
-This ensures:
-- Clean controller signatures
-- Strong typing for authenticated users
-- No manual extraction of JWT claims
-
----
-
-### 2.3 SecurityConfig
-
-**Component:**
-- `SecurityConfig`
-
-This is the central Spring Security configuration.
-
-#### Key Characteristics
-
-- CSRF disabled (stateless API)
-- All routes `permitAll()` at API layer
-- OAuth2 Resource Server enabled
-- Multi-issuer JWT support
-- Caffeine-based JWT provider cache
-
-### JWT Issuer-Based Authentication
-
-The module uses:
-
-- `JwtIssuerAuthenticationManagerResolver`
-- A `LoadingCache<String, JwtAuthenticationProvider>`
-
-This allows dynamic resolution of authentication managers based on the JWT issuer.
-
-```mermaid
-flowchart TD
-    Incoming["Incoming Request with JWT"] --> ExtractIssuer["Extract iss Claim"]
-    ExtractIssuer --> CacheCheck["Check JwtAuthenticationProvider Cache"]
-    CacheCheck -->|"Miss"| CreateDecoder["Create JwtDecoder from Issuer"]
-    CreateDecoder --> StoreCache["Store in Caffeine Cache"]
-    CacheCheck -->|"Hit"| UseProvider["Reuse Cached Provider"]
-    StoreCache --> Authenticate["Authenticate JWT"]
-    UseProvider --> Authenticate
-    Authenticate --> Principal["SecurityContext Updated"]
-```
-
-#### Cache Configuration
-
-The cache is controlled by properties:
-
-- `openframe.security.jwt.cache.expire-after`
-- `openframe.security.jwt.cache.refresh-after`
-- `openframe.security.jwt.cache.maximum-size`
-
-This ensures:
-- Efficient decoder reuse
-- Controlled memory usage
-- Automatic refresh of issuer metadata
-
----
-
-### 2.4 DataInitializer
-
-**Component:**
-- `DataInitializer`
-
-Implements a `CommandLineRunner` to initialize OAuth clients at application startup.
-
-#### Responsibilities
-
-- Reads properties:
-  - `oauth.client.default.id`
-  - `oauth.client.default.secret`
-- Checks if client exists
-- Updates secret if changed
-- Creates client if missing
-
-```mermaid
-flowchart TD
-    Startup["Application Startup"] --> LoadProps["Read OAuth Properties"]
-    LoadProps --> QueryRepo["Find Client by ID"]
-    QueryRepo -->|"Exists"| CompareSecret["Compare Secrets"]
-    CompareSecret -->|"Different"| UpdateSecret["Update and Save"]
-    CompareSecret -->|"Same"| Skip["No Action"]
-    QueryRepo -->|"Missing"| CreateClient["Create OAuthClient"]
-```
-
-#### Design Rationale
-
-- Ensures environment-driven configuration.
-- Avoids manual database seeding.
-- Keeps OAuth client configuration aligned with deployment configuration.
-
----
-
-### 2.5 GraphQL Custom Scalars
-
-The module defines three custom DGS scalars.
-
-#### DateScalarConfig
-
-- Scalar name: `Date`
-- Backed by `LocalDate`
-- Format: `yyyy-MM-dd`
-
-Validation ensures:
-- Strict format compliance
-- Clear error messages for invalid input
-
----
-
-#### InstantScalarConfig
-
-- Scalar name: `Instant`
-- Backed by `Instant`
-- ISO-8601 format (e.g. `2026-01-01T10:15:30Z`)
-
-Provides:
-- Consistent time serialization
-- Accurate timezone handling
-
----
-
-#### LongScalarConfig
-
-- Scalar name: `Long`
-- Supports 64-bit integers
-- Required for values exceeding GraphQL `Int` limits
-
-Handles:
-- Numeric literals
-- String-based numeric input
-- Safe coercion with validation
-
-```mermaid
-flowchart LR
-    GraphQLInput["GraphQL Query Input"] --> Scalar["Custom Scalar Coercing"]
-    Scalar --> Validation["Format Validation"]
-    Validation --> Parsed["Java Type (LocalDate / Instant / Long)"]
-    Parsed --> DataFetcher["Data Fetcher Execution"]
-```
-
-These scalars standardize type handling across all GraphQL data fetchers.
-
----
-
-### 2.6 RestTemplateConfig
-
-**Component:**
-- `RestTemplateConfig`
-
-Defines a singleton `RestTemplate` bean.
-
-```java
-@Bean
-public RestTemplate restTemplate() {
-    return new RestTemplate();
-}
-```
-
-Used for:
-- Outbound HTTP calls
-- Internal service-to-service communication
-- OAuth metadata resolution (indirectly via Spring Security)
-
-Centralizing the bean allows:
-- Future interceptors
-- Timeout configuration
-- Observability instrumentation
-
----
-
-## 3. End-to-End Security Flow
-
-Below is a simplified request lifecycle involving this module.
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Gateway
-    participant Api as "API Service"
-    participant Security as "SecurityConfig"
-    participant Controller
-
-    Client->>Gateway: Request with Cookie or Token
-    Gateway->>Gateway: Validate JWT
-    Gateway->>Api: Forward request with Authorization header
-    Api->>Security: Resolve issuer and authenticate
-    Security->>Api: Populate SecurityContext
-    Api->>Controller: Invoke handler
-    Controller->>Controller: Inject AuthPrincipal
-```
-
-### Key Observations
-
-- Authentication enforcement happens upstream.
-- API service trusts Gateway filtering.
-- Multi-tenant issuer resolution is supported dynamically.
-- Controllers remain clean and declarative.
-
----
-
-## 4. Design Principles
-
-The Api Service Core Config And Security module follows these principles:
-
-### 4.1 Separation of Concerns
-
-- Gateway: authentication + edge security
-- API: resource server support + identity propagation
-- Services: business logic
-
-### 4.2 Statelessness
-
-- No server-side sessions
-- JWT-based identity
-- Cache only for issuer metadata
-
-### 4.3 Extensibility
-
-- Centralized bean definitions
-- Pluggable scalar definitions
-- Configurable cache properties
-
-### 4.4 Environment-Driven Configuration
-
-- OAuth clients initialized via properties
-- Cache behavior driven by configuration
-- No hard-coded credentials
-
----
-
-## 5. Summary
-
-The **Api Service Core Config And Security** module is the foundation of the OpenFrame API runtime. It:
-
-- Enables secure JWT-based authentication
-- Integrates with multi-issuer OAuth providers
-- Standardizes GraphQL scalar behavior
-- Provides core infrastructure beans
-- Bootstraps OAuth client configuration
-
-While minimal in business logic, this module is critical for ensuring:
-
-- Secure request handling
-- Consistent authentication context propagation
-- Reliable GraphQL type handling
-- Clean separation between infrastructure and domain layers
-
-It acts as the runtime spine of the API service, ensuring that all higher-level modules operate in a secure, predictable, and standardized environment.
diff --git a/docs/reference/architecture/api-service-core-dataloaders/api-service-core-dataloaders.md b/docs/reference/architecture/api-service-core-dataloaders/api-service-core-dataloaders.md
deleted file mode 100644
index 7caecbce5..000000000
--- a/docs/reference/architecture/api-service-core-dataloaders/api-service-core-dataloaders.md
+++ /dev/null
@@ -1,343 +0,0 @@
-# Api Service Core Dataloaders
-
-## Overview
-
-The **Api Service Core Dataloaders** module provides batched, asynchronous data loading capabilities for the GraphQL layer of the OpenFrame API Service Core.
-
-Built on top of **Netflix DGS** and the standard `org.dataloader` pattern, this module eliminates N+1 query problems by batching and caching entity lookups during a single GraphQL request lifecycle.
-
-It acts as a bridge between:
-
-- GraphQL Data Fetchers (resolvers)
-- Domain Services
-- Mongo repositories
-- Underlying domain documents
-
-This module is a critical performance layer in the API stack.
-
----
-
-## Architectural Context
-
-The Api Service Core Dataloaders module sits between the GraphQL Data Fetchers and the service/repository layer.
-
-```mermaid
-flowchart TD
-    Client["GraphQL Client"] --> GQL["GraphQL Data Fetchers"]
-    GQL --> DL["Api Service Core Dataloaders"]
-    DL --> Service["Domain Services"]
-    DL --> Repo["Mongo Repositories"]
-    Service --> Mongo[("MongoDB")]
-    Repo --> Mongo
-```
-
-### Responsibilities
-
-- Batch load related entities by IDs
-- Preserve request ordering
-- Avoid redundant queries within a request
-- Delegate to appropriate service or repository
-- Return results asynchronously via `CompletableFuture`
-
----
-
-## Why DataLoaders Are Required
-
-Without DataLoaders, a query such as:
-
-```graphql
-query {
-  devices {
-    id
-    organization {
-      name
-    }
-  }
-}
-```
-
-would result in:
-
-- 1 query to load devices
-- N queries to load organizations
-
-With DataLoaders:
-
-- 1 query to load devices
-- 1 batched query to load all required organizations
-
-This dramatically improves performance and scalability.
-
----
-
-## DataLoader Execution Model
-
-All loaders implement:
-
-```java
-BatchLoader<K, V>
-```
-
-and are annotated with:
-
-```java
-@DgsDataLoader(name = "...")
-```
-
-Each loader:
-
-1. Receives a list of keys
-2. Removes nulls
-3. Batch queries the database or service
-4. Maps results by ID
-5. Returns results in the same order as input
-6. Executes asynchronously via `CompletableFuture.supplyAsync`
-
-```mermaid
-sequenceDiagram
-    participant Resolver as "GraphQL Resolver"
-    participant Loader as "DataLoader"
-    participant Service as "Service/Repository"
-
-    Resolver->>Loader: load([id1, id2, id3])
-    Loader->>Service: Batch fetch entities
-    Service-->>Loader: List of entities
-    Loader-->>Resolver: Ordered results
-```
-
----
-
-# Core DataLoaders
-
-Below are the loaders provided by this module.
-
----
-
-## InstalledAgentDataLoader
-
-**Purpose:** Batch loads InstalledAgent objects grouped by machine ID.
-
-**Delegates to:** `InstalledAgentService`
-
-```mermaid
-flowchart LR
-    Resolver --> InstalledAgentDataLoader
-    InstalledAgentDataLoader --> InstalledAgentService
-    InstalledAgentService --> Mongo
-```
-
-- Key: `machineId`
-- Value: `List<InstalledAgent>`
-- Use case: Resolving installed agents for multiple machines in one request
-
----
-
-## KnowledgeBaseAttachmentDataLoader
-
-**Purpose:** Batch loads attachments for knowledge base items.
-
-**Delegates to:** `KnowledgeBaseAttachmentService`
-
-- Key: `knowledgeBaseItemId`
-- Value: `List<KnowledgeBaseItemAttachment>`
-- Includes debug logging for batch size visibility
-
----
-
-## KnowledgeBaseItemDataLoader
-
-**Purpose:** Batch loads KnowledgeBaseItem by ID.
-
-**Used for:** Polymorphic AssignableTarget resolution for KNOWLEDGE_ARTICLE target type.
-
-**Delegates to:** `KnowledgeBaseItemRepository`
-
-### Special Behavior
-
-- Filters null IDs
-- De-duplicates IDs
-- Returns `null` for missing items
-- Preserves request order
-
-```mermaid
-flowchart TD
-    Resolver --> KnowledgeBaseItemDataLoader
-    KnowledgeBaseItemDataLoader --> KnowledgeBaseItemRepository
-    KnowledgeBaseItemRepository --> Mongo
-```
-
----
-
-## KnowledgeBaseTagDataLoader
-
-**Purpose:** Batch loads Tags associated with Knowledge Base items.
-
-**Delegates to:** `KnowledgeBaseTagService`
-
-- Key: `knowledgeBaseItemId`
-- Value: `List<Tag>`
-
----
-
-## MachineDataLoader
-
-**Purpose:** Batch loads Machine entities by machine ID.
-
-**Used for:** AssignableTarget resolution for DEVICE target type.
-
-**Delegates to:** `MachineRepository`
-
-### Behavior
-
-- Filters null IDs
-- Performs `findByMachineIdIn`
-- Maps results by machineId
-- Preserves input ordering
-
----
-
-## OrganizationDataLoader
-
-**Purpose:** Batch loads Organization entities by organization ID.
-
-**Key Optimization:** Prevents N+1 queries when resolving organization for many machines.
-
-**Delegates to:** `OrganizationRepository`
-
-### Additional Logic
-
-- Filters out soft-deleted organizations
-- Only returns organizations with `ACTIVE` status
-
-```mermaid
-flowchart TD
-    Resolver --> OrganizationDataLoader
-    OrganizationDataLoader --> OrganizationRepository
-    OrganizationRepository --> Mongo
-```
-
----
-
-## TagDataLoader
-
-**Purpose:** Batch loads Tags for machines.
-
-**Delegates to:** `TagService`
-
-- Key: `machineId`
-- Value: `List<Tag>`
-
----
-
-## TicketDataLoader
-
-**Purpose:** Batch loads Ticket entities by ID.
-
-**Used for:** AssignableTarget resolution for TICKET target type.
-
-**Delegates to:** `TicketRepository`
-
-### Behavior
-
-- Filters null IDs
-- Uses `findAllById`
-- Preserves input order
-
----
-
-## ToolConnectionDataLoader
-
-**Purpose:** Batch loads ToolConnection entities for machines.
-
-**Delegates to:** `ToolConnectionService`
-
-- Key: `machineId`
-- Value: `List<ToolConnection>`
-
----
-
-## UserDataLoader
-
-**Purpose:** Batch loads UserResponse DTOs by user ID.
-
-**Delegates to:** `UserService`
-
-### Important Detail
-
-The loader goes through `UserService` rather than directly querying a repository. This ensures:
-
-- Registered UserProcessor implementations enrich responses
-- SaaS-specific user augmentation is applied
-- Profile image and additional computed fields are included
-
-**Used by:** KnowledgeBaseItem author resolver
-
----
-
-# Cross-Module Relationships
-
-The Api Service Core Dataloaders module works closely with:
-
-- [Api Service Core GraphQL Datafetchers](../api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md)
-- Domain services in the API layer
-- Mongo repositories from the data layer
-
-```mermaid
-flowchart TD
-    subgraph graphql_layer["GraphQL Layer"]
-        DF["Data Fetchers"]
-        DL["DataLoaders"]
-    end
-
-    subgraph service_layer["Service Layer"]
-        SVC["Domain Services"]
-    end
-
-    subgraph data_layer["Data Layer"]
-        REPO["Mongo Repositories"]
-        DB[("MongoDB")]
-    end
-
-    DF --> DL
-    DL --> SVC
-    DL --> REPO
-    SVC --> DB
-    REPO --> DB
-```
-
----
-
-# Performance Characteristics
-
-✅ Eliminates N+1 query issues  
-✅ Reduces database round trips  
-✅ Maintains deterministic ordering  
-✅ Enables async non-blocking resolution  
-✅ Scales efficiently with large GraphQL queries  
-
----
-
-# Design Patterns Used
-
-- **Batch Loading Pattern**
-- **Repository Pattern**
-- **Service Layer Abstraction**
-- **Asynchronous Execution via CompletableFuture**
-- **GraphQL DataLoader Pattern**
-
----
-
-# Summary
-
-The **Api Service Core Dataloaders** module is a performance-critical layer in the OpenFrame GraphQL architecture.
-
-It ensures that complex nested queries:
-
-- Execute efficiently
-- Avoid excessive database calls
-- Preserve domain encapsulation
-- Maintain clean separation between GraphQL and persistence layers
-
-Without this module, GraphQL queries across devices, organizations, tickets, knowledge base items, and users would not scale effectively.
-
-This module enables high-performance, production-grade GraphQL execution within the Api Service Core.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md b/docs/reference/architecture/api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md
deleted file mode 100644
index 6757c6391..000000000
--- a/docs/reference/architecture/api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md
+++ /dev/null
@@ -1,439 +0,0 @@
-# Api Service Core Graphql Datafetchers
-
-## Overview
-
-The **Api Service Core Graphql Datafetchers** module is the GraphQL execution layer of the OpenFrame API Service Core. It exposes domain capabilities (devices, events, organizations, knowledge base, notifications, assignments, tools, logs, and tags) through Netflix DGS-based GraphQL data fetchers.
-
-This module acts as the orchestration layer between:
-
-- GraphQL schema and Relay node model
-- Application services (DeviceService, EventService, KnowledgeBaseService, etc.)
-- DataLoaders for batching and N+1 mitigation
-- Security context (JWT-based principals)
-- Cursor-based pagination and filter criteria
-
-It does **not** implement business logic directly. Instead, it:
-
-- Decodes Relay global IDs
-- Maps GraphQL inputs into domain filter criteria
-- Delegates to services
-- Wraps results into Relay-compatible connection types
-- Resolves nested fields using DataLoaders
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart LR
-    Client["GraphQL Client"] --> Schema["GraphQL Schema"]
-    Schema --> DataFetchers["DGS DataFetchers"]
-    DataFetchers --> Mappers["GraphQL Mappers"]
-    DataFetchers --> Services["Application Services"]
-    Services --> Repositories["Mongo / Pinot / Cassandra Repositories"]
-
-    DataFetchers --> DataLoaders["DataLoaders (Batching)"]
-    DataLoaders --> Services
-
-    DataFetchers --> Security["SecurityContext + JWT"]
-```
-
-### Responsibilities of This Module
-
-- Implements `@DgsQuery`, `@DgsMutation`, and `@DgsData`
-- Converts GraphQL inputs into service-layer DTOs
-- Encodes and decodes Relay global IDs
-- Builds cursor-based pagination criteria
-- Returns Relay-compatible `Connection` and `Edge` types
-- Resolves polymorphic types (NotificationContext, Node interface)
-
----
-
-## Core Design Patterns
-
-### 1. Relay Global ID Pattern
-
-All node-based entities use Relay global IDs.
-
-```text
-Global ID = Base64(TypeName:RawId)
-Example: "Machine:abc123" -> encoded
-```
-
-Pattern used everywhere:
-
-- Decode input ID using `Relay.fromGlobalId()`
-- Fetch entity using raw ID
-- Encode output ID using `Relay.toGlobalId()`
-
-This enables:
-
-- Uniform `node(id: ID!)` resolution
-- Type-safe global references
-- Cross-entity linking
-
----
-
-### 2. Cursor-Based Pagination
-
-Pagination is built using:
-
-- `ConnectionArgs`
-- `CursorPaginationCriteria`
-- `CountedGenericQueryResult` or `GenericQueryResult`
-- `GenericEdge<T>`
-- `CountedGenericConnection<T>` or `GenericConnection<T>`
-
-```mermaid
-flowchart TD
-    Query["GraphQL Query"] --> Args["ConnectionArgs"]
-    Args --> Pagination["CursorPaginationCriteria"]
-    Pagination --> ServiceQuery["Service.query(...)"]
-    ServiceQuery --> Result["QueryResult"]
-    Result --> Mapper["GraphQL Mapper"]
-    Mapper --> Connection["Relay Connection"]
-```
-
-This ensures consistent pagination behavior across:
-
-- Devices
-- Events
-- Organizations
-- Logs
-- Knowledge base
-- Assignments
-- Notifications
-
----
-
-### 3. DataLoader-Based N+1 Prevention
-
-Nested fields are resolved asynchronously using DGS DataLoaders.
-
-Example relationships:
-
-- Machine → Tags
-- Machine → InstalledAgents
-- Machine → ToolConnections
-- Machine → Organization
-- KnowledgeBaseItem → Tags
-- KnowledgeBaseItem → Attachments
-- KnowledgeBaseItem → Author
-- Assignment → Target entity
-
-```mermaid
-flowchart LR
-    Query["devices query"] --> DeviceFetcher
-    DeviceFetcher --> DeviceService
-    DeviceFetcher --> MachineNode["Machine"]
-    MachineNode -->|"tags"| TagLoader
-    MachineNode -->|"installedAgents"| AgentLoader
-    TagLoader --> TagService
-    AgentLoader --> InstalledAgentService
-```
-
-All DataLoader calls return `CompletableFuture<T>` to ensure batched execution.
-
----
-
-## Data Fetcher Components
-
-### AssignmentDataFetcher
-
-Handles:
-
-- Assignment queries
-- Assign/unassign mutations
-- Assignment counts by target type
-- Target resolution using DataLoaders
-
-Key patterns:
-
-- Uses `AssignmentService`
-- Maps results via `GraphQLAssignmentMapper`
-- Resolves polymorphic assignment targets (Organization, Machine, Ticket, KnowledgeBaseItem)
-
----
-
-### DeviceDataFetcher
-
-Responsible for:
-
-- Device listing with filtering and pagination
-- Device filters
-- Device lookup by ID
-- Resolving nested relations (tags, agents, organization)
-
-Key dependencies:
-
-- `DeviceService`
-- `DeviceFilterService`
-- `TagService`
-- `GraphQLDeviceMapper`
-
-Implements full Relay connection pattern.
-
----
-
-### EventDataFetcher
-
-Provides:
-
-- Event listing
-- Event lookup
-- Event creation and update
-- Event filter retrieval
-
-Features:
-
-- Converts `EventFilterInput` into `EventFilterCriteria`
-- Uses `GraphQLEventMapper`
-- Returns `GenericConnection`
-
----
-
-### KnowledgeBaseDataFetcher
-
-One of the most feature-rich fetchers.
-
-Supports:
-
-- Folder and article queries
-- Publishing/unpublishing
-- Archiving/unarchiving
-- Folder tree retrieval
-- Tag management
-- Attachment uploads (temp + permanent)
-- Attachment linking
-
-Security-aware behavior:
-
-- Extracts user ID from JWT
-- Uses `AuthPrincipal`
-- Applies mutation wrapper pattern for success/error payloads
-
-```mermaid
-flowchart TD
-    Mutation["createArticle"] --> GetUser["Extract JWT User"]
-    GetUser --> Mapper
-    Mapper --> Service["KnowledgeBaseService"]
-    Service --> DB["Mongo Repository"]
-```
-
-Also resolves nested fields:
-
-- Tags
-- Attachments
-- Author
-- Parent ID
-
----
-
-### LogDataFetcher
-
-Conditionally enabled via:
-
-```text
-spring.data.cassandra.enabled=true
-```
-
-Responsibilities:
-
-- Log listing
-- Log filters
-- Log detail retrieval
-
-Uses:
-
-- `LogService`
-- `GraphQLLogMapper`
-
-Provides cursor-based pagination for log events.
-
----
-
-### NodeDataFetcher
-
-Implements Relay `node(id: ID!)` and `nodes(ids: [ID!])`.
-
-```mermaid
-flowchart TD
-    NodeQuery["node(id)"] --> Decode["Relay.fromGlobalId"]
-    Decode --> TypeSwitch["NodeType enum"]
-    TypeSwitch --> DeviceService
-    TypeSwitch --> OrganizationService
-    TypeSwitch --> EventService
-    TypeSwitch --> ToolService
-    TypeSwitch --> TagService
-```
-
-Supports types such as:
-
-- Machine
-- Organization
-- Event
-- IntegratedTool
-- Tag
-- ToolConnection
-- InstalledAgent
-- Tenant
-
-This enables universal entity lookup via a single GraphQL entry point.
-
----
-
-### NotificationDataFetcher
-
-Handles authenticated notification access.
-
-Security rules:
-
-- Requires `ADMIN` or `AGENT` authority
-- Determines recipient type (USER or MACHINE)
-- Extracts identity from JWT
-
-Operations:
-
-- List notifications
-- Mark as read
-- Mark all as read
-- Delete
-- Delete all read
-- Unread counts by category
-
-```mermaid
-flowchart TD
-    Query["notifications"] --> CurrentRecipient
-    CurrentRecipient --> Principal["AuthPrincipal"]
-    Principal --> NotificationService
-    NotificationService --> ReadStateService
-```
-
-Also includes strict ID decoding validation for notification IDs.
-
----
-
-### OrganizationDataFetcher
-
-Provides:
-
-- Organization listing (paginated)
-- Organization lookup
-- Filter options
-
-Uses:
-
-- `OrganizationService`
-- `OrganizationQueryService`
-- `GraphQLOrganizationMapper`
-
----
-
-### TagDataFetcher
-
-Supports:
-
-- Tag listing
-- Key/value suggestions
-- Tag creation
-- Tag updates
-- Tag deletion
-
-Converts Relay ID for mutation operations.
-
----
-
-### ToolsDataFetcher
-
-Provides:
-
-- Integrated tool listing
-- Tool filters
-
-Uses:
-
-- `ToolService`
-- `GraphQLToolMapper`
-
----
-
-### NotificationContextGraphQlTypeResolver
-
-Resolves polymorphic GraphQL types for `NotificationContext`.
-
-```mermaid
-flowchart TD
-    NotificationContext --> Resolver
-    Resolver -->|"type discriminator"| TypeMap
-    TypeMap --> GraphQLType
-```
-
-- Maps discriminator string → GraphQL type name
-- Falls back to `GenericContext` if not found
-- Enables GraphQL union/interface resolution
-
----
-
-## Security Integration
-
-The module integrates tightly with JWT-based security.
-
-Key aspects:
-
-- Uses `SecurityContextHolder`
-- Extracts `AuthPrincipal` from JWT
-- Determines `ActorType` (USER or AGENT)
-- Applies `@PreAuthorize` annotations
-
-Security is enforced at:
-
-- Query level (Notification access)
-- Mutation level
-- User-aware operations (Knowledge base, notifications)
-
----
-
-## Interaction with Other Layers
-
-```mermaid
-flowchart LR
-    GraphQL["GraphQL DataFetchers"] --> Services
-    Services --> Domain["Domain Models"]
-    Services --> Repositories
-    Services --> Messaging["NATS / Kafka"]
-    Services --> Cache["Redis"]
-```
-
-The Api Service Core Graphql Datafetchers module:
-
-- Does not access repositories directly
-- Does not contain domain logic
-- Acts as translation + orchestration layer
-
----
-
-## Key Architectural Benefits
-
-1. Clear separation between API and business logic
-2. Uniform Relay support across all entities
-3. Consistent pagination model
-4. Batch loading via DataLoaders
-5. Centralized Node resolution
-6. Strong JWT-based identity handling
-7. Polymorphic type resolution for flexible schemas
-
----
-
-## Summary
-
-The **Api Service Core Graphql Datafetchers** module is the central GraphQL execution layer of the OpenFrame platform.
-
-It:
-
-- Bridges GraphQL schema to service layer
-- Implements Relay global ID and connection patterns
-- Uses DataLoaders to prevent N+1 issues
-- Enforces JWT-based security
-- Provides consistent pagination and filtering
-
-By keeping business logic in services and focusing purely on API orchestration, this module ensures a clean, scalable, and maintainable GraphQL architecture for the OpenFrame ecosystem.
diff --git a/docs/reference/architecture/api-service-core-graphql-dtos/api-service-core-graphql-dtos.md b/docs/reference/architecture/api-service-core-graphql-dtos/api-service-core-graphql-dtos.md
deleted file mode 100644
index f118770b9..000000000
--- a/docs/reference/architecture/api-service-core-graphql-dtos/api-service-core-graphql-dtos.md
+++ /dev/null
@@ -1,434 +0,0 @@
-# Api Service Core Graphql Dtos
-
-The **Api Service Core Graphql Dtos** module defines the GraphQL-facing Data Transfer Objects (DTOs) used by the Api Service Core. These DTOs represent:
-
-- GraphQL connection and edge wrappers
-- Query filter input types
-- Mutation input types
-- Structured response models
-- Lightweight aggregation models
-
-This module acts as the **schema contract layer** between GraphQL data fetchers and the underlying domain, service, and persistence layers.
-
-It does not contain business logic. Instead, it formalizes how data flows into and out of the GraphQL API.
-
----
-
-## Architectural Role
-
-Within the overall Api Service Core architecture, this module sits between:
-
-- GraphQL Data Fetchers (execution layer)
-- Domain DTOs and persistence documents (data layer)
-- Services and processors (business layer)
-
-### High-Level Placement
-
-```mermaid
-flowchart TD
-    Client["GraphQL Client"] --> Schema["GraphQL Schema"]
-    Schema --> DataFetcher["GraphQL Data Fetchers"]
-    DataFetcher --> Dtos["Api Service Core Graphql Dtos"]
-    Dtos --> Services["Core Services"]
-    Services --> Repositories["Mongo Repositories"]
-    Repositories --> Database[("Database")]
-```
-
-The **Api Service Core Graphql Dtos** module defines the types used in:
-
-- Query arguments
-- Mutation inputs
-- Relay-style connections
-- Filter inputs
-- Structured API responses
-
----
-
-# Module Structure
-
-The module can be logically grouped into the following categories:
-
-1. Relay Connection Models
-2. Filter Input DTOs
-3. Mutation Input DTOs
-4. Domain Response DTOs
-5. Aggregation and Assignment DTOs
-
----
-
-# 1. Relay Connection Models
-
-GraphQL in Api Service Core follows the Relay-style pagination model. This module provides reusable generic wrappers.
-
-## GenericEdge
-
-```java
-public class GenericEdge<T> {
-    private T node;
-    private String cursor;
-}
-```
-
-Responsibilities:
-
-- Wraps a single node
-- Provides a cursor for pagination
-- Forms part of a GraphQL Connection response
-
-## CountedGenericConnection
-
-```java
-public class CountedGenericConnection<T extends GenericEdge>
-        extends GenericConnection<T> {
-    private int filteredCount;
-}
-```
-
-Responsibilities:
-
-- Extends the base connection model
-- Adds `filteredCount` for total result size
-- Supports filtered pagination use cases
-
-### Relay Pagination Flow
-
-```mermaid
-flowchart LR
-    Query["GraphQL Query"] --> Args["Connection Arguments"]
-    Args --> Fetcher["Data Fetcher"]
-    Fetcher --> Service["Service Layer"]
-    Service --> Edge["GenericEdge<T>"]
-    Edge --> Connection["CountedGenericConnection"]
-    Connection --> Client["GraphQL Client"]
-```
-
-This ensures:
-
-- Stable cursor-based pagination
-- Support for filtering
-- Predictable total counts for UI rendering
-
----
-
-# 2. Filter Input DTOs
-
-These classes represent GraphQL input types for querying and filtering domain entities.
-
-They are optimized for client-side flexibility and map to domain-level filter criteria.
-
-## LogFilterInput
-
-Supports filtering by:
-
-- Date range (`startDate`, `endDate`)
-- Event types
-- Tool types
-- Severities
-- Organization IDs
-- Device ID
-
-Used in log and audit queries.
-
----
-
-## DeviceFilterInput
-
-Supports filtering by:
-
-- Device status
-- Device type
-- Operating system types
-- Organization IDs
-- Tag keys and values
-
-Enables complex device search and inventory queries.
-
----
-
-## EventFilterInput
-
-Supports filtering by:
-
-- User IDs
-- Event types
-- Date range
-
-Used by event-related GraphQL queries.
-
----
-
-## KnowledgeBaseFilterInput
-
-Supports filtering by:
-
-- Parent folder
-- Item type
-- Tag IDs
-
-Used to navigate and filter knowledge base structures.
-
----
-
-## OrganizationFilterInput
-
-Supports filtering by:
-
-- Category
-- Employee range
-- Contract status
-- Organization status
-
----
-
-## ToolFilterInput
-
-Supports filtering by:
-
-- Enabled state
-- Tool type
-- Category
-- Platform category
-
----
-
-## NotificationFilterInput
-
-Supports filtering by:
-
-- Read/unread status
-
----
-
-### Filter Mapping Flow
-
-```mermaid
-flowchart TD
-    GraphQLInput["GraphQL Filter Input"] --> DataFetcher["Data Fetcher"]
-    DataFetcher --> Criteria["Domain Filter Criteria"]
-    Criteria --> Repository["Custom Repository"]
-    Repository --> Results["Domain Documents"]
-    Results --> Connection["Connection DTO"]
-```
-
-Filter inputs are intentionally:
-
-- Client-oriented
-- Flexible
-- Decoupled from persistence implementation
-
----
-
-# 3. Mutation Input DTOs
-
-These DTOs define structured input contracts for GraphQL mutations.
-
-They frequently include validation annotations such as:
-
-- `@NotBlank`
-- `@NotNull`
-- `@Size`
-
-## Event Mutations
-
-### CreateEventInput
-
-Fields:
-
-- `userId` (required)
-- `type` (required)
-- `data`
-
-Used for creating audit or system events.
-
----
-
-## Knowledge Base Mutations
-
-### CreateArticleInput
-
-Supports:
-
-- Article metadata
-- Status
-- Tag assignments
-- Cross-entity assignments
-
-### UpdateArticleInput
-
-Supports partial updates of:
-
-- Name
-- Parent
-- Content
-- Summary
-
-### DeleteFolderInput
-
-Supports:
-
-- Folder deletion
-- Child handling strategy
-- Optional move target
-
-### CreateKnowledgeBaseAttachmentInput
-
-Defines:
-
-- Target article
-- File metadata
-
-### CreateKnowledgeBaseTempAttachmentInput
-
-Defines temporary upload metadata before final linking.
-
-### LinkKnowledgeBaseTempAttachmentsInput
-
-Supports bulk linking of temporary attachments to an article.
-
----
-
-## User Mutations
-
-### UpdateUserRequest
-
-Supports updating:
-
-- First name
-- Last name
-
-Includes size validation constraints.
-
----
-
-### Mutation Execution Flow
-
-```mermaid
-flowchart TD
-    Client["GraphQL Mutation"] --> Input["Mutation Input DTO"]
-    Input --> Validation["Bean Validation"]
-    Validation --> Processor["Service or Processor"]
-    Processor --> Repository["Mongo Repository"]
-    Repository --> Response["Response DTO"]
-```
-
-The DTO layer guarantees:
-
-- Schema consistency
-- Validation enforcement
-- Clear mutation contracts
-
----
-
-# 4. Domain Response DTOs
-
-These classes represent structured GraphQL output types.
-
-## UserResponse
-
-Encapsulates:
-
-- Identity fields
-- Roles
-- Status
-- Profile image
-- Audit timestamps
-
-Designed to:
-
-- Hide internal domain representation
-- Expose only client-relevant fields
-- Maintain immutability via builder pattern
-
----
-
-# 5. Aggregation and Assignment DTOs
-
-## AssignedItemCount
-
-```java
-public class AssignedItemCount {
-    private AssignmentTargetType targetType;
-    private int count;
-}
-```
-
-Purpose:
-
-- Represents assignment counts grouped by target type
-- Used in dashboards and summary queries
-- Bridges domain enum types into GraphQL responses
-
----
-
-# Design Principles
-
-The **Api Service Core Graphql Dtos** module follows several architectural principles:
-
-## 1. Clear Separation of Concerns
-
-- DTOs contain no business logic
-- Services implement logic
-- Repositories handle persistence
-
-## 2. GraphQL-Optimized Models
-
-- Designed for GraphQL schema shape
-- Optimized for client flexibility
-- Uses input-specific classes instead of reusing domain objects
-
-## 3. Validation at the Boundary
-
-Validation annotations ensure:
-
-- Early error detection
-- Strong input guarantees
-- Reduced service-layer complexity
-
-## 4. Relay Compliance
-
-- Edge-based pagination
-- Connection wrappers
-- Cursor-based navigation
-
----
-
-# End-to-End Data Flow Example
-
-```mermaid
-flowchart TD
-    UI["Frontend UI"] --> Query["GraphQL Query or Mutation"]
-    Query --> DTOIn["Input DTO"]
-    DTOIn --> Fetcher["Data Fetcher"]
-    Fetcher --> Service["Core Service"]
-    Service --> Repo["Mongo Repository"]
-    Repo --> Domain["Domain Document"]
-    Domain --> DTOOut["Edge or Response DTO"]
-    DTOOut --> Connection["CountedGenericConnection"]
-    Connection --> UI
-```
-
-This module ensures the GraphQL API remains:
-
-- Strongly typed
-- Stable
-- Decoupled from internal persistence structures
-- Easy to evolve without breaking clients
-
----
-
-# Summary
-
-The **Api Service Core Graphql Dtos** module defines the GraphQL contract layer of the Api Service Core. It provides:
-
-- Relay-compatible connection models
-- Rich filter input types
-- Structured mutation inputs
-- Clean response DTOs
-- Aggregation models for summary data
-
-By isolating API-facing structures in a dedicated module, the system maintains:
-
-- Strong separation between API and domain
-- High schema clarity
-- Safer refactoring of internal models
-- Predictable GraphQL behavior
diff --git a/docs/reference/architecture/api-service-core-relay-type-resolution/api-service-core-relay-type-resolution.md b/docs/reference/architecture/api-service-core-relay-type-resolution/api-service-core-relay-type-resolution.md
deleted file mode 100644
index 5e9693efc..000000000
--- a/docs/reference/architecture/api-service-core-relay-type-resolution/api-service-core-relay-type-resolution.md
+++ /dev/null
@@ -1,276 +0,0 @@
-# Api Service Core Relay Type Resolution
-
-## Overview
-
-The **Api Service Core Relay Type Resolution** module is responsible for resolving polymorphic GraphQL types in the Api Service Core layer. It bridges:
-
-- Mongo domain model objects (e.g., `Machine`, `Organization`, `Ticket`)
-- GraphQL interfaces and unions (e.g., `Node`, `AssignableTarget`)
-- The Netflix DGS runtime type resolution mechanism
-
-In a Relay-compliant GraphQL architecture, interfaces such as `Node` and domain-specific unions such as `AssignableTarget` require runtime type resolution. This module provides that resolution logic via DGS `@DgsTypeResolver` components.
-
----
-
-## Why This Module Exists
-
-GraphQL interfaces and unions require a mechanism to determine the concrete GraphQL type for a returned object at runtime.
-
-For example:
-
-- A `Node` query may return a `Machine`, `User`, `Ticket`, or `Organization`.
-- An `AssignableTarget` may represent an `Organization`, `Machine`, `Ticket`, or `KnowledgeBaseItem`.
-
-The GraphQL engine must map Java domain objects to their corresponding GraphQL schema type names.
-
-The **Api Service Core Relay Type Resolution** module provides that mapping in a centralized and explicit way.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    Client["GraphQL Client"] --> Query["GraphQL Query"]
-    Query --> DGS["DGS Runtime"]
-    DGS --> Resolver["Type Resolver"]
-    Resolver --> DomainObj["Domain Object"]
-    DomainObj --> GraphQLType["GraphQL Type Name"]
-
-    subgraph relay_layer["Relay Type Resolution Layer"]
-        Resolver
-    end
-
-    subgraph domain_layer["Mongo Domain Model"]
-        DomainObj
-    end
-```
-
-### Flow Summary
-
-1. A GraphQL query resolves a field returning an interface or union.
-2. DGS invokes the registered `@DgsTypeResolver`.
-3. The resolver inspects the Java object using `instanceof` checks.
-4. It returns the GraphQL type name as a `String`.
-5. The runtime binds the object to the correct schema type.
-
----
-
-## Core Components
-
-This module contains two DGS type resolvers:
-
-- `AssignableTargetTypeResolver`
-- `NodeTypeResolver`
-
-Both are annotated with `@DgsComponent` and use `@DgsTypeResolver`.
-
----
-
-## AssignableTargetTypeResolver
-
-**Component:**  
-`openframe-oss-lib.openframe-api-service-core.src.main.java.com.openframe.api.relay.AssignableTargetTypeResolver.AssignableTargetTypeResolver`
-
-### Responsibility
-
-Resolves the GraphQL union/interface `AssignableTarget` into a concrete schema type.
-
-### Supported Domain Types
-
-| Java Type | GraphQL Type Returned |
-|------------|-----------------------|
-| `Organization` | `Organization` |
-| `Machine` | `Machine` |
-| `Ticket` | `Ticket` |
-| `KnowledgeBaseItem` | `KnowledgeBaseItem` |
-
-If an unsupported object is passed, the resolver throws:
-
-```text
-IllegalArgumentException: Unknown AssignableTarget type
-```
-
-### Resolution Logic
-
-```mermaid
-flowchart TD
-    Input["AssignableTarget Object"] --> CheckOrg{"Organization?"}
-    CheckOrg -->|"Yes"| Org["Return Organization"]
-    CheckOrg -->|"No"| CheckMachine{"Machine?"}
-    CheckMachine -->|"Yes"| Machine["Return Machine"]
-    CheckMachine -->|"No"| CheckTicket{"Ticket?"}
-    CheckTicket -->|"Yes"| Ticket["Return Ticket"]
-    CheckTicket -->|"No"| CheckKB{"KnowledgeBaseItem?"}
-    CheckKB -->|"Yes"| KB["Return KnowledgeBaseItem"]
-    CheckKB -->|"No"| Error["Throw IllegalArgumentException"]
-```
-
-### Architectural Role
-
-This resolver enables:
-
-- Polymorphic assignment targets
-- Unified assignment models across multiple entity types
-- Strong alignment between domain model and GraphQL schema
-
----
-
-## NodeTypeResolver
-
-**Component:**  
-`openframe-oss-lib.openframe-api-service-core.src.main.java.com.openframe.api.relay.NodeTypeResolver.NodeTypeResolver`
-
-### Responsibility
-
-Resolves the Relay `Node` interface to a concrete GraphQL type.
-
-This is central to:
-
-- Global object identification
-- Relay-style pagination
-- Cross-entity querying
-
-### Supported Domain Types
-
-| Java Type | GraphQL Type Returned |
-|------------|-----------------------|
-| `Machine` | `Machine` |
-| `Organization` | `Organization` |
-| `Event` | `Event` |
-| `IntegratedTool` | `IntegratedTool` |
-| `Tenant` | `Tenant` |
-| `ItemAssignment` | `ItemAssignment` |
-| `Ticket` | `Ticket` |
-| `KnowledgeBaseItem` | `KnowledgeBaseItem` |
-| `User` | `User` |
-
-If an unsupported object is encountered, an exception is thrown:
-
-```text
-IllegalArgumentException: Unknown Node type
-```
-
-### Resolution Flow
-
-```mermaid
-flowchart TD
-    NodeInput["Node Object"] --> CheckMachine{"Machine?"}
-    CheckMachine -->|"Yes"| ReturnMachine["Return Machine"]
-    CheckMachine -->|"No"| CheckOrg{"Organization?"}
-    CheckOrg -->|"Yes"| ReturnOrg["Return Organization"]
-    CheckOrg -->|"No"| CheckEvent{"Event?"}
-    CheckEvent -->|"Yes"| ReturnEvent["Return Event"]
-    CheckEvent -->|"No"| Continue["Other instanceof checks"]
-    Continue --> ReturnType["Return Matching Type"]
-```
-
----
-
-## Integration with GraphQL Layer
-
-This module works closely with:
-
-- [Api Service Core GraphQL Datafetchers](../api-service-core-graphql-datafetchers/api-service-core-graphql-datafetchers.md)
-- [Api Service Core GraphQL Dtos](../api-service-core-graphql-dtos/api-service-core-graphql-dtos.md)
-
-### Interaction Diagram
-
-```mermaid
-flowchart LR
-    DataFetcher["DataFetcher"] --> Domain["Domain Object"]
-    Domain --> Resolver["Node or AssignableTarget Resolver"]
-    Resolver --> SchemaType["GraphQL Schema Type"]
-    SchemaType --> Response["GraphQL Response"]
-```
-
-1. A DataFetcher returns a domain entity.
-2. The entity implements or represents a `Node` or `AssignableTarget`.
-3. DGS invokes the appropriate resolver.
-4. The resolver returns the GraphQL type name.
-5. The object is serialized correctly into the GraphQL response.
-
----
-
-## Relationship to the Domain Model
-
-This module depends directly on the Mongo domain model defined in:
-
-- Device entities (`Machine`)
-- Organization entities (`Organization`, `Tenant`)
-- User entities (`User`)
-- Event entities (`Event`)
-- Ticket entities (`Ticket`)
-- Knowledge base entities (`KnowledgeBaseItem`)
-- Tool entities (`IntegratedTool`)
-- Assignment entities (`ItemAssignment`)
-
-These classes originate from the data layer and are not GraphQL-specific.
-
-The resolvers form a clean boundary between:
-
-```mermaid
-flowchart TB
-    DomainModel["Mongo Domain Model"] --> RelayResolver["Relay Type Resolver"]
-    RelayResolver --> GraphQLSchema["GraphQL Schema Types"]
-```
-
-This keeps domain objects independent from GraphQL schema annotations.
-
----
-
-## Design Characteristics
-
-### 1. Explicit Type Mapping
-
-- No reflection-based resolution
-- No schema name inference
-- Explicit `instanceof` checks
-
-This ensures:
-
-- Predictable behavior
-- Easy debugging
-- Compile-time safety for supported types
-
-### 2. Fail-Fast Strategy
-
-Unknown types result in immediate `IllegalArgumentException`.
-
-Benefits:
-
-- Prevents silent schema mismatches
-- Forces developers to update resolvers when introducing new Node types
-
-### 3. Relay Compliance
-
-By resolving the `Node` interface properly, the module enables:
-
-- Global ID-based queries
-- Cursor-based pagination
-- Cross-type collections
-
----
-
-## When to Update This Module
-
-You must update **Api Service Core Relay Type Resolution** when:
-
-- A new domain type implements the `Node` interface in the GraphQL schema
-- A new entity becomes assignable under `AssignableTarget`
-- A new Mongo document class is exposed through GraphQL
-
-Failure to update this module will result in runtime exceptions.
-
----
-
-## Summary
-
-The **Api Service Core Relay Type Resolution** module is a critical but focused infrastructure component that:
-
-- Implements GraphQL Relay runtime type resolution
-- Maps Mongo domain entities to GraphQL schema types
-- Enables polymorphic querying
-- Enforces strict type safety and fail-fast behavior
-
-Although small in size, it is foundational to the correctness of the GraphQL execution layer in Api Service Core.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-service-core-rest-controllers/api-service-core-rest-controllers.md b/docs/reference/architecture/api-service-core-rest-controllers/api-service-core-rest-controllers.md
deleted file mode 100644
index 19b8e7b66..000000000
--- a/docs/reference/architecture/api-service-core-rest-controllers/api-service-core-rest-controllers.md
+++ /dev/null
@@ -1,425 +0,0 @@
-# Api Service Core Rest Controllers
-
-The **Api Service Core Rest Controllers** module exposes the primary internal REST endpoints of the OpenFrame API Service Core. It acts as the HTTP boundary layer between clients (UI, agents, internal services) and the underlying application services, command/query services, and domain logic.
-
-This module is responsible for:
-
-- Exposing secure REST endpoints for tenant-scoped operations
-- Delegating business logic to dedicated service layers
-- Translating HTTP semantics into domain/service calls
-- Enforcing authentication context via `AuthPrincipal`
-- Returning DTO-based responses for consistency and API stability
-
-It complements the GraphQL data fetchers and external API controllers by providing internal and operational REST endpoints.
-
----
-
-## Architectural Role in the Platform
-
-Within the overall OpenFrame architecture, the Api Service Core Rest Controllers module sits at the edge of the API Service Core and depends on:
-
-- Application services (command/query services)
-- Domain services and processors
-- Security context (`AuthPrincipal`)
-- Mongo-backed persistence modules
-- Tenant-aware authorization infrastructure
-
-```mermaid
-flowchart TD
-    Client["Client / UI / Agent"] --> Gateway["Gateway Service"]
-    Gateway --> ApiCore["API Service Core"]
-
-    subgraph rest_layer["REST Controller Layer"]
-        Controllers["Api Service Core Rest Controllers"]
-    end
-
-    subgraph service_layer["Service Layer"]
-        CommandServices["Command Services"]
-        QueryServices["Query Services"]
-        DomainProcessors["Domain Processors"]
-    end
-
-    subgraph data_layer["Data Layer"]
-        Mongo["Mongo Repositories"]
-        Redis["Redis Cache"]
-        Kafka["Kafka / Events"]
-    end
-
-    ApiCore --> Controllers
-    Controllers --> CommandServices
-    Controllers --> QueryServices
-    Controllers --> DomainProcessors
-
-    CommandServices --> Mongo
-    QueryServices --> Mongo
-    DomainProcessors --> Kafka
-    DomainProcessors --> Redis
-```
-
-The controllers themselves contain minimal business logic and primarily orchestrate calls to services.
-
----
-
-## Controller Overview
-
-The module contains the following REST controllers:
-
-- AgentRegistrationSecretController
-- ApiKeyController
-- DeviceController
-- ForceAgentController
-- HealthController
-- InvitationController
-- MeController
-- OpenFrameClientConfigurationController
-- OrganizationController
-- ReleaseVersionController
-- SSOConfigController
-- UserController
-
-Each controller is scoped to a specific functional domain.
-
----
-
-# Endpoint Domains
-
-## 1. Agent Registration Secret
-
-**Base Path:** `/agent/registration-secret`
-
-Controller: `AgentRegistrationSecretController`
-
-Responsibilities:
-
-- Retrieve active registration secret
-- List all historical secrets
-- Generate new registration secret
-
-```mermaid
-sequenceDiagram
-    participant Admin
-    participant Controller as AgentRegistrationSecretController
-    participant Service as AgentRegistrationSecretService
-
-    Admin->>Controller: POST /agent/registration-secret/generate
-    Controller->>Service: generateNewSecret()
-    Service-->>Controller: AgentRegistrationSecretResponse
-    Controller-->>Admin: 201 Created
-```
-
-This endpoint is typically used during agent provisioning and secure enrollment flows.
-
----
-
-## 2. API Key Management
-
-**Base Path:** `/api-keys`
-
-Controller: `ApiKeyController`
-
-Key features:
-
-- List user API keys
-- Create new API key
-- Update metadata
-- Delete key
-- Regenerate secret
-
-Authentication is derived from `AuthPrincipal`, ensuring API keys are scoped to the authenticated user.
-
-```mermaid
-flowchart LR
-    User["Authenticated User"] --> Controller["ApiKeyController"]
-    Controller --> Service["ApiKeyService"]
-    Service --> Repo["BaseApiKeyRepository"]
-```
-
-Security Characteristics:
-
-- User-scoped access
-- Regeneration rotates secret while preserving key identity
-- Creation returns secret only once
-
----
-
-## 3. Device Status Updates
-
-**Base Path:** `/devices`
-
-Controller: `DeviceController`
-
-Primary responsibility:
-
-- Update device status via `PATCH /devices/{machineId}`
-
-This is typically invoked internally by agents or system processes to reflect device health or connectivity state.
-
-```mermaid
-flowchart TD
-    Agent["Agent"] --> Controller["DeviceController"]
-    Controller --> Service["DeviceService"]
-    Service --> DeviceDoc["Device Document"]
-```
-
----
-
-## 4. Force Agent Operations
-
-**Base Path:** `/force`
-
-Controller: `ForceAgentController`
-
-Supports operational commands such as:
-
-- Force tool installation
-- Force tool reinstallation
-- Force tool update
-- Force client update
-- Bulk operations ("all")
-
-These endpoints delegate to:
-
-- ForceToolInstallationService
-- ForceClientUpdateService
-- ForceToolAgentUpdateService
-
-```mermaid
-flowchart TD
-    Admin["Admin Action"] --> Controller["ForceAgentController"]
-    Controller --> InstallSvc["ForceToolInstallationService"]
-    Controller --> UpdateSvc["ForceToolAgentUpdateService"]
-    Controller --> ClientSvc["ForceClientUpdateService"]
-
-    InstallSvc --> Kafka["Kafka Event"]
-    UpdateSvc --> Kafka
-    ClientSvc --> Kafka
-```
-
-These operations are typically asynchronous and propagate through event pipelines.
-
----
-
-## 5. Health Check
-
-**Path:** `/health`
-
-Controller: `HealthController`
-
-- Lightweight liveness endpoint
-- Returns `200 OK` with body `OK`
-- Used by orchestrators and load balancers
-
----
-
-## 6. Invitations
-
-**Base Path:** `/invitations`
-
-Controller: `InvitationController`
-
-Supports:
-
-- Create invitation
-- Paginated listing
-- Revoke invitation
-- Resend invitation
-
-```mermaid
-sequenceDiagram
-    participant Admin
-    participant Controller as InvitationController
-    participant Service as InvitationService
-
-    Admin->>Controller: POST /invitations
-    Controller->>Service: createInvitation(request)
-    Service-->>Controller: InvitationResponse
-    Controller-->>Admin: 201 Created
-```
-
-Invitation flows integrate with SSO and tenant onboarding subsystems.
-
----
-
-## 7. Current User Context
-
-**Path:** `/me`
-
-Controller: `MeController`
-
-Purpose:
-
-- Exposes authenticated user context
-- Returns identity, roles, tenant ID
-- Returns 401 if no authenticated principal
-
-```mermaid
-flowchart TD
-    Request["GET /me"] --> AuthCheck["AuthPrincipal Present?"]
-    AuthCheck -->|"Yes"| Response["Return User Info"]
-    AuthCheck -->|"No"| Unauthorized["401 Unauthorized"]
-```
-
-This endpoint is commonly used by frontend applications to bootstrap user state.
-
----
-
-## 8. OpenFrame Client Configuration
-
-**Base Path:** `/openframe-client/configuration`
-
-Controller: `OpenFrameClientConfigurationController`
-
-Provides configuration metadata used by the OpenFrame client application.
-
-Delegates to:
-
-- OpenFrameClientConfigurationQueryService
-
----
-
-## 9. Organization Mutations
-
-**Base Path:** `/organizations`
-
-Controller: `OrganizationController`
-
-Handles:
-
-- Create organization
-- Update organization
-- Update status (ACTIVE / ARCHIVED)
-- Check if archivable
-
-```mermaid
-flowchart TD
-    Admin["Admin"] --> Controller["OrganizationController"]
-    Controller --> CommandSvc["OrganizationCommandService"]
-    Controller --> DomainSvc["OrganizationService"]
-    CommandSvc --> Repo["Organization Repository"]
-```
-
-Archiving rules:
-
-- Cannot archive if active devices exist
-- May return `409 Conflict`
-
-Read operations are intentionally separated into external-facing modules.
-
----
-
-## 10. Release Version
-
-**Base Path:** `/release-version`
-
-Controller: `ReleaseVersionController`
-
-Responsibilities:
-
-- Return current platform release metadata
-- Respond with 404 if not present
-
-Used by:
-
-- UI build metadata
-- Agent compatibility checks
-- Monitoring tools
-
----
-
-## 11. SSO Configuration
-
-**Base Path:** `/sso`
-
-Controller: `SSOConfigController`
-
-Supports:
-
-- List enabled providers
-- List available providers
-- Retrieve configuration
-- Create or update provider config
-- Toggle enablement
-- Delete configuration
-
-```mermaid
-flowchart TD
-    Admin["Admin"] --> Controller["SSOConfigController"]
-    Controller --> Service["SSOConfigService"]
-    Service --> Strategy["Provider Strategy"]
-    Strategy --> Provider["Google / Microsoft"]
-```
-
-This integrates with the Authorization Service Core and OAuth infrastructure.
-
----
-
-## 12. User Management
-
-**Base Path:** `/users`
-
-Controller: `UserController`
-
-Supports:
-
-- Paginated listing
-- Get by ID
-- Update user
-- Soft delete user
-
-```mermaid
-flowchart LR
-    Admin["Admin"] --> Controller["UserController"]
-    Controller --> Service["UserService"]
-    Service --> Repo["User Repository"]
-```
-
-Soft deletion ensures audit integrity and traceability.
-
----
-
-# Security Model
-
-All controllers (except `/health`) rely on Spring Security and JWT-based authentication.
-
-Authentication Flow:
-
-```mermaid
-flowchart TD
-    Request["Incoming HTTP Request"] --> Filter["JWT Filter"]
-    Filter --> Principal["AuthPrincipal"]
-    Principal --> Controller["REST Controller"]
-```
-
-Key characteristics:
-
-- Tenant-aware security context
-- Role-based authorization
-- Principal injection via `@AuthenticationPrincipal`
-- Clear separation between authentication and business logic
-
----
-
-# Design Principles
-
-The Api Service Core Rest Controllers module follows these principles:
-
-1. Thin controllers (no heavy business logic)
-2. Explicit HTTP semantics (correct status codes)
-3. DTO-based contract isolation
-4. Clear separation of command vs query concerns
-5. Tenant-aware multi-organization architecture
-
----
-
-# Summary
-
-The **Api Service Core Rest Controllers** module is the internal REST façade of the OpenFrame API Service Core. It orchestrates:
-
-- Identity-scoped user operations
-- Organization and tenant management
-- API key lifecycle
-- SSO configuration
-- Agent lifecycle control
-- Operational management endpoints
-
-It serves as a critical integration layer between authenticated clients and the underlying domain, persistence, and event-driven infrastructure, ensuring a clean, secure, and maintainable API boundary.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-service-core-user-sso-services-and-processors/api-service-core-user-sso-services-and-processors.md b/docs/reference/architecture/api-service-core-user-sso-services-and-processors/api-service-core-user-sso-services-and-processors.md
deleted file mode 100644
index 4943e9a41..000000000
--- a/docs/reference/architecture/api-service-core-user-sso-services-and-processors/api-service-core-user-sso-services-and-processors.md
+++ /dev/null
@@ -1,183 +0,0 @@
-# Api Service Core User Sso Services And Processors
-
-## Overview
-
-The **Api Service Core User Sso Services And Processors** module encapsulates user management, Single Sign-On (SSO) configuration, domain validation, and extensible post-processing hooks for user- and identity-related workflows inside the API Service Core.
-
-It acts as the orchestration layer between:
-
-- REST and GraphQL controllers in Api Service Core
-- Mongo persistence (User, Invitation, SSOConfig, AgentRegistrationSecret)
-- Encryption and domain validation services
-- External Authorization Service Core (SSO, tenant, OAuth flows)
-
-This module is designed for **extensibility**. All major lifecycle events (user updates, SSO config changes, invitation creation, agent secret generation) are delegated to pluggable processor interfaces with default no-op implementations.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    Controller["REST / GraphQL Controllers"] --> UserService["UserService"]
-    Controller --> SSOService["SSOConfigService"]
-
-    UserService --> UserRepo["UserRepository"]
-    UserService --> UserProcessor["UserProcessor"]
-
-    SSOService --> SSORepo["SSOConfigRepository"]
-    SSOService --> Encryption["EncryptionService"]
-    SSOService --> DomainValidation["DomainValidationService"]
-    SSOService --> SSOProcessor["SSOConfigProcessor"]
-
-    subgraph processors_layer["Post-Processing Layer"]
-        UserProcessor --> DefaultUserProcessor["DefaultUserProcessor"]
-        SSOProcessor --> DefaultSSOProcessor["DefaultSSOConfigProcessor"]
-        InvitationProcessor --> DefaultInvitationProcessor["DefaultInvitationProcessor"]
-        AgentSecretProcessor --> DefaultAgentProcessor["DefaultAgentRegistrationSecretProcessor"]
-    end
-```
-
-### Key Responsibilities
-
-- Manage users (query, update, soft delete)
-- Manage SSO provider configuration (CRUD + enable/disable)
-- Enforce domain validation rules for auto-provisioned SSO
-- Provide extension points for SaaS or enterprise overrides
-
----
-
-## Sub-Modules
-
-To keep responsibilities clean and extensible, this module can be logically divided into two sub-modules:
-
-### 1. Services
-
-Core business services handling user and SSO logic.
-
-👉 See: [Services](api-service-core-user-sso-services-and-processors/services/services.md)
-
-### 2. Processors
-
-Lifecycle hooks triggered after core operations (update, delete, toggle, create).
-
-👉 See: [Processors](api-service-core-user-sso-services-and-processors/processors/processors.md)
-
----
-
-## Domain Validation Strategy
-
-Domain validation plays a critical role in SSO auto-provisioning.
-
-```mermaid
-flowchart TD
-    Request["SSOConfigRequest"] --> Normalize["Normalize Domains"]
-    Normalize --> GenericCheck["validateGenericPublicDomain()"]
-    GenericCheck --> ExistsCheck["validateExists()"]
-    ExistsCheck --> Decision{"Auto Provision?"}
-    Decision -->|"No"| Save["Save Config"]
-    Decision -->|"Yes"| RequireDomain["Require At Least One Domain"]
-    RequireDomain --> MicrosoftCheck{"Microsoft?"}
-    MicrosoftCheck -->|"Yes"| RequireTenant["Require msTenantId"]
-    MicrosoftCheck -->|"No"| Save
-    RequireTenant --> Save
-```
-
-### DefaultDomainExistenceValidator
-
-The default implementation always returns `false`, meaning:
-
-- OSS deployments do not block SSO domain configuration
-- SaaS deployments can override with a stricter validator
-
-This is implemented using `@ConditionalOnMissingBean`, ensuring easy replacement.
-
----
-
-## User Lifecycle
-
-```mermaid
-flowchart TD
-    ListUsers["listUsers()"] --> FetchPage["UserRepository.findAll()"]
-    FetchPage --> MapResponse["UserMapper.toResponse()"]
-    MapResponse --> PostProcess["UserProcessor.postProcessUserGet()"]
-
-    DeleteUser["softDeleteUser()"] --> ValidateSelf["Prevent Self Delete"]
-    ValidateSelf --> ValidateOwner["Prevent OWNER Delete"]
-    ValidateOwner --> MarkDeleted["Set Status DELETED"]
-    MarkDeleted --> SaveUser["UserRepository.save()"]
-    SaveUser --> PostDelete["UserProcessor.postProcessUserDeleted()"]
-```
-
-### Soft Delete Rules
-
-- Users cannot delete themselves
-- OWNER role accounts cannot be deleted
-- Deletion sets status to `DELETED` instead of removing the record
-
-This preserves referential integrity and audit consistency.
-
----
-
-## SSO Configuration Lifecycle
-
-```mermaid
-flowchart TD
-    Upsert["upsertConfig()"] --> Exists{"Config Exists?"}
-    Exists -->|"Yes"| Update["Update Existing"]
-    Exists -->|"No"| Create["Create New"]
-    Update --> Encrypt["Encrypt Client Secret"]
-    Create --> Encrypt
-    Encrypt --> Save["SSOConfigRepository.save()"]
-    Save --> PostProcess["SSOConfigProcessor.postProcessConfigSaved()"]
-```
-
-### Important Behaviors
-
-- Client secrets are encrypted before persistence
-- Decryption occurs only when returning editable admin configuration
-- Enabling/disabling triggers processor hooks
-- Deletion triggers processor hooks
-
----
-
-## Extensibility Model
-
-All processors use:
-
-- `@Component`
-- `@ConditionalOnMissingBean`
-
-This allows:
-
-- OSS default no-op behavior
-- SaaS override with custom implementations
-- Multi-tenant side effects (auditing, events, provisioning, sync)
-
-This pattern ensures the module is both **framework-level stable** and **deployment-level customizable**.
-
----
-
-## Integration With Other Modules
-
-This module integrates closely with:
-
-- Authorization Service Core (SSO flows, tenant registration, OAuth)
-- Data Mongo Domain Model (User, Invitation, SSOConfig documents)
-- Api Service Core REST Controllers (UserController, SSOConfigController)
-
-It does not implement OAuth flows directly — it manages configuration and lifecycle hooks that support those flows.
-
----
-
-## Summary
-
-The **Api Service Core User Sso Services And Processors** module is the identity orchestration layer of the API service. It:
-
-- Centralizes user management
-- Governs SSO provider configuration
-- Enforces domain safety rules
-- Provides structured extension hooks
-- Enables SaaS override without modifying core logic
-
-Its clean separation between services and processors makes it highly maintainable and enterprise-ready.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-service-core-user-sso-services-and-processors/processors.md b/docs/reference/architecture/api-service-core-user-sso-services-and-processors/processors.md
deleted file mode 100644
index a6f72e41b..000000000
--- a/docs/reference/architecture/api-service-core-user-sso-services-and-processors/processors.md
+++ /dev/null
@@ -1,303 +0,0 @@
-# Processors
-
-The **Processors** module provides extension points for domain-specific post-processing logic within the API Service Core, specifically around user management, invitations, SSO configuration, and agent registration secrets.
-
-In OpenFrame’s modular architecture, Processors act as **hooks** that execute after core service operations complete. By default, they provide no-op (logging-only) implementations, but they are designed to be overridden in custom or enterprise deployments.
-
-This module lives under the *API Service Core – User, SSO Services and Processors* domain and works closely with the sibling Services module.
-
----
-
-## 1. Purpose and Design Philosophy
-
-The Processors module exists to:
-
-- Provide **post-operation hooks** for core domain actions
-- Enable **custom business logic injection** without modifying core services
-- Maintain **clean separation of concerns** between service logic and side effects
-- Support OSS deployments with safe default behavior
-
-All default implementations are annotated with:
-
-- `@Component`
-- `@ConditionalOnMissingBean`
-
-This ensures:
-
-- The default implementation is used in OSS environments
-- Custom implementations can transparently override the default behavior
-
----
-
-## 2. High-Level Architecture
-
-The Processors module sits between:
-
-- Core domain services (UserService, SSOConfigService, etc.)
-- Downstream side effects (notifications, audit, integrations, etc.)
-
-```mermaid
-flowchart LR
-    Controller["REST or GraphQL Controller"] --> Service["Core Service"]
-    Service --> DomainModel["Domain Model"]
-    Service --> Processor["Processor Interface"]
-    Processor --> DefaultImpl["Default Implementation"]
-    Processor --> CustomImpl["Custom Implementation (Optional)"]
-```
-
-### Key Characteristics
-
-- Services remain pure and focused on business rules
-- Processors encapsulate side effects
-- Spring’s conditional bean loading determines the active implementation
-
----
-
-## 3. Core Components
-
-The Processors module includes four default implementations:
-
-- DefaultAgentRegistrationSecretProcessor  
-- DefaultInvitationProcessor  
-- DefaultSSOConfigProcessor  
-- DefaultUserProcessor
-
-Each implements its respective processor interface and logs events by default.
-
----
-
-## 4. Agent Registration Secret Processing
-
-### Class
-
-`DefaultAgentRegistrationSecretProcessor`
-
-### Responsibilities
-
-- Post-process generated agent registration secrets
-- Post-process deactivated secrets
-- Provide safe logging in OSS mode
-
-### Interaction Flow
-
-```mermaid
-flowchart TD
-    Generator["Secret Generation Logic"] --> Persist["Persist AgentRegistrationSecret"]
-    Persist --> ProcessorCall["postProcessSecretGenerated()"]
-    ProcessorCall --> DefaultProcessor["DefaultAgentRegistrationSecretProcessor"]
-```
-
-### Extension Use Cases
-
-A custom implementation may:
-
-- Push secrets to an external vault
-- Emit audit events
-- Trigger management workflows
-- Notify external systems
-
-By default, only debug logging is performed.
-
----
-
-## 5. Invitation Processing
-
-### Class
-
-`DefaultInvitationProcessor`
-
-### Responsibilities
-
-- Post-process invitation creation
-- Post-process invitation revocation
-
-### Flow
-
-```mermaid
-flowchart TD
-    InvitationService["Invitation Service"] --> SaveInvitation["Persist Invitation"]
-    SaveInvitation --> ProcessorHook["postProcessInvitationCreated()"]
-    ProcessorHook --> DefaultInvitationProcessor["DefaultInvitationProcessor"]
-```
-
-### Typical Customization Scenarios
-
-A custom processor may:
-
-- Send email notifications
-- Publish events to Kafka or NATS
-- Integrate with external identity providers
-- Trigger onboarding workflows
-
-The default implementation logs metadata such as invitation ID and email.
-
----
-
-## 6. SSO Configuration Processing
-
-### Class
-
-`DefaultSSOConfigProcessor`
-
-### Responsibilities
-
-- Post-process SSO config save
-- Post-process SSO config deletion
-- Post-process SSO config toggle (enable/disable)
-
-### Flow
-
-```mermaid
-flowchart TD
-    SSOService["SSOConfigService"] --> SaveConfig["Persist SSOConfig"]
-    SaveConfig --> ProcessorHook["postProcessConfigSaved()"]
-    ProcessorHook --> DefaultSSOProcessor["DefaultSSOConfigProcessor"]
-```
-
-### Integration Context
-
-SSO configuration impacts:
-
-- OAuth/OIDC flows
-- Tenant authentication
-- Authorization Server behavior
-
-A custom processor could:
-
-- Register dynamic OAuth clients
-- Synchronize configuration with external IdPs
-- Invalidate authentication caches
-
-The default implementation performs debug logging only.
-
----
-
-## 7. User Processing
-
-### Class
-
-`DefaultUserProcessor`
-
-### Responsibilities
-
-- Post-process user deletion
-- Post-process user updates
-- Post-process user fetch (single)
-- Post-process user fetch (paged)
-
-### Flow Example: User Update
-
-```mermaid
-flowchart TD
-    UserController["UserController"] --> UserService["UserService"]
-    UserService --> PersistUser["Persist User"]
-    PersistUser --> ProcessorHook["postProcessUserUpdated()"]
-    ProcessorHook --> DefaultUserProcessor["DefaultUserProcessor"]
-```
-
-### Data Types Involved
-
-- User (Mongo domain model)
-- UserResponse (API DTO)
-- UserPageResponse (paginated DTO)
-
-### Customization Scenarios
-
-A custom implementation might:
-
-- Emit audit logs
-- Synchronize user state with external systems
-- Trigger deprovisioning in downstream tools
-- Enforce domain-level policies
-
-The default behavior is debug-level logging.
-
----
-
-## 8. Conditional Bean Strategy
-
-All default processors use:
-
-- `@ConditionalOnMissingBean(value = Interface.class, ignored = DefaultImpl.class)`
-
-This enables the following resolution model:
-
-```mermaid
-flowchart TD
-    SpringContext["Spring Application Context"] --> CheckCustom["Custom Bean Present?"]
-    CheckCustom -->|"Yes"| UseCustom["Use Custom Implementation"]
-    CheckCustom -->|"No"| UseDefault["Use Default Implementation"]
-```
-
-This pattern ensures:
-
-- Clean override without modifying core modules
-- Backward compatibility
-- Pluggable architecture for enterprise extensions
-
----
-
-## 9. Relationship to Services Module
-
-The Processors module complements the Services module located at:
-
-- [Services](../services/services.md)
-
-### Responsibility Split
-
-```mermaid
-flowchart LR
-    Services["Services Module"] -->|"Business Logic"| Domain["Domain Model"]
-    Services -->|"Calls"| Processors["Processors Module"]
-    Processors -->|"Side Effects"| ExternalSystems["External Systems"]
-```
-
-- Services handle validation, persistence, and domain rules
-- Processors handle post-operation side effects
-
-This clear boundary keeps the architecture maintainable and extensible.
-
----
-
-## 10. How Processors Fit Into the Overall System
-
-Within the broader OpenFrame platform:
-
-- Controllers (REST / GraphQL) invoke Services
-- Services mutate domain entities
-- Processors execute post-commit logic
-- External systems (notifications, auth server, integrations) react
-
-```mermaid
-flowchart TD
-    API["API Layer"] --> ServiceLayer["Service Layer"]
-    ServiceLayer --> RepositoryLayer["Repository Layer"]
-    ServiceLayer --> ProcessorLayer["Processors"]
-    ProcessorLayer --> Integration["Integrations / Events / Audit"]
-```
-
-This modular layering:
-
-- Prevents service bloat
-- Encourages testability
-- Enables OSS and enterprise feature differentiation
-
----
-
-## 11. Summary
-
-The **Processors** module provides structured extension points for:
-
-- Agent registration secrets
-- Invitations
-- SSO configuration
-- User lifecycle operations
-
-By default, implementations are safe and logging-only. In advanced deployments, these processors become powerful integration points that allow OpenFrame to plug into broader ecosystems without altering core service logic.
-
-The design promotes:
-
-- Clean architecture
-- Pluggability
-- Multi-tenant extensibility
-- Enterprise customization without forking core modules
diff --git a/docs/reference/architecture/api-service-core-user-sso-services-and-processors/services.md b/docs/reference/architecture/api-service-core-user-sso-services-and-processors/services.md
deleted file mode 100644
index 456083ead..000000000
--- a/docs/reference/architecture/api-service-core-user-sso-services-and-processors/services.md
+++ /dev/null
@@ -1,302 +0,0 @@
-# Services
-
-The **Services** module contains the core application services responsible for user management, Single Sign-On (SSO) configuration, and domain validation within the OpenFrame API Service Core.
-
-These services sit between controllers (REST and GraphQL) and the data layer, encapsulating business logic, validation, orchestration, and post-processing hooks. They integrate with repositories, processors, mappers, encryption utilities, and tenant/domain validation infrastructure.
-
----
-
-## 1. Module Responsibilities
-
-The Services module provides:
-
-- ✅ User lifecycle management (read, update, soft delete)
-- ✅ SSO configuration management (CRUD, toggle, validation)
-- ✅ Domain validation extension point (SaaS overrides)
-- ✅ Post-processing hooks via processors
-- ✅ Secure handling of secrets (via encryption service)
-
-Core components:
-
-- `DefaultDomainExistenceValidator`
-- `SSOConfigService`
-- `UserService`
-
----
-
-## 2. Architectural Position
-
-The Services module operates inside the API Service Core and collaborates with multiple surrounding modules.
-
-```mermaid
-flowchart LR
-    subgraph Controllers["API Layer"]
-        RestControllers["REST Controllers"]
-        GraphQL["GraphQL DataFetchers"]
-    end
-
-    subgraph ServicesLayer["Services Module"]
-        UserServiceNode["UserService"]
-        SSOServiceNode["SSOConfigService"]
-        DomainValidator["DefaultDomainExistenceValidator"]
-    end
-
-    subgraph Processors["Processors"]
-        UserProcessorNode["UserProcessor"]
-        SSOProcessorNode["SSOConfigProcessor"]
-    end
-
-    subgraph DataLayer["Data Layer"]
-        UserRepo["UserRepository"]
-        SSORepo["SSOConfigRepository"]
-        MongoDocs["Mongo Domain Models"]
-    end
-
-    Controllers --> ServicesLayer
-    ServicesLayer --> Processors
-    ServicesLayer --> DataLayer
-```
-
-### Key Relationships
-
-- Controllers invoke Services for business operations.
-- Services delegate side-effects to Processors.
-- Services persist and query through repositories.
-- Domain validation is pluggable and environment-aware.
-
----
-
-## 3. UserService
-
-`UserService` encapsulates all user-related domain logic for the API layer.
-
-### 3.1 Responsibilities
-
-- Retrieve users by ID or email
-- Paginated listing
-- Bulk fetch by IDs
-- Update profile fields
-- Soft delete users with safety checks
-- Trigger lifecycle processors
-
-### 3.2 Core Dependencies
-
-- `UserRepository`
-- `UserMapper`
-- `UserProcessor`
-- Mongo `User` document
-
-### 3.3 User Lifecycle Flow
-
-```mermaid
-flowchart TD
-    Request["User Update Request"] --> Load["Load User from Repository"]
-    Load --> Check{"User Exists?"}
-    Check -->|"No"| Error["Throw IllegalArgumentException"]
-    Check -->|"Yes"| Modify["Apply Field Updates"]
-    Modify --> Save["Save via UserRepository"]
-    Save --> PostProcess["UserProcessor.postProcessUserUpdated()"]
-    PostProcess --> Response["Return UserResponse"]
-```
-
-### 3.4 Soft Delete Safety Rules
-
-Soft deletion includes strict business constraints:
-
-- A user **cannot delete themselves** → `UserSelfDeleteNotAllowedException`
-- A user with `OWNER` role cannot be deleted → `OperationNotAllowedException`
-- Deletion sets status to `DELETED` instead of removing the document
-
-```mermaid
-flowchart TD
-    DeleteRequest["Soft Delete Request"] --> LoadUser["Load User"]
-    LoadUser --> SelfCheck{"Requester == Target?"}
-    SelfCheck -->|"Yes"| SelfError["Throw Self Delete Exception"]
-    SelfCheck -->|"No"| OwnerCheck{"Has OWNER Role?"}
-    OwnerCheck -->|"Yes"| OwnerError["Throw OperationNotAllowedException"]
-    OwnerCheck -->|"No"| MarkDeleted["Set Status = DELETED"]
-    MarkDeleted --> SaveDeleted["Save User"]
-    SaveDeleted --> PostDelete["UserProcessor.postProcessUserDeleted()"]
-```
-
-This ensures organizational integrity and prevents accidental tenant lockout.
-
----
-
-## 4. SSOConfigService
-
-`SSOConfigService` manages Single Sign-On provider configuration for the tenant.
-
-### 4.1 Responsibilities
-
-- List enabled providers
-- Return editable configuration (including decrypted secret)
-- Create or update provider config (upsert)
-- Toggle provider enabled state
-- Delete provider configuration
-- Validate domain and provisioning constraints
-- Trigger SSO lifecycle processors
-
-### 4.2 Core Dependencies
-
-- `SSOConfigRepository`
-- `EncryptionService`
-- `SSOProperties`
-- `SSOConfigProcessor`
-- `SSOConfigMapper`
-- `DomainValidationService`
-
-### 4.3 SSO Configuration Flow
-
-```mermaid
-flowchart TD
-    AdminRequest["Upsert SSOConfigRequest"] --> Validate["validateAutoProvision()"]
-    Validate --> Normalize["Normalize Domains"]
-    Normalize --> DomainValidation["DomainValidationService.validate*"]
-    DomainValidation --> Encrypt["Encrypt Client Secret"]
-    Encrypt --> SaveConfig["Save via SSOConfigRepository"]
-    SaveConfig --> PostProcess["SSOConfigProcessor.postProcessConfigSaved()"]
-    PostProcess --> ReturnResponse["Return SSOConfigResponse"]
-```
-
-### 4.4 Domain Validation Logic
-
-When `autoProvisionUsers` is enabled:
-
-- ✅ `allowedDomains` must not be empty
-- ✅ Domains are normalized (trimmed, lowercased, deduplicated)
-- ✅ Public/generic domains are rejected
-- ✅ Domains must exist (pluggable validator)
-- ✅ Microsoft provider requires `msTenantId` when auto-provisioning
-
-This ensures secure enterprise SSO onboarding.
-
-### 4.5 Secure Secret Handling
-
-- Client secrets are encrypted before persistence.
-- Decryption occurs only when returning editable configuration.
-- Encryption is delegated to `EncryptionService`.
-
----
-
-## 5. DefaultDomainExistenceValidator
-
-`DefaultDomainExistenceValidator` provides the baseline implementation for domain existence checks.
-
-### 5.1 Behavior
-
-```java
-public boolean anyExists(List<String> domains) {
-    return false;
-}
-```
-
-### 5.2 Design Purpose
-
-- Acts as a **non-blocking default** implementation.
-- Enabled via `@ConditionalOnMissingBean`.
-- Allows SaaS or enterprise deployments to override with a stricter validator.
-
-```mermaid
-flowchart LR
-    DomainService["DomainValidationService"] --> Interface["DomainExistenceValidator"]
-    Interface --> DefaultImpl["DefaultDomainExistenceValidator"]
-    Interface --> CustomImpl["SaaS Override Implementation"]
-```
-
-This pattern supports multi-tenant SaaS deployments where domain ownership must be verified.
-
----
-
-## 6. Cross-Cutting Patterns
-
-### 6.1 Processor Hook Pattern
-
-Services delegate side effects to processors after core operations:
-
-- `postProcessUserGet`
-- `postProcessUserUpdated`
-- `postProcessUserDeleted`
-- `postProcessConfigSaved`
-- `postProcessConfigDeleted`
-- `postProcessConfigToggled`
-
-This keeps services focused on:
-
-- Validation
-- Persistence
-- Mapping
-
-While processors handle:
-
-- Audit logging
-- External sync
-- Notifications
-- Policy enforcement
-
-```mermaid
-sequenceDiagram
-    participant Controller
-    participant Service
-    participant Repository
-    participant Processor
-
-    Controller->>Service: Update Request
-    Service->>Repository: Save Entity
-    Repository-->>Service: Saved Entity
-    Service->>Processor: postProcess(...)
-    Service-->>Controller: Response DTO
-```
-
----
-
-## 7. Integration with Other Modules
-
-The Services module integrates with:
-
-- API Service Core Controllers (REST & GraphQL)
-- Mongo domain and repository modules
-- Security and OAuth infrastructure
-- Authorization Service for SSO flows
-- Encryption and crypto services
-
-High-level integration view:
-
-```mermaid
-flowchart TD
-    Client["Client Application"] --> Gateway["Gateway Service"]
-    Gateway --> ApiCore["API Service Core"]
-    ApiCore --> ServicesNode["Services Module"]
-    ServicesNode --> Mongo[("MongoDB")]
-    ServicesNode --> Authz["Authorization Service"]
-    ServicesNode --> Crypto["Encryption Service"]
-```
-
----
-
-## 8. Design Principles
-
-The Services module follows these architectural principles:
-
-- ✅ Clear separation of concerns
-- ✅ Stateless service layer
-- ✅ Repository-driven persistence
-- ✅ DTO ↔ Entity mapping abstraction
-- ✅ Post-operation extension hooks
-- ✅ Pluggable domain validation
-- ✅ Secure secret handling
-- ✅ Defensive business rule enforcement
-
----
-
-# Summary
-
-The **Services** module forms the business logic core of user and SSO management within OpenFrame’s API Service Core. It ensures:
-
-- Secure and validated SSO onboarding
-- Safe user lifecycle operations
-- Tenant-aware domain validation
-- Extensible post-processing
-- Clean separation between API, business logic, and persistence layers
-
-It acts as the orchestration layer that binds controllers, repositories, processors, and security infrastructure into a cohesive, enterprise-ready service architecture.
\ No newline at end of file
diff --git a/docs/reference/architecture/authorization-service-core-auth-controllers-and-dtos/authorization-service-core-auth-controllers-and-dtos.md b/docs/reference/architecture/authorization-service-core-auth-controllers-and-dtos/authorization-service-core-auth-controllers-and-dtos.md
deleted file mode 100644
index 2445546a4..000000000
--- a/docs/reference/architecture/authorization-service-core-auth-controllers-and-dtos/authorization-service-core-auth-controllers-and-dtos.md
+++ /dev/null
@@ -1,393 +0,0 @@
-# Authorization Service Core Auth Controllers And Dtos
-
-## Overview
-
-The **Authorization Service Core Auth Controllers And Dtos** module exposes the public HTTP interface for tenant onboarding, login, invitation acceptance, password reset, SSO discovery, and tenant discovery within the OpenFrame multi-tenant authorization system.
-
-It acts as the **edge layer** of the Authorization Service Core, translating HTTP requests into domain-level service calls and orchestrating redirects, cookies, and validation logic.
-
-This module is tightly integrated with:
-
-- The authorization server and tenant context layer:  
-  [Authorization Service Core Server And Tenant](../authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md)
-- The SSO flow and security utilities layer (redirect helpers, auth state utilities, registration constants)
-- The persistence and key management layer (Mongo authorization service, client repositories, tenant keys)
-
----
-
-## Architectural Role
-
-This module sits at the boundary between:
-
-- 🌐 External clients (browser, SPA, CLI, third-party tools)
-- 🔐 Spring Security & OAuth2 Authorization Server
-- 🏢 Multi-tenant domain services
-
-It contains:
-
-- REST controllers
-- MVC login controller
-- Request/response DTOs
-- Validation annotations
-
-### High-Level Request Flow
-
-```mermaid
-flowchart LR
-    Client["Browser / Client App"] --> Controllers["Auth Controllers"]
-    Controllers --> Services["Domain Services"]
-    Services --> Persistence["Authorization & Tenant Persistence"]
-    Services --> Security["Spring Security / OAuth2"]
-    Security --> Client
-```
-
-The controllers remain intentionally thin. All business logic is delegated to service-layer components such as:
-
-- `InvitationRegistrationService`
-- `SsoInvitationService`
-- `TenantRegistrationService`
-- `TenantDiscoveryService`
-- `PasswordResetService`
-
----
-
-# Controllers
-
-## 1. InvitationRegistrationController
-
-**Base path:** `/invitations`
-
-Handles invitation-based onboarding, both standard and SSO-based.
-
-### Endpoints
-
-#### `POST /invitations/accept`
-Registers a user using an invitation token.
-
-- Input: `InvitationRegistrationRequest`
-- Output: `AuthUser`
-- Delegates to: `InvitationRegistrationService`
-
-#### `GET /invitations/accept/sso`
-Initiates SSO-based invitation acceptance.
-
-Flow:
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant Controller as InvitationRegistrationController
-    participant SSOService as SsoInvitationService
-    participant IdP as External IdP
-
-    Browser->>Controller: GET /invitations/accept/sso
-    Controller->>SSOService: startAccept(request)
-    SSOService-->>Controller: SsoAuthorizeData
-    Controller->>Browser: Set-Cookie + 303 Redirect
-    Browser->>IdP: OAuth2 Authorization Request
-```
-
-Key behaviors:
-
-- Clears previous auth state using `AuthStateUtils`
-- Sets secure, HTTP-only SSO invitation cookie
-- Performs 303 redirect using `Redirects.seeOther`
-- Encodes error message and redirects to configured `openframe.auth.error-url` on failure
-
----
-
-## 2. TenantRegistrationController
-
-**Base path:** `/oauth`
-
-Responsible for creating new tenants via:
-
-- Password-based registration
-- SSO-based registration
-
-### `POST /oauth/register`
-
-Registers a new tenant and initial user.
-
-- Input: `TenantRegistrationRequest`
-- Output: `Tenant`
-- Delegates to: `TenantRegistrationService`
-
-### `GET /oauth/register/sso`
-
-Initiates SSO tenant registration.
-
-```mermaid
-flowchart TD
-    Start["User Clicks Register with SSO"] --> Clear["Clear Auth State"]
-    Clear --> StartReg["SsoTenantRegistrationService.startRegistration()"]
-    StartReg --> Cookie["Set COOKIE_SSO_REG"]
-    Cookie --> Redirect["Redirect to IdP"]
-```
-
-Security properties:
-
-- Secure cookies
-- HTTP-only flags
-- Tenant-scoped redirect path
-- Centralized error handling
-
----
-
-## 3. LoginController
-
-MVC controller (not REST).
-
-### Endpoints
-
-- `GET /login` → renders login page
-- `GET /` → renders index page
-
-Responsibilities:
-
-- Inject error message when `?error` query param is present
-- Expose optional password reset URL from configuration
-
-This controller integrates with Spring Security login processing.
-
----
-
-## 4. PasswordResetController
-
-**Base path:** `/password-reset`
-
-Handles password recovery flows.
-
-### `POST /password-reset/request`
-
-- Input: `ResetRequest`
-- Normalizes email to lowercase
-- Delegates to `PasswordResetService.createResetToken`
-- Returns HTTP 202 (Accepted)
-
-### `POST /password-reset/confirm`
-
-- Input: `ResetConfirm`
-- Enforces strong password pattern validation
-- Delegates to `PasswordResetService.resetPassword`
-- Returns HTTP 204 (No Content)
-
-Password validation rules:
-
-- Minimum 8 characters
-- At least one uppercase
-- At least one lowercase
-- At least one digit
-- At least one special character
-
----
-
-## 5. SsoDiscoveryController
-
-**Base path:** `/sso/providers`
-
-Used by frontend before redirecting to SSO provider.
-
-### `GET /sso/providers/invite`
-
-- Requires `invitationId`
-- Loads invitation via `InvitationValidator`
-- Returns effective providers for tenant
-
-### `GET /sso/providers/registration`
-
-- Returns system default SSO providers
-- Delegates to `SSOConfigService`
-
-Response model:
-
-```text
-{
-  "providers": ["google", "microsoft"]
-}
-```
-
----
-
-## 6. TenantDiscoveryController
-
-**Base path:** `/tenant`
-
-Supports multi-tenant login UX.
-
-### `GET /tenant/discover?email=`
-
-Returns:
-
-- Whether accounts exist
-- Associated tenant ID
-- Available authentication providers
-
-Flow:
-
-```mermaid
-flowchart LR
-    User["User enters email"] --> Controller["TenantDiscoveryController"]
-    Controller --> Service["TenantDiscoveryService"]
-    Service --> Response["TenantDiscoveryResponse"]
-```
-
-Used to determine:
-
-- Password login vs SSO
-- Redirect to tenant-specific issuer
-
----
-
-# DTO Layer
-
-The DTOs define the external API contract and enforce validation constraints.
-
-## InvitationRegistrationRequest
-
-Extends `CoreUserRequest`.
-
-Fields:
-
-- `invitationId` (required)
-- `switchTenant` (optional)
-
----
-
-## TenantRegistrationRequest
-
-Extends `CoreUserRequest`.
-
-Fields:
-
-- `email`
-- `tenantName`
-- `tenantDomain`
-- `accessCode`
-
-Validation ensures:
-
-- Proper tenant domain format
-- Organization name pattern restrictions
-
----
-
-## SsoTenantRegistrationInitRequest
-
-Used before redirecting to IdP.
-
-Fields:
-
-- `email`
-- `tenantName`
-- `tenantDomain`
-- `provider`
-- `redirectTo`
-
-This ensures the system has enough context to:
-
-- Create tenant if needed
-- Attach SSO configuration
-- Prepare OAuth2 client registration
-
----
-
-## SsoInvitationAcceptRequest
-
-Fields:
-
-- `invitationId`
-- `provider`
-- `switchTenant`
-- `redirectTo`
-
-Used to bootstrap SSO flow for invited users.
-
----
-
-## PasswordResetDtos
-
-Two nested DTOs:
-
-- `ResetRequest`
-- `ResetConfirm`
-
-Encapsulates strict password validation rules.
-
----
-
-## TenantDiscoveryResponse
-
-```text
-{
-  "email": "user@example.com",
-  "has_existing_accounts": true,
-  "tenant_id": "tenant123",
-  "auth_providers": ["password", "google"]
-}
-```
-
----
-
-## TenantAvailabilityResponse
-
-Indicates whether a tenant domain is available and suggests alternatives.
-
----
-
-# Multi-Tenant & Security Integration
-
-This module works in conjunction with:
-
-- Tenant context resolution
-- OAuth2 authorization server
-- SSO provider strategies (Google, Microsoft)
-- Registration processors
-- Token generation and persistence
-
-### Cross-Module Interaction
-
-```mermaid
-flowchart TD
-    Controllers["Auth Controllers"] --> TenantLayer["Tenant Context Layer"]
-    Controllers --> SSOFlow["SSO Flow & Handlers"]
-    Controllers --> AuthServer["OAuth2 Authorization Server"]
-    AuthServer --> Persistence["Mongo Authorization Service"]
-```
-
-The controllers do not directly manipulate:
-
-- JWT generation
-- Key pairs
-- OAuth token storage
-- Client registration persistence
-
-These responsibilities are delegated to the lower layers of the Authorization Service Core.
-
----
-
-# Design Principles
-
-✅ Thin controllers  
-✅ Strong DTO validation  
-✅ Clear separation of concerns  
-✅ Secure cookie handling  
-✅ Explicit redirect logic  
-✅ Multi-tenant aware flows  
-✅ SSO-provider abstraction  
-
----
-
-# Summary
-
-The **Authorization Service Core Auth Controllers And Dtos** module defines the complete public-facing contract of the OpenFrame Authorization Service.
-
-It:
-
-- Exposes login, registration, invitation, and password reset APIs
-- Coordinates SSO bootstrap and redirect logic
-- Enforces strict validation rules
-- Supports multi-tenant discovery and onboarding
-- Bridges HTTP requests to secure, tenant-aware domain services
-
-This module is the entry point into the OpenFrame multi-tenant identity and authorization infrastructure.
\ No newline at end of file
diff --git a/docs/reference/architecture/authorization-service-core-keys-and-authorization-persistence/authorization-service-core-keys-and-authorization-persistence.md b/docs/reference/architecture/authorization-service-core-keys-and-authorization-persistence/authorization-service-core-keys-and-authorization-persistence.md
deleted file mode 100644
index abca1c21b..000000000
--- a/docs/reference/architecture/authorization-service-core-keys-and-authorization-persistence/authorization-service-core-keys-and-authorization-persistence.md
+++ /dev/null
@@ -1,355 +0,0 @@
-# Authorization Service Core Keys And Authorization Persistence
-
-## Overview
-
-The **Authorization Service Core Keys And Authorization Persistence** module is responsible for:
-
-- Generating and managing tenant-scoped RSA signing keys
-- Converting RSA keys to and from PEM format
-- Persisting OAuth2 registered clients
-- Persisting OAuth2 authorizations (authorization codes, access tokens, refresh tokens)
-- Preserving PKCE metadata across the authorization lifecycle
-
-This module forms the cryptographic and persistence backbone of the Authorization Server. It ensures that:
-
-- Each tenant has a secure signing key used for JWT issuance
-- OAuth2 clients are stored and reconstructed correctly
-- Authorization state (including PKCE parameters) survives restarts and distributed deployments
-
-It integrates tightly with Spring Authorization Server, MongoDB repositories, and the tenant-aware authorization server configuration.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    ClientApp["OAuth2 Client Application"] --> AuthServer["Authorization Server"]
-
-    subgraph key_layer["Tenant Key Layer"]
-        TenantKeyService["TenantKeyService"] --> KeyGenerator["RsaAuthenticationKeyPairGenerator"]
-        TenantKeyService --> PemUtil["PemUtil"]
-        TenantKeyService --> TenantKeyRepo["TenantKeyRepository"]
-        TenantKeyService --> EncryptionService["EncryptionService"]
-    end
-
-    subgraph client_layer["Client Registration Layer"]
-        RegisteredRepo["MongoRegisteredClientRepository"] --> MongoClientRepo["RegisteredClientMongoRepository"]
-    end
-
-    subgraph auth_layer["Authorization Persistence Layer"]
-        AuthService["MongoAuthorizationService"] --> AuthMapper["MongoAuthorizationMapper"]
-        AuthService --> MongoAuthRepo["MongoOAuth2AuthorizationRepository"]
-        AuthMapper --> MongoEntity["MongoOAuth2Authorization"]
-    end
-
-    AuthServer --> TenantKeyService
-    AuthServer --> RegisteredRepo
-    AuthServer --> AuthService
-```
-
-### Responsibilities by Layer
-
-| Layer | Responsibility |
-|--------|----------------|
-| Tenant Key Layer | RSA key generation, encryption, and retrieval per tenant |
-| Client Registration Layer | Persistent storage of OAuth2 RegisteredClient definitions |
-| Authorization Persistence Layer | Persistent storage of authorization codes, access tokens, refresh tokens, and PKCE metadata |
-
----
-
-## Tenant RSA Key Management
-
-### Purpose
-
-The Authorization Service must sign JWT access tokens and ID tokens. In a multi-tenant system, each tenant requires its own signing key to:
-
-- Isolate cryptographic trust boundaries
-- Support per-tenant key rotation
-- Prevent cross-tenant token misuse
-
-### Core Components
-
-- `PemUtil`
-- `RsaAuthenticationKeyPairGenerator`
-- `TenantKeyService`
-
----
-
-### PemUtil
-
-`PemUtil` is a low-level utility that:
-
-- Parses PEM-encoded RSA public/private keys
-- Serializes RSA keys into PEM format
-- Wraps base64 content into 64-character lines
-
-Supported formats:
-
-```text
------BEGIN PUBLIC KEY-----
-(base64)
------END PUBLIC KEY-----
-
------BEGIN PRIVATE KEY-----
-(base64)
------END PRIVATE KEY-----
-```
-
-This class ensures interoperability with external JWK and JWT libraries.
-
----
-
-### RsaAuthenticationKeyPairGenerator
-
-This Spring component generates RSA key pairs using configurable properties:
-
-- Algorithm (for example, RSA)
-- Key size (for example, 2048 or 4096)
-- SecureRandom algorithm
-
-Generation flow:
-
-```mermaid
-flowchart TD
-    Start["Generate Key Pair"] --> InitRandom["Initialize SecureRandom"]
-    InitRandom --> InitGenerator["Initialize KeyPairGenerator"]
-    InitGenerator --> Generate["Generate RSA KeyPair"]
-    Generate --> ConvertPem["Convert to PEM"]
-    ConvertPem --> CreateKid["Create kid UUID"]
-    CreateKid --> Result["Return AuthenticationKeyPair"]
-```
-
-Each generated key pair includes:
-
-- RSAPublicKey
-- RSAPrivateKey
-- Public PEM
-- Private PEM
-- `kid` (Key ID) prefixed with `kid-`
-
-The `kid` is later embedded into JWT headers.
-
----
-
-### TenantKeyService
-
-`TenantKeyService` provides the runtime contract used by the Authorization Server to retrieve signing keys.
-
-#### Responsibilities
-
-1. Retrieve active key for a tenant
-2. Generate and persist a key if none exists
-3. Encrypt private key material before persistence
-4. Return a Nimbus `RSAKey` for signing
-
-#### getOrCreateActiveKey Flow
-
-```mermaid
-flowchart TD
-    Request["Request RSAKey for Tenant"] --> CheckActive["Check Active Key Count"]
-    CheckActive --> Found{"Active Key Exists?"}
-    Found -->|"Yes"| LoadDoc["Load TenantKey Document"]
-    Found -->|"No"| Create["Generate New Key"]
-    Create --> Encrypt["Encrypt Private PEM"]
-    Encrypt --> Save["Save TenantKey"]
-    Save --> LoadDoc
-    LoadDoc --> Parse["Parse PEM to RSA Keys"]
-    Parse --> BuildJwk["Build Nimbus RSAKey"]
-    BuildJwk --> Return["Return RSAKey"]
-```
-
-#### Security Model
-
-- Public key is stored in plaintext PEM.
-- Private key is encrypted using `EncryptionService` before persistence.
-- Only decrypted in-memory during signing operations.
-
-If multiple active keys are detected for a tenant, a warning is logged to prevent `kid` mismatches.
-
----
-
-## OAuth2 Client Persistence
-
-### MongoRegisteredClientRepository
-
-This class implements Spring Authorization Server's `RegisteredClientRepository` interface.
-
-It acts as a bridge between:
-
-- Spring `RegisteredClient`
-- Mongo `MongoRegisteredClient` document
-
-### Save Mapping
-
-On save:
-
-- Authentication methods are converted to string values
-- Grant types are converted to string values
-- Token TTL values are converted to seconds
-- PKCE requirement flags are persisted
-
-### Reconstruction Mapping
-
-On retrieval:
-
-- `ClientSettings` is rebuilt
-- `TokenSettings` is rebuilt
-- Authentication methods and grant types are rehydrated
-- Redirect URIs and scopes are restored
-
-This ensures full compatibility with Spring Authorization Server runtime expectations.
-
----
-
-## OAuth2 Authorization Persistence
-
-### Core Components
-
-- `MongoAuthorizationService`
-- `MongoAuthorizationMapper`
-
-These classes implement and support Spring's `OAuth2AuthorizationService`.
-
----
-
-## MongoAuthorizationMapper
-
-This class converts between:
-
-- `OAuth2Authorization` (Spring domain model)
-- `MongoOAuth2Authorization` (Mongo document)
-
-It persists:
-
-- Authorization grant type
-- Authorization code
-- Access token
-- Refresh token
-- State
-- PKCE parameters
-- Authorization request snapshot
-
-### PKCE Preservation Strategy
-
-PKCE parameters (`code_challenge`, `code_challenge_method`) are captured from:
-
-- OAuth2AuthorizationRequest additional parameters
-- Authorization code metadata
-
-They are normalized and stored in:
-
-- `arAdditional`
-- `authorizationCodeMetadata`
-
-When reconstructing:
-
-- PKCE keys are restored with underscore format
-- Both dot and underscore variants are normalized
-- OAuth2AuthorizationRequest is rebuilt
-
-This ensures PKCE validation works correctly during token exchange.
-
----
-
-## MongoAuthorizationService
-
-Implements `OAuth2AuthorizationService`.
-
-### Save Flow
-
-```mermaid
-flowchart TD
-    SaveCall["Save Authorization"] --> ExtractPkce["Extract PKCE Parameters"]
-    ExtractPkce --> MapEntity["Map to Mongo Entity"]
-    MapEntity --> Persist["Save to Mongo"]
-    Persist --> Verify["Debug Verify PKCE"]
-```
-
-### Token Lookup Flow
-
-```mermaid
-flowchart TD
-    Lookup["Find By Token"] --> TypeCheck{"Token Type?"}
-    TypeCheck -->|"Access"| AccessQuery["Find By Access Token"]
-    TypeCheck -->|"Refresh"| RefreshQuery["Find By Refresh Token"]
-    TypeCheck -->|"Code"| CodeQuery["Find By Authorization Code"]
-    TypeCheck -->|"Null"| MultiQuery["Try All Token Fields"]
-    AccessQuery --> MapBack["Map to Domain"]
-    RefreshQuery --> MapBack
-    CodeQuery --> MapBack
-    MultiQuery --> MapBack
-    MapBack --> ReturnAuth["Return OAuth2Authorization"]
-```
-
-It supports lookup by:
-
-- Access token
-- Refresh token
-- Authorization code
-- State
-
-After retrieval, the entity is mapped back to `OAuth2Authorization`, ensuring:
-
-- PKCE metadata is restored
-- Principal placeholder is recreated
-- Tokens are rebuilt with correct expiry
-
----
-
-## End-to-End Authorization Lifecycle
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant AuthServer
-    participant KeyService
-    participant AuthService
-    participant MongoDB
-
-    User->>AuthServer: Authorization Request with PKCE
-    AuthServer->>AuthService: Save OAuth2Authorization
-    AuthService->>MongoDB: Persist Authorization Code
-    AuthServer->>KeyService: Get Tenant Signing Key
-    KeyService->>MongoDB: Load or Create TenantKey
-    KeyService->>AuthServer: Return RSAKey
-    AuthServer->>User: Issue JWT Access Token
-    User->>AuthServer: Token Exchange
-    AuthServer->>AuthService: Find Authorization by Code
-    AuthService->>MongoDB: Retrieve Authorization
-    AuthServer->>User: Return Access and Refresh Tokens
-```
-
----
-
-## Security Considerations
-
-1. Private Key Encryption
-   - Private RSA keys are encrypted before Mongo persistence.
-   - Decrypted only when building the runtime RSAKey.
-
-2. PKCE Integrity
-   - PKCE values are preserved exactly as provided.
-   - Underscore normalization avoids validation mismatches.
-
-3. Token Expiry
-   - TTL values are enforced through stored expiration timestamps.
-   - Expired authorizations can be pruned by repository-level TTL logic.
-
-4. Multi-Tenant Isolation
-   - Each tenant has an isolated signing key.
-   - Each authorization record references its registered client.
-
----
-
-## Summary
-
-The **Authorization Service Core Keys And Authorization Persistence** module provides:
-
-- Cryptographically secure tenant-aware RSA key management
-- Robust Mongo-backed OAuth2 client persistence
-- Reliable authorization and token persistence
-- Full PKCE support with metadata normalization
-- Seamless integration with Spring Authorization Server
-
-It is the foundation that guarantees secure JWT issuance, correct OAuth2 behavior, and multi-tenant isolation within the OpenFrame Authorization Server architecture.
diff --git a/docs/reference/architecture/authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md b/docs/reference/architecture/authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md
deleted file mode 100644
index 5fbba1505..000000000
--- a/docs/reference/architecture/authorization-service-core-server-and-tenant/authorization-service-core-server-and-tenant.md
+++ /dev/null
@@ -1,405 +0,0 @@
-# Authorization Service Core Server And Tenant
-
-## Overview
-
-The **Authorization Service Core Server And Tenant** module is the heart of OpenFrame's multi-tenant identity and OAuth2 infrastructure. It implements a fully multi-tenant OAuth2 Authorization Server using Spring Authorization Server, with per-tenant key material, dynamic client registration, and tenant-aware authentication flows.
-
-This module is responsible for:
-
-- Acting as the OAuth2 / OIDC Authorization Server
-- Issuing tenant-scoped JWT access tokens and refresh tokens
-- Managing per-tenant signing keys (JWKS)
-- Resolving tenant context for every request
-- Integrating with SSO and dynamic OAuth2 clients
-- Enforcing tenant isolation at the authentication and token layers
-
-It works closely with:
-
-- Data Mongo Domain Model (users, OAuth clients, tokens)
-- Security Core And OAuth BFF (shared security constants and utilities)
-- Gateway Service Core Security And Routing (JWT validation and issuer routing)
-- Authorization Service Core SSO Flow And Utils (SSO login, provider strategies)
-
----
-
-## High-Level Architecture
-
-The module is composed of five core building blocks:
-
-- Authorization Server Configuration
-- Default Security Configuration
-- Dynamic Client Registration
-- Tenant Context Management
-- Tenant-Aware Key Infrastructure
-
-```mermaid
-flowchart TD
-    Client["Browser or API Client"] --> Gateway["Gateway Service"]
-    Gateway --> Authz["Authorization Service Core Server And Tenant"]
-
-    subgraph authz_core["Authorization Layer"]
-        TenantFilter["TenantContextFilter"]
-        AuthServerConfig["AuthorizationServerConfig"]
-        SecurityConfigBean["SecurityConfig"]
-        DynamicClientRepo["DynamicClientRegistrationRepository"]
-        TenantKeySvc["TenantKeyService"]
-    end
-
-    Authz --> TenantFilter
-    TenantFilter --> AuthServerConfig
-    TenantFilter --> SecurityConfigBean
-    AuthServerConfig --> TenantKeySvc
-    SecurityConfigBean --> DynamicClientRepo
-
-    AuthServerConfig --> JWKS["Per-Tenant JWKS"]
-    AuthServerConfig --> JWT["Signed JWT Tokens"]
-```
-
----
-
-## Multi-Tenant Design Principles
-
-The Authorization Service Core Server And Tenant module is built around strict tenant isolation:
-
-1. Every request must resolve a tenant identifier.
-2. Every JWT contains a `tenant_id` claim.
-3. Every tenant has its own RSA key pair.
-4. OAuth2 client registrations are resolved dynamically per tenant.
-5. User authentication always queries tenant-scoped user records.
-
-Tenant identity flows through the entire request lifecycle using a thread-local context.
-
----
-
-## Tenant Context Management
-
-### TenantContext
-
-Component:
-- `openframe-oss-lib.openframe-authorization-service-core.src.main.java.com.openframe.authz.config.tenant.TenantContext.TenantContext`
-
-A lightweight `ThreadLocal` holder storing the current tenant ID for the duration of a request.
-
-Responsibilities:
-
-- Store tenant ID per thread
-- Provide `setTenantId`, `getTenantId`, and `clear`
-- Ensure isolation between concurrent requests
-
-```mermaid
-flowchart LR
-    Request["Incoming HTTP Request"] --> Filter["TenantContextFilter"]
-    Filter --> ThreadLocal["TenantContext ThreadLocal"]
-    ThreadLocal --> Services["UserService and Key Services"]
-```
-
----
-
-### TenantContextFilter
-
-Component:
-- `openframe-oss-lib.openframe-authorization-service-core.src.main.java.com.openframe.authz.config.tenant.TenantContextFilter.TenantContextFilter`
-
-This filter executes early in the filter chain and resolves the tenant ID using:
-
-- URL path prefix (for example `/tenantId/oauth2/authorize`)
-- Query parameter `tenant`
-- Existing HTTP session attribute
-
-Key behaviors:
-
-- Stores tenant ID in both session and `TenantContext`
-- Prevents unsafe cross-tenant session reuse
-- Allows special onboarding tenant switching
-- Clears context after request completion
-
-Tenant resolution directly influences:
-
-- JWT signing key selection
-- OAuth2 client registration
-- User lookup and authentication
-
----
-
-## Authorization Server Configuration
-
-### AuthorizationServerConfig
-
-Component:
-- `openframe-oss-lib.openframe-authorization-service-core.src.main.java.com.openframe.authz.config.AuthorizationServerConfig.AuthorizationServerConfig`
-
-This class configures Spring Authorization Server with multi-issuer support.
-
-### Key Responsibilities
-
-- Enables OIDC support
-- Allows multiple issuers (`multipleIssuersAllowed(true)`)
-- Configures OAuth2 endpoints
-- Sets up JWT encoder and decoder
-- Defines token customization logic
-- Registers tenant-aware JWK source
-
-### Security Filter Chain (Order 1)
-
-```mermaid
-flowchart TD
-    Request["OAuth2 Endpoint Request"] --> Match["Authorization Endpoints Matcher"]
-    Match --> Authenticated["Require Authentication"]
-    Authenticated --> JWTValidation["JWT Resource Server Enabled"]
-    JWTValidation --> Response["OAuth2 Response"]
-```
-
-This chain applies only to Authorization Server endpoints.
-
----
-
-## Per-Tenant Key Infrastructure
-
-### JWKSource and TenantKeyService Integration
-
-The `jwkSource` bean dynamically selects the RSA key based on the current tenant:
-
-```mermaid
-flowchart LR
-    JWTRequest["JWKS or Token Signing"] --> TenantId["TenantContext.getTenantId()"]
-    TenantId --> KeyService["TenantKeyService.getOrCreateActiveKey"]
-    KeyService --> RSAKey["Tenant RSAKey"]
-    RSAKey --> JWKSet["JWKSet Returned"]
-```
-
-Important properties:
-
-- Each tenant has its own active RSA key
-- Key ID (`kid`) is logged and exposed via JWKS
-- If tenant ID is missing, the request fails
-
-This guarantees:
-
-- Cryptographic tenant isolation
-- Independent key rotation per tenant
-- Safe multi-issuer JWT validation
-
----
-
-## JWT Token Customization
-
-The module injects tenant and user metadata into access tokens.
-
-### Custom Claims Added
-
-When issuing an `access_token`, the following claims are added:
-
-- `tenant_id`
-- `userId`
-- `roles`
-
-Role logic:
-
-- If user has `OWNER`, `ADMIN` is implicitly included
-- Roles are emitted as string names
-
-```mermaid
-flowchart TD
-    Auth["Authenticated Principal"] --> Lookup["UserService.findActiveByEmailAndTenant"]
-    Lookup --> Claims["Add Claims to JWT"]
-    Claims --> Token["Signed Access Token"]
-```
-
-Additionally:
-
-- Refresh token grants update `lastLogin`
-- Claims are derived from tenant-scoped `AuthUser`
-
-This ensures that downstream services (Gateway, API Service) can enforce tenant and role-based authorization purely from JWT claims.
-
----
-
-## User Authentication Integration
-
-### UserDetailsService
-
-Provides tenant-aware authentication:
-
-- Looks up users by email + tenant ID
-- Converts roles into `ROLE_*` authorities
-- Uses BCrypt for password hashing
-
-### AuthenticationManager
-
-Uses a `DaoAuthenticationProvider` wired with:
-
-- Tenant-aware `UserDetailsService`
-- BCrypt `PasswordEncoder`
-
-This enables:
-
-- Form login
-- Programmatic authentication
-- Password-based fallback for SSO users
-
----
-
-## Default Security Configuration
-
-### SecurityConfig
-
-Component:
-- `openframe-oss-lib.openframe-authorization-service-core.src.main.java.com.openframe.authz.config.SecurityConfig.SecurityConfig`
-
-This filter chain handles **non-Authorization Server endpoints** (Order 2).
-
-Responsibilities:
-
-- Form login configuration
-- OAuth2 login configuration
-- SSO failure handling
-- Auto-provisioning of users
-- Microsoft multi-tenant issuer validation
-
----
-
-### OAuth2 Login and SSO Integration
-
-Key integrations:
-
-- `SsoAuthorizationRequestResolver`
-- `AuthSuccessHandler`
-- Custom `JwtDecoderFactory`
-- Auto-provisioning logic
-
-```mermaid
-flowchart TD
-    User["User Clicks SSO"] --> OAuthLogin["oauth2Login()"]
-    OAuthLogin --> Resolver["SsoAuthorizationRequestResolver"]
-    Resolver --> Provider["External IdP"]
-    Provider --> Callback["OIDC Callback"]
-    Callback --> OidcService["Custom OidcUserService"]
-    OidcService --> AutoProvision["Auto Provision If Needed"]
-    AutoProvision --> Success["AuthSuccessHandler"]
-```
-
----
-
-## Auto-Provisioning Logic
-
-When a user logs in via OIDC:
-
-1. Resolve tenant from context
-2. Extract email and provider
-3. Load per-tenant SSO configuration
-4. Validate allowed domains
-5. Register or reactivate user if necessary
-6. Assign ADMIN role during SSO registration
-
-Safeguards:
-
-- Does not block login if provisioning fails
-- Honors global domain policy fallback
-- Avoids duplicate image sync
-
-This tightly integrates identity provider flows with OpenFrame's tenant-based user model.
-
----
-
-## Dynamic Client Registration
-
-### DynamicClientRegistrationRepository
-
-Component:
-- `openframe-oss-lib.openframe-authorization-service-core.src.main.java.com.openframe.authz.config.DynamicClientRegistrationRepository.DynamicClientRegistrationRepository`
-
-Implements `ClientRegistrationRepository` dynamically per tenant.
-
-Behavior:
-
-- Resolves tenant ID from:
-  - `TenantContext`
-  - HTTP session
-- Delegates to `DynamicClientRegistrationService`
-- Returns null if tenant is unresolved
-
-```mermaid
-flowchart LR
-    OAuthFlow["OAuth2 Login Request"] --> Repo["DynamicClientRegistrationRepository"]
-    Repo --> TenantCtx["TenantContext"]
-    TenantCtx --> DynamicSvc["DynamicClientRegistrationService"]
-    DynamicSvc --> ClientReg["ClientRegistration"]
-```
-
-This allows:
-
-- Per-tenant SSO provider configuration
-- Dynamic Google and Microsoft client resolution
-- Runtime onboarding of new tenants
-
----
-
-## Multi-Issuer and Gateway Compatibility
-
-The Authorization Service Core Server And Tenant module is designed for compatibility with the Gateway Service:
-
-- Each tenant may have its own issuer URL
-- JWT includes `tenant_id`
-- JWKS endpoint is tenant-aware
-- Gateway validates JWT using issuer-specific configuration
-
-This ensures horizontal scalability and safe routing across multiple tenants.
-
----
-
-## Security Characteristics
-
-- Per-tenant RSA key pairs
-- BCrypt password hashing
-- OIDC ID token validation
-- Microsoft multi-tenant issuer pattern validation
-- Session invalidation on unsafe tenant switch
-- Strict JWT claim injection
-- CSRF disabled for OAuth endpoints only
-
----
-
-## Request Lifecycle Summary
-
-```mermaid
-flowchart TD
-    Step1["Incoming Request"] --> Step2["TenantContextFilter Resolves Tenant"]
-    Step2 --> Step3{{"OAuth2 Endpoint?"}}
-    Step3 -->|"Yes"| Step4["AuthorizationServerConfig"]
-    Step3 -->|"No"| Step5["SecurityConfig"]
-    Step4 --> Step6["JWT Issued with Tenant Claims"]
-    Step5 --> Step7["Authenticated Session or SSO"]
-    Step6 --> EndNode["Response"]
-    Step7 --> EndNode
-```
-
----
-
-## How This Module Fits Into OpenFrame
-
-Within the broader OpenFrame architecture:
-
-- It is the authoritative identity provider.
-- It enforces tenant boundaries at authentication time.
-- It supplies signed JWTs used by:
-  - API Service Core
-  - Gateway Service Core
-  - External API Service Core
-- It integrates with Mongo repositories for user and OAuth persistence.
-
-Without this module, the multi-tenant trust boundary would not exist.
-
----
-
-## Conclusion
-
-The **Authorization Service Core Server And Tenant** module provides:
-
-- Multi-tenant OAuth2 Authorization Server
-- Tenant-aware JWT issuance
-- Per-tenant RSA key management
-- Dynamic client registration
-- SSO auto-provisioning
-- Strict tenant isolation guarantees
-
-It forms the cryptographic and identity backbone of OpenFrame, enabling secure, scalable, and tenant-isolated authentication across the entire platform.
\ No newline at end of file
diff --git a/docs/reference/architecture/authorization-service-core-sso-flow-and-utils/authorization-service-core-sso-flow-and-utils.md b/docs/reference/architecture/authorization-service-core-sso-flow-and-utils/authorization-service-core-sso-flow-and-utils.md
deleted file mode 100644
index e5c3b06e0..000000000
--- a/docs/reference/architecture/authorization-service-core-sso-flow-and-utils/authorization-service-core-sso-flow-and-utils.md
+++ /dev/null
@@ -1,359 +0,0 @@
-# Authorization Service Core Sso Flow And Utils
-
-## Overview
-
-The **Authorization Service Core Sso Flow And Utils** module encapsulates the Single Sign-On (SSO) flow orchestration, post-authentication handling, provider registration strategies, extensibility processors, and supporting web/security utilities for the OpenFrame Authorization Server.
-
-It sits on top of the core authorization server and tenant infrastructure and focuses on:
-
-- Handling OAuth2/OIDC authentication success
-- Driving SSO-based tenant registration and invitation flows
-- Dynamically configuring Google and Microsoft OIDC providers
-- Providing extensibility hooks for registration and user lifecycle events
-- Offering security and redirect utilities for clean session handling
-
-This module is a critical bridge between:
-
-- The **Authorization Server Core** (multi-tenant, OAuth2, client registration)
-- The **User and Tenant Services**
-- External OIDC providers (Google, Microsoft)
-
----
-
-## Architectural Context
-
-At a high level, the module enhances the OAuth2 login pipeline and injects SSO-specific behaviors.
-
-```mermaid
-flowchart TD
-    Browser["Browser"] -->|"OAuth2 Login"| AuthServer["Authorization Server"]
-    AuthServer -->|"Authentication Success"| AuthSuccessHandler["Auth Success Handler"]
-
-    AuthSuccessHandler -->|"Delegate"| SsoFlowHandlers["SSO Flow Handlers"]
-    AuthSuccessHandler -->|"Update User"| UserService["User Service"]
-
-    SsoFlowHandlers --> InviteHandler["Invite SSO Handler"]
-    SsoFlowHandlers --> TenantRegHandler["Tenant Registration SSO Handler"]
-
-    InviteHandler --> InvitationService["Invitation Registration Service"]
-    TenantRegHandler --> TenantRegService["Tenant Registration Service"]
-
-    AuthSuccessHandler --> RedirectsUtil["Redirect Utilities"]
-    AuthSuccessHandler --> AuthStateUtils["Auth State Utilities"]
-```
-
-The flow can be summarized as:
-
-1. User authenticates via OAuth2 (Google or Microsoft).
-2. `AuthSuccessHandler` updates user metadata and delegates to SSO flow handlers.
-3. Based on SSO cookies, the appropriate handler executes:
-   - Invitation-based onboarding
-   - Tenant self-registration
-4. Registration services create or update tenant/user entities.
-5. Cookies are cleared and user is redirected to the correct tenant context.
-
----
-
-## Authentication Success Orchestration
-
-### AuthSuccessHandler
-
-**Responsibility:** Central post-authentication entry point.
-
-Key behaviors:
-
-- Extracts tenant ID from `TenantContext`
-- Resolves email from `Authentication` (OIDC or standard login)
-- Updates `lastLogin` via `UserService`
-- Optionally marks email as verified for trusted providers
-- Delegates to SSO tenant registration success handler
-
-### Email Resolution Strategy
-
-Email resolution is provider-aware and handled via `OidcUserUtils`:
-
-```mermaid
-flowchart TD
-    OidcUser["OIDC User Claims"] --> Email["email"]
-    OidcUser --> Preferred["preferred_username"]
-    OidcUser --> Upn["upn"]
-    OidcUser --> Unique["unique_name"]
-
-    Email --> Resolved["Resolved Email"]
-    Preferred --> Resolved
-    Upn --> Resolved
-    Unique --> Resolved
-```
-
-Order of precedence:
-
-1. `email`
-2. `preferred_username`
-3. `upn`
-4. `unique_name`
-
-This ensures compatibility with Google and Azure AD organizational accounts.
-
----
-
-## SSO Flow Handling
-
-The module supports two primary SSO-driven flows using cookie-based state management.
-
-### SsoRegistrationConstants
-
-Defines cookie names and special onboarding tenant identifiers:
-
-- `of_sso_reg` → Tenant self-registration flow
-- `of_sso_invite` → Invitation-based onboarding
-- `sso-onboarding` → Temporary tenant context
-
----
-
-### InviteSsoHandler
-
-**Use Case:** User accepts an invitation and authenticates via SSO.
-
-Flow:
-
-```mermaid
-flowchart TD
-    Cookie["Invite Cookie"] --> Decode["Decode Invite Payload"]
-    Oidc["OIDC User"] --> Extract["Extract Names and Email"]
-    Decode --> BuildReq["Build InvitationRegistrationRequest"]
-    Extract --> BuildReq
-    BuildReq --> Register["InvitationRegistrationService.registerByInvitation"]
-    Register --> Redirect["Clear Cookie and Redirect"]
-```
-
-Key characteristics:
-
-- Validates SSO session via `SsoCookieCodec`
-- Generates a random password (UUID-based)
-- Uses provider picture (if available)
-- Optionally switches tenant
-- Clears SSO cookie while preserving OAuth session continuity
-
----
-
-### TenantRegSsoHandler
-
-**Use Case:** New tenant self-registration via SSO.
-
-Flow:
-
-```mermaid
-flowchart TD
-    Cookie["Registration Cookie"] --> Decode["Decode Tenant Payload"]
-    Oidc["OIDC User"] --> Email["Resolve Email"]
-    Decode --> Validate["Validate Tenant Name and Domain"]
-    Email --> BuildReq["Build TenantRegistrationRequest"]
-    Validate --> BuildReq
-    BuildReq --> Register["TenantRegistrationService.registerTenant"]
-    Register --> Redirect["Clear Cookie and Redirect"]
-```
-
-Key behaviors:
-
-- Requires tenant name and domain
-- Normalizes domain to lowercase
-- Generates secure random password
-- Associates authenticated email with tenant
-
----
-
-## OIDC Provider Strategies
-
-The module uses a strategy pattern for dynamic client registration.
-
-### GoogleClientRegistrationStrategy
-
-- Provider ID: `google`
-- Uses `GoogleSSOProperties`
-- Extends base OIDC registration strategy
-- Integrates with `SSOConfigService`
-
-### MicrosoftClientRegistrationStrategy
-
-- Provider ID: `microsoft`
-- Uses `MicrosoftSSOProperties`
-- Supports Azure AD OIDC configuration
-
-```mermaid
-flowchart LR
-    SSOConfigService["SSO Config Service"] --> GoogleStrategy["Google Client Registration Strategy"]
-    SSOConfigService --> MicrosoftStrategy["Microsoft Client Registration Strategy"]
-
-    GoogleStrategy --> GoogleProps["Google SSO Properties"]
-    MicrosoftStrategy --> MicrosoftProps["Microsoft SSO Properties"]
-```
-
-This design enables:
-
-- Per-tenant provider configuration
-- Default provider fallbacks
-- Clean extension for additional IdPs
-
----
-
-## Default Provider Configuration
-
-### GoogleDefaultProviderConfig
-### MicrosoftDefaultProviderConfig
-
-Provide default client ID and secret values when no tenant-specific configuration exists.
-
-This ensures:
-
-- Zero-config local development
-- Sensible fallback for multi-tenant environments
-
----
-
-## Domain Policy Lookup
-
-### NoopGlobalDomainPolicyLookup
-
-Fallback implementation for domain-based auto-provisioning.
-
-- Returns empty result by default
-- Activated only if no custom `GlobalDomainPolicyLookup` bean exists
-- Enables domain-to-tenant auto-binding customization
-
-This is a key extensibility point for enterprise auto-provisioning.
-
----
-
-## Registration and User Lifecycle Processors
-
-The module defines multiple processor extension points with default no-op implementations.
-
-### DefaultRegistrationProcessor
-
-Hooks:
-
-- `preProcessTenantRegistration`
-- `postProcessTenantRegistration`
-- `postProcessInvitationRegistration`
-- `postProcessAutoProvision`
-
-Allows custom logic such as:
-
-- Audit logging
-- License provisioning
-- External system synchronization
-
-### DefaultUserDeactivationProcessor
-
-Triggered after user deactivation.
-
-### DefaultUserEmailVerifiedProcessor
-
-Triggered when user email is marked verified.
-
-These processors follow a conditional bean pattern:
-
-- If no custom bean exists → default implementation is used
-- If custom bean exists → default is ignored
-
-This enables safe override without modifying core logic.
-
----
-
-## Security and Web Utilities
-
-### OidcUserUtils
-
-Provides claim resolution helpers:
-
-- Email resolution across providers
-- Picture URL extraction
-- Safe string claim parsing
-
-Ensures provider inconsistencies do not leak into business logic.
-
----
-
-### ResetTokenUtil
-
-Generates secure password reset tokens:
-
-- 32 random bytes
-- URL-safe Base64 encoding without padding
-- Uses `SecureRandom`
-
-This provides cryptographically strong reset tokens.
-
----
-
-### AuthStateUtils
-
-Handles authentication state cleanup:
-
-- Invalidates session
-- Clears `JSESSIONID`
-- Removes cookies at root and context path
-
-Used during logout or auth reset scenarios.
-
----
-
-### Redirects
-
-Utility for safe HTTP redirects:
-
-- 302 Found
-- 303 See Other
-- Root-based redirect support
-- Context-aware URL construction
-
-Ensures:
-
-- Clean redirect semantics
-- No manual URL concatenation
-- Context-path safety
-
----
-
-## Complete SSO Registration Sequence
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant AuthServer as "Authorization Server"
-    participant Success as "Auth Success Handler"
-    participant Flow as "SSO Flow Handler"
-    participant Service as "Registration Service"
-
-    Browser->>AuthServer: OAuth2 Login (Google or Microsoft)
-    AuthServer->>Success: onAuthenticationSuccess
-    Success->>Success: Update lastLogin
-    Success->>Flow: Delegate to flow handler
-    Flow->>Service: Register user or tenant
-    Service->>Flow: Return tenant context
-    Flow->>Browser: Redirect to target tenant
-```
-
----
-
-## Key Design Principles
-
-1. **Separation of concerns** – Authentication success handling is isolated from registration logic.
-2. **Cookie-driven flow state** – SSO flow intent is persisted safely across OAuth redirects.
-3. **Strategy pattern for IdPs** – Enables clean addition of new providers.
-4. **Extensibility via processors** – Business-specific logic can be injected without modifying core.
-5. **Provider-agnostic claim resolution** – Normalizes Google and Microsoft differences.
-6. **Secure defaults** – Strong random token generation and strict cookie clearing.
-
----
-
-## Summary
-
-The **Authorization Service Core Sso Flow And Utils** module is the orchestration layer that transforms raw OAuth2/OIDC authentication into:
-
-- Tenant-aware onboarding
-- Invitation-driven account activation
-- Secure and extensible registration flows
-- Clean post-authentication lifecycle updates
-
-It acts as the glue between authentication, tenant management, and user lifecycle processing, ensuring a secure, extensible, and multi-tenant-ready SSO experience across OpenFrame.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-kafka-configuration-and-retry/data-kafka-configuration-and-retry.md b/docs/reference/architecture/data-kafka-configuration-and-retry/data-kafka-configuration-and-retry.md
deleted file mode 100644
index 195ade979..000000000
--- a/docs/reference/architecture/data-kafka-configuration-and-retry/data-kafka-configuration-and-retry.md
+++ /dev/null
@@ -1,380 +0,0 @@
-# Data Kafka Configuration And Retry
-
-## Overview
-
-The **Data Kafka Configuration And Retry** module provides the foundational Kafka infrastructure for the OpenFrame OSS ecosystem. It encapsulates:
-
-- Multi-tenant Kafka configuration
-- Custom Spring Boot auto-configuration for Kafka
-- Topic provisioning and management
-- Standardized Debezium message modeling
-- Structured recovery handling for failed Kafka operations
-
-This module is designed to be reusable across services such as Stream Service, Management Service, and other components that rely on event-driven communication.
-
-It replaces default Spring Boot Kafka auto-configuration with a controlled, tenant-aware setup tailored for OpenFrame OSS.
-
----
-
-## Architectural Role in the Platform
-
-Within the overall system, this module acts as the **Kafka infrastructure layer** used by event-driven services.
-
-```mermaid
-flowchart LR
-    AppService[Application Service] --> KafkaInfra[Data Kafka Configuration And Retry]
-    KafkaInfra --> KafkaCluster[Kafka Cluster]
-    KafkaCluster --> StreamService[Stream Service Core]
-    KafkaCluster --> OtherConsumers[Other Consumers]
-```
-
-### Responsibilities
-
-1. Provide tenant-aware Kafka configuration
-2. Standardize producer and consumer factories
-3. Enable dynamic topic auto-creation
-4. Provide a canonical Debezium message wrapper
-5. Handle Kafka publishing failures via recovery logic
-
----
-
-## Module Components
-
-The module consists of the following core components:
-
-| Component | Responsibility |
-|------------|----------------|
-| `KafkaTopicProperties` | Defines topic configuration and auto-creation behavior |
-| `OssKafkaConfig` | Enables Kafka and disables default auto-configuration |
-| `OssTenantKafkaAutoConfiguration` | Main bean wiring for producers, consumers, listeners, and admin |
-| `OssTenantKafkaProperties` | Tenant-scoped Kafka configuration properties |
-| `KafkaHeader` | Standardized Kafka header constants |
-| `DebeziumMessage` | Generic wrapper for Debezium CDC events |
-| `KafkaRecoveryHandlerImpl` | Structured recovery handler for failed Kafka publishes |
-
----
-
-# Configuration Architecture
-
-## Custom Kafka Bootstrapping
-
-The module disables Spring Boot's default `KafkaAutoConfiguration` and replaces it with a controlled configuration:
-
-```mermaid
-flowchart TD
-    SpringBoot[Spring Boot] --> DefaultKafkaAutoConfig[KafkaAutoConfiguration]
-    DefaultKafkaAutoConfig -->|Excluded| OssKafkaConfig
-    OssKafkaConfig --> OssTenantKafkaAutoConfiguration
-    OssTenantKafkaAutoConfiguration --> ProducerFactory
-    OssTenantKafkaAutoConfiguration --> ConsumerFactory
-    OssTenantKafkaAutoConfiguration --> KafkaTemplate
-    OssTenantKafkaAutoConfiguration --> KafkaAdmin
-```
-
-### OssKafkaConfig
-
-- Enables `@EnableKafka`
-- Excludes `KafkaAutoConfiguration`
-- Ensures only OSS tenant configuration is active
-
-This prevents accidental configuration conflicts and guarantees predictable Kafka behavior.
-
----
-
-## Tenant-Aware Kafka Properties
-
-### OssTenantKafkaProperties
-
-Bound to:
-
-```text
-spring.oss-tenant
-```
-
-This class wraps Spring's `KafkaProperties`, allowing full reuse of:
-
-- Producer properties
-- Consumer properties
-- Listener configuration
-- Template configuration
-- Admin configuration
-
-### Enabling Kafka
-
-Kafka is conditionally activated using:
-
-```text
-spring.oss-tenant.enabled=true
-```
-
-If disabled, no Kafka beans are registered.
-
----
-
-# Topic Management
-
-## KafkaTopicProperties
-
-Bound to:
-
-```text
-openframe.oss-tenant.kafka.topics
-```
-
-It supports:
-
-- Automatic topic creation
-- Partition configuration
-- Replication factor configuration
-
-### Structure
-
-```text
-openframe:
-  oss-tenant:
-    kafka:
-      topics:
-        inbound:
-          device-events:
-            name: device.events
-            partitions: 3
-            replication-factor: 2
-```
-
-### Auto-Creation Flow
-
-```mermaid
-flowchart TD
-    ConfigProps[KafkaTopicProperties] --> AdminBean[KafkaAdmin]
-    AdminBean --> TopicBuilder
-    TopicBuilder --> NewTopic
-    NewTopic --> KafkaCluster
-```
-
-If topic auto-creation is enabled:
-
-- `KafkaAdmin` registers `NewTopic` beans
-- Topics are created on startup
-- Logging confirms partition and replica configuration
-
----
-
-# Producer and Consumer Infrastructure
-
-## Producer Side
-
-### ProducerFactory
-
-- Key serializer: `StringSerializer`
-- Value serializer: `JsonSerializer`
-- Backed by Spring `KafkaProperties`
-
-### KafkaTemplate
-
-- Default topic configurable
-- JSON payload support
-- Used by higher-level producers
-
-### OssTenantKafkaProducer
-
-Created as a bean to provide a simplified abstraction over `KafkaTemplate`.
-
----
-
-## Consumer Side
-
-### ConsumerFactory
-
-- Key deserializer: `StringDeserializer`
-- Value deserializer: `JsonDeserializer`
-- Uses Spring-configured properties
-
-### Listener Container Factory
-
-Configurable:
-
-- Concurrency
-- AckMode (defaults to RECORD)
-- Poll timeout
-- Idle event interval
-- Container logging
-
-```mermaid
-flowchart LR
-    KafkaCluster --> ListenerContainer
-    ListenerContainer --> ConsumerFactory
-    ConsumerFactory --> JsonDeserializer
-    ListenerContainer --> AckMode[RECORD Ack Mode]
-```
-
-The default acknowledgment mode ensures per-record reliability if not explicitly configured.
-
----
-
-# Debezium Event Modeling
-
-## DebeziumMessage
-
-The module defines a generic wrapper for Debezium Change Data Capture events.
-
-### Structure
-
-```mermaid
-flowchart TD
-    DebeziumMessage --> Payload
-    Payload --> Before[Before State]
-    Payload --> After[After State]
-    Payload --> Source
-    Payload --> Operation
-    Payload --> Timestamp
-    Source --> Database
-    Source --> Table
-    Source --> Connector
-```
-
-### Supported Fields
-
-- `before` – state before change
-- `after` – state after change
-- `operation` – CDC operation (c, u, d)
-- `ts_ms` – event timestamp
-- `source` – connector metadata
-  - database
-  - table
-  - connector type
-  - schema
-  - snapshot flag
-
-This structure ensures:
-
-- Strong typing of CDC events
-- Cross-service consistency
-- Cleaner event enrichment in downstream consumers
-
----
-
-# Kafka Headers Standardization
-
-## KafkaHeader
-
-Defines common header keys used across producers and consumers.
-
-Currently:
-
-```text
-message-type
-```
-
-This enables:
-
-- Event routing
-- Polymorphic deserialization
-- Handler selection in downstream services
-
----
-
-# Retry and Recovery Handling
-
-## KafkaRecoveryHandlerImpl
-
-This component implements structured error recovery for failed Kafka publish operations.
-
-### Behavior
-
-When publishing fails:
-
-- The exception is captured
-- Topic and key are logged
-- Error class and message are recorded
-- Payload summary is logged
-- Full stacktrace is attached
-
-```mermaid
-flowchart TD
-    Producer --> KafkaCluster
-    KafkaCluster -->|Failure| RecoveryHandler
-    RecoveryHandler --> StructuredLog
-```
-
-### Logging Strategy
-
-The recovery handler logs:
-
-- `topic`
-- `key`
-- `errorClass`
-- `errorMsg`
-- `payload`
-
-This ensures observability without introducing immediate dead-letter queue complexity.
-
-It can later be extended to:
-
-- Publish to retry topics
-- Send to dead-letter queues
-- Trigger alerting systems
-
----
-
-# Integration with Other Modules
-
-The **Data Kafka Configuration And Retry** module serves as a foundational infrastructure layer for:
-
-- Stream processing services consuming Debezium events
-- Management services publishing operational events
-- Notification pipelines
-- Cross-service event propagation
-
-It does not implement business logic itself. Instead, it standardizes:
-
-- How Kafka is configured
-- How topics are created
-- How messages are structured
-- How failures are handled
-
----
-
-# Design Principles
-
-### 1. Tenant Isolation
-Kafka configuration is explicitly scoped under:
-
-```text
-spring.oss-tenant
-```
-
-This prevents accidental mixing with default Kafka configurations.
-
-### 2. Explicit Auto-Configuration
-Default Spring Kafka auto-configuration is excluded to avoid:
-
-- Bean conflicts
-- Hidden configuration overrides
-- Environment-specific ambiguity
-
-### 3. Strong CDC Modeling
-Debezium events are modeled as typed structures instead of raw maps.
-
-### 4. Safe Defaults
-- Ack mode defaults to RECORD
-- Admin auto-creation enabled unless disabled
-- Kafka enabled by default but explicitly configurable
-
-### 5. Observability First
-Failure handling prioritizes structured logging for operational visibility.
-
----
-
-# Summary
-
-The **Data Kafka Configuration And Retry** module provides a controlled, tenant-aware Kafka foundation for the OpenFrame OSS platform.
-
-It ensures:
-
-- Deterministic Kafka bootstrapping
-- Configurable topic lifecycle management
-- Structured Debezium message handling
-- Safe producer/consumer defaults
-- Clear recovery and error logging
-
-By centralizing Kafka configuration and retry behavior, the module guarantees consistency across all services that rely on event-driven communication.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-mongo-base-repositories/data-mongo-base-repositories.md b/docs/reference/architecture/data-mongo-base-repositories/data-mongo-base-repositories.md
deleted file mode 100644
index 85d255373..000000000
--- a/docs/reference/architecture/data-mongo-base-repositories/data-mongo-base-repositories.md
+++ /dev/null
@@ -1,256 +0,0 @@
-# Data Mongo Base Repositories
-
-## Overview
-
-The **Data Mongo Base Repositories** module defines technology-agnostic repository contracts for core MongoDB-backed domain entities in the OpenFrame platform. These base interfaces act as a unifying abstraction layer between:
-
-- The **domain model** (Mongo documents such as User, Tenant, API Key, Integrated Tool)
-- The **blocking (imperative)** repository implementations
-- The **reactive (Project Reactor)** repository implementations
-
-By introducing generic wrapper types (`T`, `B`, `L`, `ID`), this module ensures that the same repository contract can be reused across both blocking and reactive stacks without duplicating business semantics.
-
----
-
-## Architectural Role in the Data Layer
-
-Within the broader persistence architecture, this module sits between the domain documents and concrete repository implementations.
-
-```mermaid
-flowchart TD
-    Domain["Mongo Domain Model"] --> BaseRepo["Data Mongo Base Repositories"]
-    BaseRepo --> Blocking["Blocking Repositories"]
-    BaseRepo --> Reactive["Reactive Repositories"]
-
-    Blocking --> Services["Application Services"]
-    Reactive --> Services
-```
-
-### Responsibilities
-
-- Define **common repository operations** for core entities
-- Provide **generic signatures** adaptable to Optional / List or Mono / Flux
-- Ensure **consistent query semantics** across execution models
-- Reduce duplication between blocking and reactive repository layers
-
----
-
-## Design Philosophy
-
-Each base repository follows a consistent pattern:
-
-```text
-public interface BaseXRepository<T, B, L?, ID> {
-    T findBy...(...);
-    B existsBy...(...);
-    L findAllBy...(...);
-}
-```
-
-Where:
-
-- `T` → Wrapper for single-result queries
-  - Blocking: `Optional<Entity>`
-  - Reactive: `Mono<Entity>`
-- `B` → Wrapper for boolean responses
-  - Blocking: `boolean`
-  - Reactive: `Mono<Boolean>`
-- `L` → Wrapper for multi-result queries (if applicable)
-  - Blocking: `List<Entity>`
-  - Reactive: `Flux<Entity>`
-- `ID` → Identifier type (typically `String`)
-
-This allows downstream modules to:
-
-- Implement blocking repositories using Spring Data Mongo
-- Implement reactive repositories using Spring Data Reactive Mongo
-- Preserve identical method semantics across implementations
-
----
-
-# Core Interfaces
-
-## 1. BaseApiKeyRepository
-
-**Purpose:** Defines common API key query operations.
-
-### Key Methods
-
-- `findByIdAndUserId(String keyId, String userId)`
-- `findByUserId(String userId)`
-- `findExpiredKeys(Instant currentTime)`
-
-### Architectural Context
-
-```mermaid
-flowchart LR
-    ApiKey["API Key Document"] --> ApiKeyRepo["BaseApiKeyRepository"]
-    ApiKeyRepo --> UserScope["User-Scoped Queries"]
-    ApiKeyRepo --> Expiry["Expiration Queries"]
-```
-
-### Design Considerations
-
-- API keys are **user-scoped**.
-- Expiration handling is centralized via `findExpiredKeys`.
-- Enables scheduled cleanup and security enforcement logic.
-
-This repository is critical for authentication flows and API access management.
-
----
-
-## 2. BaseTenantRepository
-
-**Purpose:** Defines tenant lookup and domain validation operations.
-
-### Key Methods
-
-- `findByDomain(String domain)`
-- `existsByDomain(String domain)`
-
-### Architectural Context
-
-```mermaid
-flowchart TD
-    Tenant["Tenant Document"] --> TenantRepo["BaseTenantRepository"]
-    TenantRepo --> DomainLookup["Domain-Based Resolution"]
-    DomainLookup --> AuthLayer["Authorization & SSO"]
-```
-
-### Design Considerations
-
-- Domain-based lookup enables **multi-tenant resolution**.
-- Used heavily in authentication and tenant-aware request routing.
-- `existsByDomain` supports validation during registration and onboarding flows.
-
----
-
-## 3. BaseIntegratedToolRepository
-
-**Purpose:** Provides lookup functionality for integrated tools.
-
-### Key Methods
-
-- `findByType(String type)`
-
-### Architectural Context
-
-```mermaid
-flowchart LR
-    Tool["Integrated Tool Document"] --> ToolRepo["BaseIntegratedToolRepository"]
-    ToolRepo --> TypeLookup["Type-Based Resolution"]
-    TypeLookup --> Gateway["Gateway & Integration Layer"]
-```
-
-### Design Considerations
-
-- Tool resolution is based on logical tool type.
-- Enables integration routing and upstream configuration.
-- Keeps tool lookup semantics consistent across sync and reactive stacks.
-
----
-
-## 4. BaseUserRepository
-
-**Purpose:** Defines foundational user lookup and existence checks.
-
-### Key Methods
-
-- `findByEmail(String email)`
-- `existsByEmail(String email)`
-- `existsByEmailAndStatus(String email, UserStatus status)`
-
-### Architectural Context
-
-```mermaid
-flowchart TD
-    UserDoc["User Document"] --> UserRepo["BaseUserRepository"]
-    UserRepo --> EmailLookup["Email-Based Lookup"]
-    UserRepo --> StatusCheck["Status Validation"]
-    StatusCheck --> Security["Authentication & Access Control"]
-```
-
-### Design Considerations
-
-- Email is the primary identity attribute.
-- Status validation supports enforcement of states such as ACTIVE or DISABLED.
-- Provides a consistent existence-check abstraction across blocking and reactive implementations.
-
----
-
-# Cross-Cutting Patterns
-
-## 1. Technology Agnostic Contracts
-
-All repositories avoid direct dependencies on:
-
-- Spring Data interfaces
-- Reactive types
-- Mongo-specific annotations
-
-Instead, they rely on generic wrapper types, allowing different execution models without rewriting business contracts.
-
----
-
-## 2. Multi-Tenancy Alignment
-
-The BaseTenantRepository and BaseUserRepository are foundational for tenant-aware identity resolution.
-
-```mermaid
-flowchart TD
-    Request["Incoming Request"] --> DomainExtract["Extract Domain"]
-    DomainExtract --> TenantRepo["BaseTenantRepository"]
-    TenantRepo --> TenantResolved["Tenant Context Established"]
-    TenantResolved --> UserRepo["BaseUserRepository"]
-    UserRepo --> AuthResult["User Validated"]
-```
-
-This separation ensures that:
-
-- Tenant resolution is independent from authentication logic.
-- User validation remains consistent regardless of execution model.
-
----
-
-## 3. Expiration and Lifecycle Handling
-
-Repositories such as BaseApiKeyRepository expose lifecycle-oriented queries (e.g., expired keys). This supports:
-
-- Scheduled cleanup tasks
-- Security enforcement policies
-- Token rotation and revocation strategies
-
----
-
-# Interaction with Other Data Modules
-
-Although this module only defines interfaces, it enables:
-
-- Concrete Mongo repository implementations in synchronization modules.
-- Reactive repository implementations in reactive data modules.
-- Service-layer logic in API and authorization services.
-
-```mermaid
-flowchart LR
-    Base["Data Mongo Base Repositories"] --> SyncImpl["Mongo Sync Implementations"]
-    Base --> ReactiveImpl["Mongo Reactive Implementations"]
-    SyncImpl --> ServiceLayer["Service Layer"]
-    ReactiveImpl --> ServiceLayer
-```
-
-The base repository layer ensures consistent semantics regardless of whether the application is running in blocking or reactive mode.
-
----
-
-# Summary
-
-The **Data Mongo Base Repositories** module is a foundational abstraction layer in the OpenFrame persistence architecture.
-
-It provides:
-
-- Unified repository contracts
-- Execution-model independence (blocking vs reactive)
-- Tenant-aware and security-aware query primitives
-- Reduced duplication across repository implementations
-
-By separating repository semantics from implementation details, this module ensures long-term maintainability, flexibility, and architectural consistency across the OpenFrame data stack.
diff --git a/docs/reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md b/docs/reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md
deleted file mode 100644
index 77d406e97..000000000
--- a/docs/reference/architecture/data-mongo-domain-model/data-mongo-domain-model.md
+++ /dev/null
@@ -1,471 +0,0 @@
-# Data Mongo Domain Model
-
-## Overview
-
-The **Data Mongo Domain Model** module defines the core MongoDB document structures used across the OpenFrame platform. It provides the canonical persistence model for:
-
-- Multi-tenant users and authentication
-- Organizations and tenancy boundaries
-- Devices and operational state
-- Tickets and PSA workflows
-- Events and audit trail
-- Notifications and read states
-- OAuth clients and tokens
-- Tag assignments
-
-This module acts as the **persistence foundation** for API services, authorization services, stream processing, gateway routing, and management components. All higher-level services depend on these document definitions for consistent storage and indexing strategies.
-
----
-
-## Architectural Role in the Platform
-
-The Data Mongo Domain Model sits at the base of the application stack and is shared by:
-
-- API Service Core (REST + GraphQL)
-- Authorization Service Core
-- Stream Service Core (Kafka consumers)
-- Management Service Core
-- External API Service Core
-- Gateway and Security components (indirectly via persistence)
-
-### High-Level Data Flow
-
-```mermaid
-flowchart TD
-    Gateway["Gateway Service"] --> ApiService["API Service Core"]
-    ApiService --> DomainModel["Data Mongo Domain Model"]
-    AuthService["Authorization Service"] --> DomainModel
-    StreamService["Stream Service"] --> DomainModel
-    ManagementService["Management Service"] --> DomainModel
-    ExternalApi["External API Service"] --> DomainModel
-
-    DomainModel --> MongoDB[("MongoDB")]
-```
-
-The module defines **document schemas and indexing strategies**, while repositories and services (in other modules) implement business logic on top of these models.
-
----
-
-## Core Domain Areas
-
-The domain model can be grouped into the following bounded contexts:
-
-1. Identity & Authentication
-2. Organization & Tenancy
-3. Device Management
-4. Ticketing (PSA)
-5. Events & Audit
-6. Notifications
-7. OAuth & Client Registration
-8. Tagging System
-
----
-
-# 1. Identity & Authentication
-
-## User
-
-**Collection:** `users`
-
-Represents an application user within a tenant.
-
-Key characteristics:
-
-- Indexed by `email`
-- Supports multiple roles (`UserRole`)
-- Email normalization (lowercased, trimmed)
-- Soft status control via `UserStatus`
-- Audit fields (`createdAt`, `updatedAt`)
-
-### Responsibilities
-
-- Technician identity
-- Role-based authorization support
-- Assignment target for tickets
-- Reporter reference for tickets
-
----
-
-## AuthUser
-
-Extends `User` for multi-tenant authorization server use.
-
-**Compound Index:** `(tenantId, email)` unique when tenant exists.
-
-Additional fields:
-
-- `tenantId` (multi-tenancy boundary)
-- `passwordHash`
-- `loginProvider` (LOCAL, GOOGLE, etc.)
-- `externalUserId`
-- `lastLogin`
-- `imageUrl` (cached profile picture)
-
-### Purpose
-
-- Used by the Authorization Service
-- Supports SSO and external identity providers
-- Maintains domain-based tenancy
-
-### Identity Model Diagram
-
-```mermaid
-classDiagram
-    class User {
-        id
-        email
-        firstName
-        lastName
-        roles
-        status
-        createdAt
-        updatedAt
-    }
-
-    class AuthUser {
-        tenantId
-        passwordHash
-        loginProvider
-        externalUserId
-        lastLogin
-        imageUrl
-    }
-
-    User <|-- AuthUser
-```
-
----
-
-# 2. Organization & Tenancy
-
-## Organization
-
-**Collection:** `organizations`
-
-Represents a company or tenant-scoped business entity.
-
-Key features:
-
-- Unique `organizationId`
-- Indexed `name`
-- `isDefault` flag
-- Business metadata (revenue, employees, contract dates)
-- Soft-delete via `OrganizationStatus` (ACTIVE, ARCHIVED, DELETED)
-- Contract validation logic
-
-### Important Design Decision
-
-Organizations are **never hard-deleted** to preserve device and ticket references. Instead:
-
-- `ARCHIVED` → hidden from standard queries
-- `DELETED` → soft-deleted but still referentially valid
-
----
-
-# 3. Device Management
-
-## Device
-
-**Collection:** `devices`
-
-Represents a managed endpoint.
-
-Key fields:
-
-- `machineId` (link to external Machine entity)
-- `serialNumber`, `model`, `osVersion`
-- `status` (ACTIVE, OFFLINE, MAINTENANCE)
-- `DeviceType`
-- `lastCheckin`
-- `DeviceConfiguration`
-- `DeviceHealth`
-
-### Device Lifecycle
-
-```mermaid
-stateDiagram-v2
-    [*] --> ACTIVE
-    ACTIVE --> OFFLINE
-    OFFLINE --> ACTIVE
-    ACTIVE --> MAINTENANCE
-    MAINTENANCE --> ACTIVE
-```
-
-Devices are heavily used by:
-
-- Ticketing
-- Stream event ingestion
-- Management schedulers
-- External API integrations
-
----
-
-# 4. Ticketing (PSA Domain)
-
-Ticketing is modeled as a primary entity with related collections.
-
-## Ticket
-
-**Collection:** `tickets`
-
-Primary PSA entity.
-
-Key design elements:
-
-- Unique `ticketNumber` (auto-increment per tenant)
-- Indexed status and assignment fields
-- Linked to:
-  - `deviceId`
-  - `organizationId`
-  - `assignedTo` (User)
-  - `reporterId`
-- Soft resolution via `resolvedAt`
-
-### Index Strategy
-
-Compound indexes support:
-
-- Status-based dashboards
-- Assignment filtering
-- Organization filtering
-- Device filtering
-
----
-
-## TicketNote
-
-**Collection:** `ticket_notes`
-
-Technician-only internal notes.
-
-- Indexed by `ticketId`
-- Sorted by `createdAt`
-- Editable (tracked via `updatedAt`)
-
----
-
-## TicketAttachment
-
-**Collection:** `ticket_attachments`
-
-Metadata-only storage.
-
-Files are stored externally (S3/MinIO), while this document stores:
-
-- `ticketId`
-- `fileName`
-- `contentType`
-- `fileSize`
-- `storagePath`
-
----
-
-### Ticket Aggregate Model
-
-```mermaid
-flowchart TD
-    Ticket["Ticket"] --> Note["TicketNote"]
-    Ticket --> Attachment["TicketAttachment"]
-    Ticket --> User["User (Assigned)"]
-    Ticket --> Device["Device"]
-    Ticket --> Org["Organization"]
-```
-
-Ticket owns metadata; attachments and notes are independent collections for scalability.
-
----
-
-# 5. Events & Audit
-
-## CoreEvent
-
-**Collection:** `events`
-
-Represents system-level or domain events.
-
-Fields:
-
-- `type`
-- `payload`
-- `timestamp`
-- `userId`
-- `status` (CREATED, PROCESSING, COMPLETED, FAILED)
-
-### Usage
-
-- Stream ingestion persistence
-- Audit logs
-- Async processing workflows
-
----
-
-# 6. Notifications
-
-## Notification
-
-**Collection:** `notifications`
-
-Represents a system notification.
-
-Fields:
-
-- `severity`
-- `title`
-- `description`
-- `createdAt`
-- `context`
-
----
-
-## NotificationReadState
-
-**Collection:** `notification_read_states`
-
-Tracks per-recipient state.
-
-Compound indexes ensure:
-
-- Unique (recipientId, recipientType, notificationId)
-- Fast unread queries by status
-- Filtering by category
-
-### Notification Model
-
-```mermaid
-flowchart TD
-    Notification["Notification"] --> ReadState["NotificationReadState"]
-    ReadState --> Recipient["User or Organization"]
-```
-
-Notifications are immutable; read state is tracked separately.
-
----
-
-# 7. OAuth & Client Registration
-
-## MongoRegisteredClient
-
-**Collection:** `oauth_registered_clients`
-
-Represents OAuth2 clients.
-
-Key features:
-
-- Unique `clientId`
-- Grant types
-- Redirect URIs
-- Scopes
-- PKCE support
-- Token TTL configuration
-
----
-
-## OAuthToken
-
-**Collection:** `oauth_tokens`
-
-Stores issued tokens.
-
-Fields:
-
-- `userId`
-- `accessToken`
-- `refreshToken`
-- Expiry timestamps
-- `clientId`
-- `scopes`
-
-Used by Authorization Service for token validation and revocation.
-
----
-
-# 8. Tagging System
-
-## TagAssignment
-
-**Collection:** `tag_assignments`
-
-Provides a unified tagging mechanism across entities.
-
-Unique compound index:
-
-- `(entityId, tagId, entityType)`
-
-Supports:
-
-- Label-style tags
-- Key-value tags with `values`
-- Timestamped tagging (`taggedAt`)
-- Attribution (`taggedBy`)
-
-### Cross-Entity Tag Model
-
-```mermaid
-flowchart LR
-    TagAssignment["TagAssignment"] --> Device
-    TagAssignment --> Ticket
-    TagAssignment --> Organization
-```
-
-This design avoids embedding tags inside each entity and enables consistent querying.
-
----
-
-# Multi-Tenancy Considerations
-
-Multi-tenancy is enforced through:
-
-- `tenantId` in AuthUser
-- Tenant-scoped repositories in other modules
-- Unique constraints within tenant boundaries
-- Per-tenant ticket numbering
-
-The domain model avoids hard coupling to tenant logic; enforcement is handled at repository and service layers.
-
----
-
-# Indexing Strategy Summary
-
-The module heavily leverages:
-
-- `@Indexed` for query acceleration
-- `@CompoundIndex` for dashboard queries
-- Unique constraints for integrity
-- Partial indexes for multi-tenant isolation
-
-This ensures:
-
-- Fast filtering
-- Scalable dashboard queries
-- Safe uniqueness guarantees
-- Reduced cross-tenant data leakage risk
-
----
-
-# Design Principles
-
-The Data Mongo Domain Model follows these principles:
-
-1. Document-per-aggregate boundary
-2. Soft deletes over hard deletes
-3. External storage for large binary data
-4. Event-driven compatibility
-5. Strong indexing strategy
-6. Multi-tenant safe uniqueness
-7. Clear separation of identity vs domain users
-
----
-
-# Conclusion
-
-The **Data Mongo Domain Model** is the foundational persistence layer of OpenFrame. It defines the canonical MongoDB structures that power:
-
-- Authentication and SSO
-- Tenant isolation
-- Device monitoring
-- Ticketing workflows
-- Notifications
-- Event processing
-- OAuth client management
-
-All higher-level services rely on these documents to provide consistent, scalable, and multi-tenant safe behavior across the platform.
diff --git a/docs/reference/architecture/data-mongo-query-filters/data-mongo-query-filters.md b/docs/reference/architecture/data-mongo-query-filters/data-mongo-query-filters.md
deleted file mode 100644
index da7d8fd77..000000000
--- a/docs/reference/architecture/data-mongo-query-filters/data-mongo-query-filters.md
+++ /dev/null
@@ -1,316 +0,0 @@
-# Data Mongo Query Filters
-
-## Overview
-
-The **Data Mongo Query Filters** module defines strongly-typed filter objects used to construct dynamic MongoDB queries across the OpenFrame platform. These filters act as the boundary between higher-level API input (REST and GraphQL) and low-level repository query execution.
-
-Rather than embedding query logic directly in controllers or services, this module provides composable filter models that:
-
-- Encapsulate domain-specific filtering criteria
-- Support time-based and enum-based constraints
-- Enable clean separation between API DTOs and MongoDB query construction
-- Promote consistency across sync and reactive repositories
-
-This module is part of the data layer and works closely with:
-
-- [Data Mongo Domain Model](../data-mongo-domain-model/data-mongo-domain-model.md)
-- [Data Mongo Base Repositories](../data-mongo-base-repositories/data-mongo-base-repositories.md)
-- [Data Mongo Sync Config and Custom Repositories](../data-mongo-sync-config-and-custom-repositories/data-mongo-sync-config-and-custom-repositories.md)
-- [Data Mongo Reactive Repositories](../data-mongo-reactive-repositories/data-mongo-reactive-repositories.md)
-
----
-
-## Architectural Role in the System
-
-The Data Mongo Query Filters module sits between API-level filter inputs and repository-level query execution.
-
-```mermaid
-flowchart LR
-    ApiLayer["API Layer\nREST + GraphQL"] --> FilterDTOs["Filter Input DTOs"]
-    FilterDTOs --> QueryFilters["Data Mongo Query Filters"]
-    QueryFilters --> CustomRepos["Custom Mongo Repositories"]
-    CustomRepos --> MongoDB[("MongoDB")]
-
-    DomainModel["Domain Documents"] --> CustomRepos
-```
-
-### Flow Explanation
-
-1. **API Layer** receives filter inputs (e.g., `TicketFilterInput`, `UserFilterInput`).
-2. These inputs are mapped into internal **Query Filter** objects defined in this module.
-3. Custom repositories interpret the filter object and build a MongoDB `Criteria` / query.
-4. Queries are executed against collections defined in the domain model.
-
-This separation ensures:
-
-- API contracts can evolve without tightly coupling to MongoDB internals.
-- Query construction remains centralized and testable.
-- Business services remain independent from persistence logic.
-
----
-
-## Design Principles
-
-### 1. Immutable, Builder-Based Construction
-
-All filter classes use Lombok annotations:
-
-- `@Data`
-- `@Builder`
-- `@NoArgsConstructor`
-- `@AllArgsConstructor`
-
-This enables safe, expressive creation:
-
-```java
-TicketQueryFilter filter = TicketQueryFilter.builder()
-    .statuses(List.of(TicketStatus.OPEN))
-    .organizationIds(List.of("org-1"))
-    .createdAtFrom(Instant.now().minus(30, ChronoUnit.DAYS))
-    .build();
-```
-
-### 2. Domain-Oriented Filtering
-
-Each filter aligns directly with a Mongo document type from the domain model:
-
-- Events → `EventQueryFilter`
-- Organizations → `OrganizationQueryFilter`
-- Tickets → `TicketQueryFilter`
-- Tools → `ToolQueryFilter`
-- Users → `UserQueryFilter`
-
-### 3. Null-Safe Optional Criteria
-
-All fields are optional. Repositories interpret `null` values as "no constraint".
-
-This allows flexible query composition without requiring multiple overloaded methods.
-
----
-
-# Filter Classes
-
-## EventQueryFilter
-
-**Component:**  
-`openframe-oss-lib.openframe-data-mongo-common.src.main.java.com.openframe.data.document.event.filter.EventQueryFilter.EventQueryFilter`
-
-### Purpose
-
-Encapsulates filtering logic for querying event documents.
-
-### Fields
-
-- `List<String> userIds` – Filter by user IDs
-- `List<String> eventTypes` – Restrict by event categories
-- `LocalDate startDate` – Inclusive lower bound
-- `LocalDate endDate` – Inclusive upper bound
-
-### Usage Context
-
-Used by event-related repositories to construct date-range and type-based queries.
-
-```mermaid
-flowchart TD
-    Filter["EventQueryFilter"] --> ByUser["userIds"]
-    Filter --> ByType["eventTypes"]
-    Filter --> ByStart["startDate"]
-    Filter --> ByEnd["endDate"]
-```
-
----
-
-## OrganizationQueryFilter
-
-**Component:**  
-`openframe-oss-lib.openframe-data-mongo-common.src.main.java.com.openframe.data.document.organization.filter.OrganizationQueryFilter.OrganizationQueryFilter`
-
-### Purpose
-
-Defines structured filtering for organization queries.
-
-### Fields
-
-- `String category`
-- `Integer minEmployees`
-- `Integer maxEmployees`
-- `Boolean hasActiveContract`
-- `String status`
-
-### Typical Query Logic
-
-Repositories may:
-
-- Apply numeric range constraints for employee size
-- Apply boolean checks for contract state
-- Apply equality matching on category and status
-
-```mermaid
-flowchart LR
-    OrgFilter["OrganizationQueryFilter"] --> SizeRange["Employee Range"]
-    OrgFilter --> Contract["Active Contract"]
-    OrgFilter --> Status["Organization Status"]
-```
-
----
-
-## TicketQueryFilter
-
-**Component:**  
-`openframe-oss-lib.openframe-data-mongo-common.src.main.java.com.openframe.data.document.ticket.filter.TicketQueryFilter.TicketQueryFilter`
-
-### Purpose
-
-Provides comprehensive filtering for ticket documents.
-
-### Fields
-
-- `List<TicketStatus> statuses`
-- `List<String> organizationIds`
-- `List<String> assigneeIds`
-- `List<String> labelIds`
-- `List<String> deviceIds`
-- `List<TicketCreationSource> creationSources`
-- `Instant createdAtFrom`
-- `Instant createdAtTo`
-
-### Capabilities
-
-- Multi-status filtering
-- Organization-scoped filtering
-- Assignee-based filtering
-- Label and device constraints
-- Creation source classification
-- Time-window filtering using `Instant`
-
-```mermaid
-flowchart TD
-    TicketFilter["TicketQueryFilter"] --> Statuses["TicketStatus List"]
-    TicketFilter --> OrgScope["Organization IDs"]
-    TicketFilter --> Assignees["Assignee IDs"]
-    TicketFilter --> Labels["Label IDs"]
-    TicketFilter --> Devices["Device IDs"]
-    TicketFilter --> Source["Creation Sources"]
-    TicketFilter --> TimeFrom["createdAtFrom"]
-    TicketFilter --> TimeTo["createdAtTo"]
-```
-
-This filter is commonly used in custom repository implementations for advanced aggregation and dashboard queries.
-
----
-
-## ToolQueryFilter
-
-**Component:**  
-`openframe-oss-lib.openframe-data-mongo-common.src.main.java.com.openframe.data.document.tool.filter.ToolQueryFilter.ToolQueryFilter`
-
-### Purpose
-
-Filters integrated tool documents based on enablement and classification.
-
-### Fields
-
-- `Boolean enabled`
-- `String type`
-- `String category`
-- `String platformCategory`
-
-### Common Use Cases
-
-- Retrieve only enabled tools
-- Filter by tool type (e.g., RMM, MDM)
-- Segment tools by platform category
-
----
-
-## UserQueryFilter
-
-**Component:**  
-`openframe-oss-lib.openframe-data-mongo-common.src.main.java.com.openframe.data.document.user.filter.UserQueryFilter.UserQueryFilter`
-
-### Purpose
-
-Defines flexible filtering for user queries.
-
-### Fields
-
-- `String emailRegex`
-- `String nameRegex`
-- `UserStatus status`
-
-### Query Semantics
-
-- Regex-based filtering for search capabilities
-- Status-based filtering (e.g., ACTIVE, DISABLED)
-
-```mermaid
-flowchart LR
-    UserFilter["UserQueryFilter"] --> Email["emailRegex"]
-    UserFilter --> Name["nameRegex"]
-    UserFilter --> Status["UserStatus"]
-```
-
----
-
-# Integration with Repositories
-
-The filters are interpreted by repository implementations in the sync and reactive Mongo modules.
-
-```mermaid
-flowchart TD
-    ServiceLayer["Service Layer"] --> QueryFilter["Query Filter"]
-    QueryFilter --> CustomRepository["Custom Repository Impl"]
-    CustomRepository --> CriteriaBuilder["Mongo Criteria Builder"]
-    CriteriaBuilder --> Mongo[("MongoDB Collection")]
-```
-
-Repositories typically:
-
-1. Inspect each non-null filter field.
-2. Add corresponding `Criteria` conditions.
-3. Combine conditions using `andOperator` / `orOperator`.
-4. Apply pagination and sorting.
-
----
-
-# Benefits to the Platform
-
-### Clean Separation of Concerns
-
-- API DTOs define external contract.
-- Query filters define internal query semantics.
-- Repositories handle persistence mechanics.
-
-### Extensibility
-
-Adding a new filter field:
-
-1. Extend the filter class.
-2. Update repository criteria logic.
-3. Expose through API input DTO if needed.
-
-No cross-layer coupling is introduced.
-
-### Consistency Across Domains
-
-All filters follow a uniform pattern:
-
-- Builder-based construction
-- Optional fields
-- Domain-aligned attributes
-- Used exclusively by data layer
-
----
-
-# Summary
-
-The **Data Mongo Query Filters** module provides the structured, domain-driven filtering layer for MongoDB queries across OpenFrame.
-
-It:
-
-- Encapsulates filtering logic for events, organizations, tickets, tools, and users.
-- Bridges API input models with Mongo repository implementations.
-- Supports flexible, composable, and maintainable query construction.
-- Enforces consistent filtering patterns across the data access layer.
-
-This module is a foundational building block in the persistence architecture, enabling scalable, expressive, and maintainable MongoDB querying throughout the platform.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-mongo-reactive-repositories/data-mongo-reactive-repositories.md b/docs/reference/architecture/data-mongo-reactive-repositories/data-mongo-reactive-repositories.md
deleted file mode 100644
index 618500f92..000000000
--- a/docs/reference/architecture/data-mongo-reactive-repositories/data-mongo-reactive-repositories.md
+++ /dev/null
@@ -1,287 +0,0 @@
-# Data Mongo Reactive Repositories
-
-## Overview
-
-The **Data Mongo Reactive Repositories** module provides reactive, non-blocking access to MongoDB for selected core domain entities in the OpenFrame platform. Built on **Spring Data Reactive MongoDB** and **Project Reactor**, this module enables asynchronous data access patterns using `Mono` and `Flux` types.
-
-It complements the synchronous repository layer by offering reactive alternatives for high-concurrency or event-driven use cases, particularly around:
-
-- OAuth client persistence
-- User lookups and existence checks
-- Security and authentication flows
-
-This module integrates closely with:
-
-- The domain model defined in **Data Mongo Domain Model**
-- Shared base repository contracts from the synchronous layer
-- Spring Boot auto-configuration and repository scanning
-
----
-
-## Core Components
-
-This module contains three primary components:
-
-- `MongoReactiveConfig`
-- `ReactiveOAuthClientRepository`
-- `ReactiveUserRepository`
-
----
-
-## Architecture Overview
-
-```mermaid
-flowchart TD
-    App["Application Context"] --> Config["MongoReactiveConfig"]
-    Config -->|"@EnableReactiveMongoRepositories"| Scan["Reactive Repository Scan"]
-
-    Scan --> OAuthRepo["ReactiveOAuthClientRepository"]
-    Scan --> UserRepo["ReactiveUserRepository"]
-
-    OAuthRepo --> OAuthClient["OAuthClient Document"]
-    UserRepo --> UserDoc["User Document"]
-
-    OAuthClient --> MongoDB[("MongoDB")]
-    UserDoc --> MongoDB
-```
-
-The configuration class enables reactive repository scanning. Spring automatically wires implementations for repository interfaces extending `ReactiveMongoRepository`.
-
----
-
-## Reactive Programming Model
-
-This module uses **Project Reactor** primitives:
-
-- `Mono<T>` — zero or one result
-- `Flux<T>` — zero to many results
-
-Example semantics:
-
-```text
-Mono<User>        → Asynchronous single user lookup
-Mono<Boolean>     → Asynchronous existence check
-```
-
-Unlike synchronous repositories that block on I/O, reactive repositories:
-
-- Use non-blocking MongoDB drivers
-- Integrate with WebFlux and reactive security chains
-- Support high-concurrency workloads efficiently
-
----
-
-## Component Details
-
-### MongoReactiveConfig
-
-**Class:** `MongoReactiveConfig`  
-**Package:** `com.openframe.data.config`
-
-```java
-@Configuration
-@EnableReactiveMongoRepositories(basePackages = "com.openframe.data.reactive.repository")
-public class MongoReactiveConfig {
-}
-```
-
-#### Responsibilities
-
-- Enables reactive MongoDB repository scanning
-- Registers Spring Data reactive repository infrastructure
-- Configures repositories located under:
-
-```text
-com.openframe.data.reactive.repository
-```
-
-This class acts as the entry point for the reactive persistence layer.
-
----
-
-### ReactiveOAuthClientRepository
-
-**Interface:** `ReactiveOAuthClientRepository`  
-**Extends:** `ReactiveMongoRepository<OAuthClient, String>`
-
-```java
-@Repository
-public interface ReactiveOAuthClientRepository 
-        extends ReactiveMongoRepository<OAuthClient, String> {
-
-    Mono<OAuthClient> findByClientId(String clientId);
-}
-```
-
-#### Responsibilities
-
-- Reactive CRUD operations for `OAuthClient`
-- Lookup by `clientId`
-- Used by authentication and OAuth flows
-
-#### Data Flow
-
-```mermaid
-sequenceDiagram
-    participant Service as "Auth Service"
-    participant Repo as "ReactiveOAuthClientRepository"
-    participant DB as "MongoDB"
-
-    Service->>Repo: findByClientId(clientId)
-    Repo->>DB: Reactive query
-    DB-->>Repo: OAuthClient document
-    Repo-->>Service: Mono<OAuthClient>
-```
-
-#### Typical Use Cases
-
-- OAuth client validation
-- Client credentials flow
-- Token issuance validation
-- Dynamic client lookup
-
----
-
-### ReactiveUserRepository
-
-**Interface:** `ReactiveUserRepository`  
-**Extends:**
-- `ReactiveMongoRepository<User, String>`
-- `BaseUserRepository<Mono<User>, Mono<Boolean>, String>`
-
-```java
-@Repository
-public interface ReactiveUserRepository 
-    extends ReactiveMongoRepository<User, String>,
-            BaseUserRepository<Mono<User>, Mono<Boolean>, String> {
-
-    Mono<User> findByEmail(String email);
-
-    Mono<Boolean> existsByEmail(String email);
-
-    Mono<Boolean> existsByEmailAndStatus(String email, UserStatus status);
-}
-```
-
-#### Responsibilities
-
-- Reactive user retrieval by email
-- Email existence checks
-- Status-aware existence validation
-- Compliance with shared `BaseUserRepository` contract
-
-#### Inheritance Model
-
-```mermaid
-flowchart LR
-    BaseRepo["BaseUserRepository"] --> ReactiveRepo["ReactiveUserRepository"]
-    ReactiveMongo["ReactiveMongoRepository"] --> ReactiveRepo
-    ReactiveRepo --> UserDoc["User Document"]
-```
-
-The repository:
-
-- Inherits generic user contract behavior
-- Adapts return types to `Mono<T>`
-- Ensures consistency across reactive and synchronous layers
-
-#### Example Reactive Pattern
-
-```text
-findByEmail(email)
-    → returns Mono<User>
-    → may emit value or complete empty
-```
-
-This integrates directly with:
-
-- Reactive security filters
-- OAuth BFF layers
-- WebFlux controllers
-
----
-
-## Relationship to Other Modules
-
-### Data Mongo Domain Model
-
-The reactive repositories operate on domain documents defined in:
-
-- `User`
-- `OAuthClient`
-
-These are defined in the **Data Mongo Domain Model** module.
-
-(See the corresponding domain model documentation for detailed schema information.)
-
----
-
-### Data Mongo Base Repositories
-
-`ReactiveUserRepository` implements the generic `BaseUserRepository` contract, ensuring:
-
-- Cross-layer API consistency
-- Shared query method definitions
-- Type-safe generics for both blocking and reactive variants
-
-This pattern allows the platform to maintain consistent repository contracts while supporting different execution models.
-
----
-
-## Reactive vs Synchronous Repositories
-
-| Aspect | Reactive | Synchronous |
-|--------|----------|------------|
-| Driver | Reactive MongoDB driver | Blocking MongoDB driver |
-| Return Types | `Mono<T>`, `Flux<T>` | `T`, `List<T>` |
-| Thread Model | Event-loop friendly | Thread-per-request |
-| Backpressure | Supported | Not supported |
-
-The reactive repositories are ideal for:
-
-- High-concurrency authentication workloads
-- Streaming integrations
-- Event-driven services
-
----
-
-## Security and OAuth Integration
-
-Reactive repositories are particularly important in:
-
-- OAuth client validation
-- Email-based login checks
-- Account existence validation
-- Status-based user access control
-
-Because these flows are frequently executed and latency-sensitive, non-blocking access improves scalability and throughput.
-
----
-
-## Extension Guidelines
-
-When adding new reactive repositories:
-
-1. Place them under:
-
-```text
-com.openframe.data.reactive.repository
-```
-
-2. Extend `ReactiveMongoRepository<Entity, IdType>`
-3. Return `Mono<T>` or `Flux<T>`
-4. If applicable, implement shared base repository contracts
-5. Ensure the entity exists in the domain model module
-
----
-
-## Summary
-
-The **Data Mongo Reactive Repositories** module provides:
-
-- Spring Data reactive MongoDB integration
-- Reactive user and OAuth client persistence
-- Contract alignment with base repository interfaces
-- Non-blocking access patterns for authentication-critical flows
-
-It forms a lightweight but critical foundation for scalable security, authentication, and identity-related operations across the OpenFrame platform.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-mongo-sync-config-and-custom-repositories/data-mongo-sync-config-and-custom-repositories.md b/docs/reference/architecture/data-mongo-sync-config-and-custom-repositories/data-mongo-sync-config-and-custom-repositories.md
deleted file mode 100644
index 4c8b166e1..000000000
--- a/docs/reference/architecture/data-mongo-sync-config-and-custom-repositories/data-mongo-sync-config-and-custom-repositories.md
+++ /dev/null
@@ -1,434 +0,0 @@
-# Data Mongo Sync Config And Custom Repositories
-
-## Overview
-
-The **Data Mongo Sync Config And Custom Repositories** module provides the synchronous MongoDB configuration and advanced repository implementations used across the OpenFrame platform.
-
-It is responsible for:
-
-- Bootstrapping synchronous MongoDB repositories
-- Customizing Mongo mapping and auditing behavior
-- Managing indexes and legacy index cleanup
-- Implementing advanced filtering, cursor-based pagination, sorting, and aggregation logic
-- Providing bulk and optimized update operations
-- Supporting optimistic locking retry observability
-
-This module builds on:
-
-- [Data Mongo Domain Model](../data-mongo-domain-model/data-mongo-domain-model.md)
-- [Data Mongo Query Filters](../data-mongo-query-filters/data-mongo-query-filters.md)
-- [Data Mongo Base Repositories](../data-mongo-base-repositories/data-mongo-base-repositories.md)
-
-It acts as the **data-access execution layer** for API services, management services, and background processors.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    ApiLayer["API Service Layer"] --> RepositoryLayer["Custom Repositories"]
-    RepositoryLayer --> MongoTemplate["MongoTemplate"]
-    MongoTemplate --> MongoDB[("MongoDB")]
-
-    DomainModel["Domain Documents"] --> RepositoryLayer
-    QueryFilters["Query Filter DTOs"] --> RepositoryLayer
-
-    Config["Mongo Sync Config"] --> RepositoryLayer
-    IndexConfig["Mongo Index Config"] --> MongoDB
-```
-
-### Key Responsibilities
-
-| Layer | Responsibility |
-|--------|----------------|
-| Mongo Sync Config | Enables repositories, auditing, mapping customization |
-| Mongo Index Config | Ensures required indexes, removes legacy indexes |
-| Custom Repositories | Filtering, cursor pagination, aggregations, bulk updates |
-| Retry Listener | Observability for optimistic locking retries |
-
----
-
-# Configuration Layer
-
-## Mongo Sync Config
-
-**Component:** `MongoSyncConfig`
-
-Enables synchronous Mongo repositories and configures Mongo mapping behavior.
-
-### Features
-
-- Conditional activation via `spring.data.mongodb.enabled`
-- Enables `@EnableMongoRepositories` for `com.openframe.data.repository`
-- Enables `@EnableMongoAuditing`
-- Custom `MappingMongoConverter`
-
-### Mapping Customization
-
-```mermaid
-flowchart LR
-    Factory["MongoDatabaseFactory"] --> Resolver["DefaultDbRefResolver"]
-    Resolver --> Converter["MappingMongoConverter"]
-    Conversions["MongoCustomConversions"] --> Converter
-```
-
-Notable configuration:
-
-- `setMapKeyDotReplacement("__dot__")`
-  - Allows storing map keys containing dots (`.`) safely
-
-This is critical for metadata-heavy documents like events and external application integrations.
-
----
-
-## Mongo Index Config
-
-**Component:** `MongoIndexConfig`
-
-Executed at application startup via `@PostConstruct`.
-
-### Index Responsibilities
-
-- Ensures compound indexes on `application_events`
-- Drops stale legacy indexes
-
-### Example Indexes
-
-- `{ userId: ASC, timestamp: DESC }`
-- `{ type: ASC, metadata.tags: ASC }`
-
-### Legacy Cleanup
-
-```mermaid
-flowchart TD
-    Startup["Application Startup"] --> EnsureIndexes["Ensure Required Indexes"]
-    EnsureIndexes --> DropLegacy["Drop Stale Indexes"]
-    DropLegacy --> LogResult["Log Success Or Skip"]
-```
-
-The cleanup ensures:
-
-- Schema evolution safety
-- Removal of org-scoped uniqueness constraints
-- Tenant-wide tag uniqueness enforcement consistency
-
----
-
-# Custom Repository Implementations
-
-This module implements advanced data-access behavior beyond standard Spring Data repositories.
-
-Common patterns across repositories:
-
-- Cursor-based pagination using `_id`
-- Secondary sort field with `_id` tie-breaker
-- Mongo `Criteria`-based dynamic filtering
-- Aggregation pipelines for grouped metrics
-- Distinct queries for filter options
-- Bulk operations for efficiency
-
----
-
-## Cursor-Based Pagination Pattern
-
-Most repositories follow this strategy:
-
-```mermaid
-flowchart TD
-    ClientRequest["Client Request With Cursor"] --> ParseCursor["Parse ObjectId"]
-    ParseCursor --> LoadCursorDoc["Load Cursor Document"]
-    LoadCursorDoc --> CompareSortField["Compare Sort Field"]
-    CompareSortField --> AddCriteria["Add $or Criteria"]
-    AddCriteria --> ApplySort["Sort By Field And _id"]
-    ApplySort --> Limit["Apply Limit"]
-```
-
-This ensures:
-
-- Stable ordering
-- Deterministic pagination
-- No duplicates or gaps
-- Proper tie-breaking when sort field values are equal
-
----
-
-# Repository Categories
-
-## 1. Assignment Repository
-
-**Component:** `CustomItemAssignmentRepositoryImpl`
-
-Features:
-
-- Cursor-based pagination
-- Search by display name
-- Group-by aggregation per `AssignmentTargetType`
-
-Aggregation example:
-
-```mermaid
-flowchart LR
-    Match["Match itemId"] --> Group["Group By targetType"]
-    Group --> Count["Count"]
-    Count --> MapResult["Map To EnumMap"]
-```
-
----
-
-## 2. Machine Repository
-
-**Component:** `CustomMachineRepositoryImpl`
-
-Capabilities:
-
-- Multi-field filtering (status, type, OS, organization)
-- Regex-based search (hostname, IP, serial, model)
-- Cursor pagination with compound sorting
-- Count queries for pagination metadata
-
----
-
-## 3. Event Repositories
-
-### External Application Event Repository
-
-**Component:** `ExternalApplicationEventRepository`
-
-- Spring Data `MongoRepository`
-- Time-range queries
-- Custom `@Query` for metadata tag filtering
-
-### Custom Event Repository
-
-**Component:** `CustomEventRepositoryImpl`
-
-Features:
-
-- Date range filtering
-- Distinct queries (userId, event type)
-- Cursor pagination
-- Search over type and data fields
-
----
-
-## 4. Knowledge Base Repository
-
-**Component:** `CustomKnowledgeBaseItemRepositoryImpl`
-
-Advanced behaviors:
-
-- Folder vs article separation
-- Archived vs active filtering
-- Combined `$or` search and cursor criteria using `$and`
-- Draft visibility model
-
-### Composite Criteria Strategy
-
-Spring Data does not allow multiple root `$or` conditions.
-
-Solution:
-
-```mermaid
-flowchart TD
-    SearchCriteria["Search OR Criteria"] --> Combine
-    CursorCriteria["Cursor OR Criteria"] --> Combine
-    Combine["Combine Using $and"] --> FinalQuery["Final Query"]
-```
-
-This avoids null-key collisions in the Mongo query builder.
-
----
-
-## 5. Notification Repositories
-
-### Custom Notification Repository
-
-**Component:** `CustomNotificationRepositoryImpl`
-
-Implements:
-
-- Recipient-based filtering
-- Read/unread filtering
-- Title search
-- Forward/backward pagination
-- Two-phase fetch (read states first, then notifications)
-
-```mermaid
-flowchart TD
-    FetchReadStates["Fetch NotificationReadState"] --> ExtractIds
-    ExtractIds["Extract Notification IDs"] --> FetchNotifications
-    FetchNotifications["Fetch Notification Documents"] --> Merge["Merge With Status"]
-```
-
-### Custom Notification Read State Repository
-
-**Component:** `CustomNotificationReadStateRepositoryImpl`
-
-- Bulk unordered insert
-- Gracefully swallows duplicate-key errors
-- Improves idempotency in concurrent flows
-
----
-
-## 6. Ticket Repository
-
-**Component:** `CustomTicketRepositoryImpl`
-
-One of the most feature-rich repositories.
-
-Capabilities:
-
-- Complex filtering (status, org, assignee, device)
-- Created-at range filtering
-- Cursor-based pagination with tie-breaker
-- Aggregation metrics:
-  - Count by status
-  - Average resolution time
-- Bulk status update
-- Partial field updates (title)
-
-### Average Resolution Time Aggregation
-
-```mermaid
-flowchart LR
-    MatchResolved["Match Resolved Tickets"] --> ProjectDiff["Compute resolvedAt - createdAt"]
-    ProjectDiff --> GroupAvg["Average Resolution Time"]
-```
-
----
-
-## 7. Organization Repository
-
-**Component:** `CustomOrganizationRepositoryImpl`
-
-Features:
-
-- Default ACTIVE status filtering
-- Contract validity evaluation
-- Employee range filters
-- Regex category matching
-- Cursor pagination with multi-field sorting
-
----
-
-## 8. Integrated Tool Repository
-
-**Component:** `CustomIntegratedToolRepositoryImpl`
-
-Capabilities:
-
-- Enabled/type/category filtering
-- Search over name and description
-- Distinct queries for:
-  - type
-  - category
-  - platformCategory
-
----
-
-## 9. User Repository
-
-**Component:** `CustomUserRepositoryImpl`
-
-Focused on search:
-
-- Status filtering
-- Email regex
-- Name regex (first OR last name)
-- Sorted by createdAt descending
-
----
-
-## 10. OAuth Token Repository
-
-**Component:** `OAuthTokenRepository`
-
-Simple Spring Data repository with:
-
-- `findByAccessToken`
-- `findByRefreshToken`
-
-Used by authentication and token lifecycle management flows.
-
----
-
-## 11. Ticket Attachments And Notes
-
-- `TicketAttachmentRepository`
-- `TicketNoteRepository`
-
-Provide standard CRUD plus:
-
-- Find by ticket ID
-- Batch lookup
-- Delete by ticket ID
-- Sorted retrieval (notes)
-
----
-
-# Retry Observability
-
-## Optimistic Locking Retry Listener
-
-**Component:** `OptimisticLockingRetryListener`
-
-Provides structured logging for:
-
-- Retry attempts
-- Retry success
-- Retry exhaustion
-
-```mermaid
-flowchart TD
-    RetryStart["Retry Attempt"] --> OnError["onError()"]
-    OnError --> LogWarn["Log Warning"]
-    RetryEnd["Retry Complete"] --> Close
-    Close --> SuccessOrFail["Log Success Or Error"]
-```
-
-This improves:
-
-- Visibility into concurrency conflicts
-- Operational debugging
-- Retry exhaustion tracing
-
----
-
-# Cross-Module Relationships
-
-The **Data Mongo Sync Config And Custom Repositories** module interacts heavily with:
-
-- **Domain documents** from Data Mongo Domain Model
-- **Query filter DTOs** from Data Mongo Query Filters
-- **API Services** and **Management Services** that orchestrate business logic
-- **Authorization Service** when dealing with OAuth tokens
-
-It serves as the **core synchronous persistence engine** of the OpenFrame platform.
-
----
-
-# Design Principles
-
-1. Database-Level Filtering First
-2. Deterministic Cursor Pagination
-3. Safe Aggregations With Type Mapping
-4. Bulk Operations For Performance
-5. Graceful Handling Of Legacy Indexes
-6. Idempotent Insert Strategies
-7. Clear Separation Between Query Building And Execution
-
----
-
-# Summary
-
-The **Data Mongo Sync Config And Custom Repositories** module:
-
-- Configures MongoDB for synchronous workloads
-- Ensures proper indexing and schema evolution safety
-- Implements advanced query logic across all major domain entities
-- Provides efficient aggregation and bulk operations
-- Enables stable cursor-based pagination across the platform
-- Improves concurrency observability via retry listeners
-
-It is a foundational infrastructure module that underpins all synchronous data access within the OpenFrame ecosystem.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-nats-notifications/data-nats-notifications.md b/docs/reference/architecture/data-nats-notifications/data-nats-notifications.md
deleted file mode 100644
index 5f5202f3a..000000000
--- a/docs/reference/architecture/data-nats-notifications/data-nats-notifications.md
+++ /dev/null
@@ -1,365 +0,0 @@
-# Data Nats Notifications
-
-## Overview
-
-The **Data Nats Notifications** module is responsible for broadcasting real-time notifications over NATS while ensuring durable persistence in MongoDB. It acts as the bridge between:
-
-- The persistent notification domain model (Mongo documents)
-- The read-state tracking subsystem
-- The NATS messaging infrastructure
-- Downstream consumers such as WebSocket gateways, clients, and machine agents
-
-This module guarantees that:
-
-- Notifications are **persisted first** (source of truth).
-- Read states are created for each recipient.
-- Real-time delivery over NATS is **best-effort and non-blocking**.
-- Clients can reconcile missed events via GraphQL or REST catch-up.
-
-It is feature-flagged and can operate in persistence-only mode when NATS is disabled.
-
----
-
-## Core Responsibilities
-
-The Data Nats Notifications module provides:
-
-1. ✅ Command validation and audience sanitation
-2. ✅ Durable notification persistence
-3. ✅ Read-state creation for users and machines
-4. ✅ NATS subject-based publishing
-5. ✅ Safe failure handling with rollback protection
-6. ✅ Graceful degradation when NATS is unavailable
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    Caller["Application Service"] --> Command["NotificationCommand"]
-    Command --> Broadcaster["NotificationBroadcaster"]
-
-    Broadcaster --> Repo["NotificationRepository"]
-    Broadcaster --> ReadState["NotificationReadStateService"]
-    Broadcaster --> Registry["NotificationContextDescriptorRegistry"]
-
-    Broadcaster -->|"optional"| Publisher["NotificationNatsPublisher"]
-    Publisher --> Nats["NATS Server"]
-
-    Repo --> Mongo[("MongoDB")]
-    ReadState --> Mongo
-```
-
-### Key Design Principle
-
-**Persistence is the source of truth.**
-
-NATS delivery is best-effort. If publishing fails, the notification remains persisted and recipients reconcile via API queries.
-
----
-
-## Notification Lifecycle
-
-```mermaid
-flowchart TD
-    Start["Broadcast Request"] --> Validate["Validate NotificationCommand"]
-    Validate --> Persist["Persist Notification"]
-    Persist --> CreateReadStates["Create Read States"]
-    CreateReadStates --> Publish["Publish to NATS"]
-    Publish --> End["Complete"]
-
-    CreateReadStates -->|"failure"| Rollback["Delete Notification"]
-```
-
-### Transactional Strategy
-
-- If **read-state creation fails**, the notification document is deleted.
-- If **NATS publish fails**, no rollback occurs.
-- Recipients catch up using stored notifications.
-
----
-
-# Core Components
-
-## 1. NotificationCommand
-
-Immutable command object representing a validated broadcast request.
-
-### Responsibilities
-
-- Enforces required fields:
-  - `title`
-  - `severity`
-  - `context`
-- Ensures `context.type` is non-blank
-- Sanitizes and validates:
-  - `adminAudience`
-  - `machineAudience`
-- Requires at least one non-empty audience
-- Produces immutable recipient sets
-
-### Validation Rules
-
-```text
-- title must not be blank
-- severity must not be null
-- context must not be null
-- context.type must not be blank
-- at least one audience must be non-empty
-- no blank entries in audience sets
-```
-
-This prevents invalid broadcasts from reaching persistence or NATS.
-
----
-
-## 2. NotificationBroadcaster
-
-The orchestration service of the module.
-
-### Dependencies
-
-- `NotificationRepository`
-- `NotificationReadStateService`
-- `NotificationContextDescriptorRegistry`
-- Optional `NotificationNatsPublisher`
-
-### Feature Flag
-
-```text
-openframe.features.notifications.enabled=false
-```
-
-If disabled:
-- No persistence
-- No read states
-- No NATS publish
-- Broadcast returns `null`
-
----
-
-### Broadcast Flow
-
-```mermaid
-flowchart LR
-    Cmd["NotificationCommand"] --> Build["Build Notification"]
-    Build --> Save["Save to Repository"]
-    Save --> Category["Resolve Category"]
-    Category --> RS["Create Read States"]
-    RS --> Publish["Publish Per Recipient"]
-```
-
-### Read-State Creation
-
-Recipients are separated by type:
-
-- `RecipientType.USER`
-- `RecipientType.MACHINE`
-
-The category is derived from:
-
-- `NotificationContextDescriptorRegistry`
-
-If read-state creation throws an exception:
-
-1. The persisted notification is deleted.
-2. The exception is rethrown.
-3. Caller must retry.
-
----
-
-### NATS Publishing Strategy
-
-Publishing is performed per-recipient:
-
-- Each admin user → `user.{userId}.notification`
-- Each machine → `machine.{machineId}.notification`
-
-Failures are handled individually:
-
-- Logged as warnings
-- No rollback
-- Recipient reconciles via API
-
----
-
-## 3. NotificationNatsPublisher
-
-Encapsulates subject generation and NATS publishing.
-
-### Conditional Activation
-
-```text
-@ConditionalOnProperty("spring.cloud.stream.enabled")
-```
-
-If Spring Cloud Stream is disabled:
-- Publisher bean is not created
-- Broadcaster logs persistence-only mode
-
----
-
-### Subject Templates
-
-```text
-user.{userId}.notification
-machine.{machineId}.notification
-```
-
-### Publish Safety Rules
-
-- `userId` and `machineId` must not be blank
-- Notification must be persisted (must have `id`)
-- `NatsException` is caught and logged
-- No exception propagates to caller
-
----
-
-### Message Construction
-
-The domain `Notification` document is mapped to a lightweight transport model:
-
-```mermaid
-flowchart TD
-    Doc["Notification Document"] --> Msg["NotificationMessage"]
-
-    Msg --> Id["id"]
-    Msg --> Severity["severity"]
-    Msg --> Title["title"]
-    Msg --> Desc["description"]
-    Msg --> Created["createdAt"]
-    Msg --> Context["context"]
-```
-
-Only fields required by clients are included.
-
----
-
-## 4. NotificationMessage
-
-Transport DTO published to NATS.
-
-### Fields
-
-```text
-id          : String
-severity    : NotificationSeverity
-title       : String
-description : String
-createdAt   : Instant
-context     : NotificationContext
-```
-
-Designed to:
-
-- Be serialization-friendly
-- Avoid heavy domain coupling
-- Provide enough context for real-time rendering
-
----
-
-# Reliability Model
-
-The module intentionally separates:
-
-- **Storage reliability** (strong)
-- **Delivery reliability** (eventual)
-
-```mermaid
-flowchart TD
-    Persist["Persist Notification"] --> Durable["Durable Storage"]
-    Durable --> RealTime["Real-Time Publish"]
-
-    RealTime -->|"failure"| CatchUp["Client Catch-Up via API"]
-```
-
-### Guarantees
-
-| Concern | Guarantee |
-|----------|-----------|
-| Persistence | Strong (Mongo) |
-| Read State | Strong (created before publish) |
-| NATS Delivery | Best effort |
-| Consistency | Eventual for clients |
-
----
-
-# Integration with the Platform
-
-Although self-contained, this module integrates with:
-
-- Mongo notification domain model
-- Notification read-state services
-- NATS infrastructure
-- GraphQL notification queries
-- Gateway WebSocket or client subscribers
-
-### Typical End-to-End Flow
-
-```mermaid
-sequenceDiagram
-    participant Service
-    participant Broadcaster
-    participant Mongo
-    participant NATS
-    participant Client
-
-    Service->>Broadcaster: broadcast(command)
-    Broadcaster->>Mongo: save(notification)
-    Broadcaster->>Mongo: createReadStates()
-    Broadcaster->>NATS: publish(subject, message)
-    NATS->>Client: deliver real-time event
-    Client->>Mongo: query for reconciliation
-```
-
----
-
-# Design Principles
-
-## 1. Fail-Safe Persistence
-
-No notification is published without being persisted.
-
-## 2. Controlled Rollback
-
-Only read-state failures trigger deletion.
-
-## 3. Optional Real-Time Layer
-
-System works fully without NATS.
-
-## 4. Recipient Isolation
-
-Failures per-recipient do not block others.
-
-## 5. Immutable Command Pattern
-
-Validation happens before orchestration.
-
----
-
-# Configuration Summary
-
-```text
-openframe.features.notifications.enabled
-spring.cloud.stream.enabled
-```
-
-| Property | Purpose |
-|----------|----------|
-| openframe.features.notifications.enabled | Master feature flag |
-| spring.cloud.stream.enabled | Enables NATS publisher bean |
-
----
-
-# Conclusion
-
-The **Data Nats Notifications** module provides a robust, fault-tolerant notification broadcasting mechanism built on:
-
-- Strong persistence guarantees
-- Read-state tracking
-- Optional real-time messaging via NATS
-- Safe error handling and graceful degradation
-
-It ensures that OpenFrame can deliver reliable notifications to both administrators and machine agents while maintaining consistency and operational safety across distributed services.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-pinot-repositories/data-pinot-repositories.md b/docs/reference/architecture/data-pinot-repositories/data-pinot-repositories.md
deleted file mode 100644
index c3a1457da..000000000
--- a/docs/reference/architecture/data-pinot-repositories/data-pinot-repositories.md
+++ /dev/null
@@ -1,308 +0,0 @@
-# Data Pinot Repositories
-
-## Overview
-
-The **Data Pinot Repositories** module provides analytical data access capabilities using **Apache Pinot** for high-performance, real-time OLAP queries. While transactional and operational data is stored in MongoDB, this module is responsible for:
-
-- Real-time log analytics
-- Device-level aggregations and facet queries
-- High-volume, time-series filtering
-- Efficient count and distinct queries for UI filters
-
-It acts as the **analytics read layer** of the OpenFrame platform, optimized for dashboards, filters, and log exploration workloads.
-
----
-
-## Architectural Role in the Platform
-
-The platform follows a polyglot persistence architecture:
-
-- **MongoDB** → transactional and domain persistence
-- **Kafka / Stream Service** → event ingestion and enrichment
-- **Apache Pinot** → analytical querying and aggregations
-
-The Data Pinot Repositories module sits on top of Pinot and exposes structured repository abstractions used by API and management services.
-
-```mermaid
-flowchart LR
-    StreamService["Stream Service Core Kafka And Handlers"] -->|"Ingest Events"| PinotCluster["Apache Pinot Cluster"]
-    MongoDB["Data Mongo Domain Model"] -->|"Transactional Data"| Services["API & Management Services"]
-    PinotCluster -->|"Analytical Queries"| PinotRepos["Data Pinot Repositories"]
-    PinotRepos -->|"Facet Counts & Logs"| Services
-```
-
-### Upstream Dependencies
-
-- Event ingestion from **Stream Service Core Kafka And Handlers**
-- Pinot cluster availability and schema configuration
-
-### Downstream Consumers
-
-- API Service (GraphQL and REST)
-- External API Service
-- Management Service (resync operations)
-
----
-
-## Core Components
-
-The module contains the following core components:
-
-| Component | Responsibility |
-|------------|----------------|
-| `PinotConfig` | Configures Pinot broker and controller connections |
-| `PinotEventEntity` | Domain marker for Pinot-backed event projections |
-| `PinotClientDeviceRepository` | Device analytics and facet queries |
-| `PinotClientLogRepository` | Log search, filtering, and projection queries |
-
----
-
-## Configuration Layer
-
-### PinotConfig
-
-`PinotConfig` provides Spring-managed `Connection` beans for interacting with Pinot:
-
-- **Broker Connection** → Used for query execution
-- **Controller Connection** → Used for cluster/controller operations
-
-Configuration properties:
-
-- `pinot.broker.url`
-- `pinot.controller.url`
-- `pinot.tables.devices.name`
-- `pinot.tables.logs.name`
-
-```mermaid
-flowchart TD
-    AppConfig["Spring Context"] --> PinotConfig["PinotConfig"]
-    PinotConfig --> BrokerConn["pinotBrokerConnection()"]
-    PinotConfig --> ControllerConn["pinotControllerConnection()"]
-    BrokerConn --> PinotCluster["Pinot Broker"]
-    ControllerConn --> PinotController["Pinot Controller"]
-```
-
-The broker connection is injected into repository implementations using `@Qualifier("pinotBrokerConnection")`.
-
----
-
-## Device Analytics Repository
-
-### PinotClientDeviceRepository
-
-The **PinotClientDeviceRepository** provides analytical queries over the `devices` Pinot table.
-
-It supports:
-
-- Faceted filter queries
-- Aggregated device counts
-- Multi-dimensional filtering
-- Tag-based filtering
-
-### Supported Filters
-
-- Status (excluding `DELETED`)
-- Device type
-- OS type
-- Organization
-- Tags
-- Tag key-value pairs
-
-### Facet Query Pattern
-
-Facet queries dynamically exclude the field being aggregated to ensure correct filter option computation.
-
-```mermaid
-flowchart TD
-    Start["Facet Request"] --> BuildQuery["PinotQueryBuilder"]
-    BuildQuery --> ApplyFilters["applyDeviceFilters()"]
-    ApplyFilters --> ExcludeField{"Exclude Facet Field?"}
-    ExcludeField -->|"Yes"| SkipFilter["Skip That Filter"]
-    ExcludeField -->|"No"| ApplyFilter["Apply Filter"]
-    SkipFilter --> GroupBy["GROUP BY facetField"]
-    ApplyFilter --> GroupBy
-    GroupBy --> Execute["executeKeyCountQuery()"]
-```
-
-### Key Behaviors
-
-1. Always excludes devices with status `DELETED`.
-2. Dynamically removes the active facet field from filters.
-3. Returns `Map<String, Integer>` for UI-ready filter counts.
-4. Uses count queries for total filtered device count.
-
-This repository is optimized for dashboard filters and device inventory analytics.
-
----
-
-## Log Analytics Repository
-
-### PinotClientLogRepository
-
-The **PinotClientLogRepository** supports time-series log exploration and advanced filtering.
-
-### Capabilities
-
-- Date range filtering
-- Cursor-based pagination
-- Relevance search
-- Sortable column validation
-- Distinct filter options
-- Organization option projections
-
-### Query Construction Flow
-
-```mermaid
-flowchart LR
-    Request["Log Query Request"] --> Builder["PinotQueryBuilder"]
-    Builder --> DateRange["whereDateRange()"]
-    DateRange --> Filters["whereIn() / whereEquals()"]
-    Filters --> Search["whereRelevanceLogSearch()"]
-    Search --> Cursor["whereCursor()"]
-    Cursor --> Sorting["orderBySortInput()"]
-    Sorting --> Limit["limit()"]
-    Limit --> Execute["executeLogQuery()"]
-```
-
-### Sorting Controls
-
-The repository enforces a whitelist of sortable columns:
-
-- `eventTimestamp`
-- `severity`
-- `eventType`
-- `toolType`
-- `organizationId`
-- `deviceId`
-- `ingestDay`
-
-If a field is not sortable:
-
-- It falls back to `eventTimestamp`.
-
-This protects against invalid or unsafe query construction.
-
-### Projection Mapping
-
-Results are mapped into `LogProjection` objects using column index mapping derived from Pinot result sets.
-
-Important fields include:
-
-- `toolEventId`
-- `eventTimestamp`
-- `toolType`
-- `eventType`
-- `severity`
-- `organizationId`
-- `summary`
-
-The `eventTimestamp` is converted from epoch milliseconds to `Instant`.
-
----
-
-## Multi-Tenant Isolation
-
-All queries are built using a `tenantId` parameter via `PinotQueryBuilder`.
-
-This ensures:
-
-- Logical data isolation
-- Tenant-safe aggregations
-- Secure filtering across shared Pinot tables
-
-```mermaid
-flowchart TD
-    Query["Incoming Query"] --> TenantFilter["Apply tenantId"]
-    TenantFilter --> PinotExec["Execute on Shared Table"]
-    PinotExec --> TenantScoped["Tenant Scoped Result"]
-```
-
----
-
-## Interaction with Other Modules
-
-### Stream Ingestion
-
-Events are ingested via Kafka and enriched by the stream layer before being indexed into Pinot.
-
-See:
-
-- [Stream Service Core Kafka And Handlers](../stream-service-core-kafka-and-handlers.md)
-
-### Device Pinot Resynchronization
-
-Management workflows may trigger re-synchronization of device data into Pinot.
-
-See:
-
-- [Management Service Core Initializers And Schedulers](../management-service-core-initializers-and-schedulers.md)
-
-### API Layer Consumption
-
-The API layer consumes Pinot repositories to provide:
-
-- Filter option endpoints
-- Log search endpoints
-- Aggregated dashboard counts
-
----
-
-## Design Principles
-
-### 1. Separation of Concerns
-
-- MongoDB → transactional storage
-- Pinot → analytical read queries
-
-### 2. Query Builder Abstraction
-
-All query logic flows through a `PinotQueryBuilder`, ensuring:
-
-- Safe dynamic query construction
-- Consistent filter application
-- Centralized cursor logic
-
-### 3. Facet-First Design
-
-Repositories are optimized for UI filter experiences:
-
-- Count per facet value
-- Distinct option lists
-- Filter exclusion logic
-
-### 4. Performance-Oriented
-
-- Aggregations pushed to Pinot
-- Minimal application-side computation
-- Projection-based mapping
-
----
-
-## End-to-End Log Analytics Flow
-
-```mermaid
-flowchart LR
-    Client["UI / API Request"] --> ApiService["API Service"]
-    ApiService --> LogRepo["PinotClientLogRepository"]
-    LogRepo --> PinotBroker["Pinot Broker"]
-    PinotBroker --> PinotServer["Pinot Servers"]
-    PinotServer --> PinotBroker
-    PinotBroker --> LogRepo
-    LogRepo --> ApiService
-    ApiService --> Client
-```
-
----
-
-## Summary
-
-The **Data Pinot Repositories** module provides the analytical backbone of the OpenFrame platform.
-
-It enables:
-
-- Real-time log exploration
-- High-performance device filtering
-- Multi-dimensional facet queries
-- Secure tenant-scoped analytics
-
-By leveraging Apache Pinot, it ensures scalable, low-latency query execution for dashboard and filtering workloads while keeping transactional systems isolated in MongoDB.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-redis-cache/data-redis-cache.md b/docs/reference/architecture/data-redis-cache/data-redis-cache.md
deleted file mode 100644
index cb2f0e676..000000000
--- a/docs/reference/architecture/data-redis-cache/data-redis-cache.md
+++ /dev/null
@@ -1,240 +0,0 @@
-# Data Redis Cache
-
-The **Data Redis Cache** module provides Redis-based caching and key infrastructure for the OpenFrame platform. It integrates Spring Cache with Redis, configures synchronous and reactive Redis templates, and enforces tenant-aware key prefixing to ensure strict data isolation across organizations.
-
-This module acts as the foundational caching layer used by API services, management services, and other components that require high-performance, low-latency data access.
-
----
-
-## Purpose and Responsibilities
-
-The Data Redis Cache module is responsible for:
-
-- Enabling and configuring Spring Cache backed by Redis
-- Providing a tenant-aware cache key prefix strategy
-- Supplying `RedisTemplate` and `ReactiveRedisTemplate` beans
-- Enforcing standardized key/value serialization
-- Supporting conditional activation based on configuration
-
-Redis is enabled only when the property `spring.redis.enabled=true` is set, allowing flexible deployment topologies.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    AppServices["Application Services"] --> CacheAbstraction["Spring Cache Abstraction"]
-    CacheAbstraction --> CacheManager["RedisCacheManager"]
-    CacheManager --> RedisConnection["RedisConnectionFactory"]
-    CacheManager --> KeyBuilder["OpenframeRedisKeyBuilder"]
-    RedisConnection --> RedisServer[("Redis Server")]
-
-    ReactiveServices["Reactive Services"] --> ReactiveTemplate["ReactiveRedisTemplate"]
-    ReactiveTemplate --> ReactiveConnection["ReactiveRedisConnectionFactory"]
-    ReactiveConnection --> RedisServer
-```
-
-### Key Components
-
-| Component | Responsibility |
-|------------|----------------|
-| CacheConfig | Configures Spring Cache and RedisCacheManager |
-| RedisConfig | Provides RedisTemplate and ReactiveRedisTemplate beans |
-| OpenframeRedisKeyConfiguration | Registers OpenframeRedisKeyBuilder for tenant-aware key prefixes |
-
----
-
-# Core Configuration Classes
-
-## CacheConfig
-
-**Class:** `CacheConfig`
-
-This class enables Spring caching and configures the Redis-backed `CacheManager`.
-
-### Activation
-
-The configuration is loaded only if:
-
-```text
-spring.redis.enabled=true
-```
-
-### Default Cache Behavior
-
-The default cache configuration includes:
-
-- Time-to-live (TTL): 6 hours
-- Null values disabled
-- String key serialization
-- JSON value serialization using `GenericJackson2JsonRedisSerializer`
-- Tenant-aware key prefixing
-
-### Tenant-Aware Key Prefixing
-
-All cache keys follow this structure:
-
-```text
-<prefix>:<cacheName>::<key>
-```
-
-The prefix is computed via `OpenframeRedisKeyBuilder`, ensuring isolation between tenants.
-
-### Custom TTL Overrides
-
-Certain caches use shorter TTL values:
-
-| Cache Name | TTL |
-|------------|------|
-| fleetPolicyCache | 1 hour |
-| fleetQueryCache | 1 hour |
-
-This prevents stale policy or query data from persisting too long.
-
-### Cache Initialization Flow
-
-```mermaid
-flowchart TD
-    Start["Application Startup"] --> RedisEnabled{"Redis Enabled?"}
-    RedisEnabled -->|Yes| CreateManager["Create RedisCacheManager"]
-    RedisEnabled -->|No| Skip["Skip Redis Cache Config"]
-    CreateManager --> DefaultConfig["Apply Default TTL 6h"]
-    DefaultConfig --> FleetOverride["Override Fleet TTL 1h"]
-    FleetOverride --> Ready["CacheManager Ready"]
-```
-
----
-
-## RedisConfig
-
-**Class:** `RedisConfig`
-
-This class provides low-level Redis beans for both blocking and reactive usage.
-
-### Provided Beans
-
-| Bean | Type | Purpose |
-|------|------|----------|
-| redisTemplate | RedisTemplate<String, String> | Standard Redis operations |
-| reactiveStringRedisTemplate | ReactiveStringRedisTemplate | Reactive string-based operations |
-| reactiveRedisTemplate | ReactiveRedisTemplate<String, String> | Reactive key-value operations |
-
-### Serialization Strategy
-
-All templates use:
-
-- String serialization for keys
-- String serialization for values (in template beans)
-- JSON serialization for Spring Cache values (via CacheConfig)
-
-This ensures consistent behavior across imperative and reactive flows.
-
-### Repository Support
-
-`@EnableRedisRepositories` enables Redis-backed repositories under:
-
-```text
-com.openframe.data.repository.redis
-```
-
-This allows future extensions such as token stores, distributed locks, or transient state persistence.
-
----
-
-## OpenframeRedisKeyConfiguration
-
-**Class:** `OpenframeRedisKeyConfiguration`
-
-This configuration registers the `OpenframeRedisKeyBuilder` bean.
-
-### Responsibilities
-
-- Binds `OpenframeRedisProperties`
-- Constructs a reusable key builder
-- Ensures consistent prefix generation across the platform
-
-The key builder centralizes key naming conventions, preventing:
-
-- Cross-tenant collisions
-- Environment conflicts
-- Inconsistent naming patterns
-
----
-
-# Multi-Tenant Key Strategy
-
-The Data Redis Cache module enforces strict tenant-aware isolation.
-
-```mermaid
-flowchart LR
-    TenantA["Tenant A"] --> KeyBuilder
-    TenantB["Tenant B"] --> KeyBuilder
-    KeyBuilder --> RedisKeyA["tenantA:deviceCache::123"]
-    KeyBuilder --> RedisKeyB["tenantB:deviceCache::123"]
-    RedisKeyA --> RedisServer[("Redis")]
-    RedisKeyB --> RedisServer
-```
-
-Even when logical cache keys are identical, the computed prefix ensures physical separation in Redis.
-
----
-
-# Integration Within the Platform
-
-The Data Redis Cache module supports multiple platform layers:
-
-- API services for query result caching
-- Authorization services for token or metadata caching
-- Management services for transient synchronization data
-- Gateway services for rate limiting or session metadata
-
-It works alongside:
-
-- Mongo repositories (primary persistence layer)
-- Kafka streaming services (event-driven updates)
-- Security modules (authentication and token validation)
-
-Redis acts as a performance optimization layer — never the source of truth.
-
----
-
-# Conditional Activation and Deployment
-
-Redis caching is optional and controlled by configuration.
-
-```text
-spring.redis.enabled=true
-```
-
-If disabled:
-
-- CacheConfig is not loaded
-- RedisConfig is not loaded
-- No Redis repositories are enabled
-
-This design supports:
-
-- Local development without Redis
-- Staging environments with partial caching
-- Production environments with full caching enabled
-
----
-
-# Design Principles
-
-The Data Redis Cache module follows these principles:
-
-1. Tenant Isolation by Default
-2. Safe Serialization Strategies
-3. Sensible TTL Defaults with Domain Overrides
-4. Reactive and Imperative Support
-5. Conditional Bootstrapping
-
----
-
-# Summary
-
-The **Data Redis Cache** module provides a structured, tenant-aware, and extensible Redis caching layer for the OpenFrame platform. By centralizing Redis configuration, serialization policies, and key naming strategies, it ensures consistent behavior across services while preserving strong multi-tenant boundaries.
-
-It serves as the high-performance caching backbone of the platform while maintaining strict separation from the system's primary data stores.
\ No newline at end of file
diff --git a/docs/reference/architecture/external-api-service-core/external-api-service-core.md b/docs/reference/architecture/external-api-service-core/external-api-service-core.md
deleted file mode 100644
index 8a65298ac..000000000
--- a/docs/reference/architecture/external-api-service-core/external-api-service-core.md
+++ /dev/null
@@ -1,436 +0,0 @@
-# External Api Service Core
-
-## Overview
-
-The **External Api Service Core** module exposes a secure, API key–based REST interface for external integrations with the OpenFrame platform.
-
-It provides:
-
-- Public REST endpoints under `/api/v1/**`
-- Tool proxy endpoints under `/tools/**`
-- OpenAPI (Swagger) documentation
-- Cursor-based pagination, filtering, and sorting
-- API key authentication via `X-API-Key`
-
-Unlike the internal GraphQL-based API service, this module is purpose-built for third-party systems, automation scripts, and integration partners.
-
----
-
-## Architectural Positioning
-
-The External Api Service Core sits at the boundary between external consumers and the internal platform services.
-
-```mermaid
-flowchart LR
-    Client["External Client"] -->|"X-API-Key"| ExternalAPI["External Api Service Core"]
-
-    ExternalAPI --> DeviceService["Device Service"]
-    ExternalAPI --> EventService["Event Service"]
-    ExternalAPI --> LogService["Log Service"]
-    ExternalAPI --> OrganizationService["Organization Services"]
-    ExternalAPI --> ToolService["Tool Service"]
-
-    ExternalAPI --> ProxyService["Rest Proxy Service"]
-    ProxyService --> IntegratedTool["Integrated Tool"]
-
-    DeviceService --> MongoDB[("MongoDB")]
-    EventService --> MongoDB
-    LogService --> Pinot[("Apache Pinot")]
-    ToolService --> MongoDB
-```
-
-### Responsibilities
-
-- Authenticate requests using API keys
-- Translate REST query parameters into internal filter criteria
-- Apply cursor-based pagination
-- Map domain models into external DTOs
-- Proxy tool-specific requests to integrated tools
-
----
-
-## Authentication Model
-
-All endpoints require an API key provided in the `X-API-Key` header.
-
-```text
-X-API-Key: ak_keyId.sk_secretKey
-```
-
-Internally:
-
-- The API key is validated by upstream security filters
-- `X-User-Id` and `X-API-Key-Id` headers are injected
-- Controllers use those headers for auditing and authorization
-
-The module does **not** perform token-based OAuth authentication. It is explicitly designed for machine-to-machine API key usage.
-
----
-
-## OpenAPI Configuration
-
-### OpenApiConfig
-
-The `OpenApiConfig` class configures:
-
-- API metadata (title, version, license)
-- API key security scheme
-- Grouped OpenAPI paths
-- Server base path `/external-api`
-
-Documented path groups:
-
-```text
-Included:
-- /tools/**
-- /api/v1/**
-
-Excluded:
-- /actuator/**
-- /api/core/**
-```
-
-Security scheme definition:
-
-```text
-Type: APIKEY
-In: HEADER
-Header name: X-API-Key
-```
-
----
-
-# REST Controllers
-
-All REST endpoints are versioned under `/api/v1` except integration proxy endpoints (`/tools/**`).
-
----
-
-## DeviceController
-
-**Base Path:** `/api/v1/devices`
-
-### Capabilities
-
-- List devices with filtering and pagination
-- Retrieve a device by machine ID
-- Retrieve device filter options
-- Update device status
-
-### Query Features
-
-The controller converts query parameters into `DeviceFilterCriteria`:
-
-- Status filters
-- Device type filters
-- OS type filters
-- Organization filters
-- Tag filters
-- Search
-- Sorting
-- Cursor-based pagination
-
-```mermaid
-flowchart TD
-    Request["GET /api/v1/devices"] --> Criteria["DeviceFilterCriteria"]
-    Criteria --> Pagination["CursorPaginationCriteria"]
-    Pagination --> Query["DeviceService.queryDevices()"]
-    Query --> Result["Query Result"]
-    Result --> Mapper["DeviceMapper"]
-    Mapper --> Response["DevicesResponse"]
-```
-
-### Tag Enrichment
-
-When `includeTags=true`, the controller:
-
-1. Extracts machine IDs
-2. Loads tags via `TagService`
-3. Returns enriched response
-
-Failures in tag loading fall back to non-enriched responses.
-
----
-
-## EventController
-
-**Base Path:** `/api/v1/events`
-
-### Capabilities
-
-- Query events with filtering
-- Retrieve event by ID
-- Create event
-- Update event
-- Retrieve filter options
-
-### Filtering Dimensions
-
-- User IDs
-- Event types
-- Date range
-- Search term
-- Sorting
-- Cursor pagination
-
-```mermaid
-flowchart TD
-    EventRequest["GET /api/v1/events"] --> Filter["EventFilterCriteria"]
-    Filter --> Service["EventService.queryEvents()"]
-    Service --> Mapper["EventMapper"]
-    Mapper --> EventsResponse["EventsResponse"]
-```
-
-Create and update operations directly delegate to `EventService`.
-
----
-
-## LogController
-
-**Base Path:** `/api/v1/logs`
-
-### Capabilities
-
-- Query logs with filtering
-- Retrieve log filter options
-- Retrieve detailed log entry
-
-### Filtering Dimensions
-
-- Date range
-- Tool type
-- Event type
-- Severity
-- Organization
-- Device ID
-- Search
-- Sorting
-- Cursor pagination
-
-Log queries are executed via `LogService`, which may retrieve data from analytics stores such as Apache Pinot.
-
-Detailed log retrieval requires composite identifiers:
-
-```text
-ingestDay
-toolType
-eventType
-timestamp
-toolEventId
-```
-
----
-
-## OrganizationController
-
-**Base Path:** `/api/v1/organizations`
-
-### Capabilities
-
-- List organizations with filtering
-- Retrieve organization by database ID
-- Retrieve organization by business identifier
-- Create organization
-- Update organization
-- Update status (ACTIVE / ARCHIVED)
-- Check archive eligibility
-
-### Query Delegation
-
-The controller delegates:
-
-- Reads → `OrganizationQueryService`
-- Writes → `OrganizationCommandService`
-- Archival checks → `OrganizationService`
-
-```mermaid
-flowchart LR
-    OrgRequest["Organization Request"] --> QueryService["OrganizationQueryService"]
-    OrgRequest --> CommandService["OrganizationCommandService"]
-    CommandService --> Validation["Archive Rules"]
-```
-
-Archiving is blocked when active devices exist.
-
----
-
-## ToolController
-
-**Base Path:** `/api/v1/tools`
-
-### Capabilities
-
-- List integrated tools
-- Retrieve tool filter options
-
-Filtering includes:
-
-- Enabled status
-- Tool type
-- Category
-- Search
-- Sorting
-
-Delegates to `ToolService` and maps results using `ToolMapper`.
-
----
-
-## IntegrationController
-
-**Base Path:** `/tools/{toolId}/**`
-
-This controller proxies arbitrary HTTP requests to integrated tools.
-
-Supported methods:
-
-- GET
-- POST
-- PUT
-- PATCH
-- DELETE
-- OPTIONS
-
-```mermaid
-flowchart TD
-    Client["External Client"] --> ProxyController["IntegrationController"]
-    ProxyController --> RestProxyService["RestProxyService"]
-    RestProxyService --> ToolRepo["IntegratedToolRepository"]
-    RestProxyService --> Resolver["ProxyUrlResolver"]
-    Resolver --> TargetTool["Integrated Tool API"]
-```
-
----
-
-# Rest Proxy Service
-
-The `RestProxyService` performs secure HTTP forwarding.
-
-## Responsibilities
-
-1. Validate tool existence
-2. Verify tool is enabled
-3. Resolve upstream URL
-4. Attach tool credentials
-5. Forward request
-6. Return upstream response
-
-## Credential Injection
-
-Based on `APIKeyType`:
-
-```text
-HEADER       → Custom header injection
-BEARER_TOKEN → Authorization: Bearer <token>
-NONE         → No credential
-```
-
-## HTTP Client Configuration
-
-- Connection timeout: 10 seconds
-- Response timeout: 60 seconds
-- Apache HttpClient 5
-
-The service preserves:
-
-- HTTP method
-- Request body
-- Response status code
-- Response body
-
----
-
-# Pagination Model
-
-All list endpoints use cursor-based pagination.
-
-Components:
-
-- `CursorPaginationCriteria.fromRest(cursor, limit)`
-- `SortInput.from(sortField, sortDirection)`
-
-Benefits:
-
-- Stable pagination
-- Scalable large dataset traversal
-- No offset-based performance degradation
-
----
-
-# Error Handling
-
-Standard HTTP status codes are used:
-
-```text
-200  Success
-201  Created
-204  No Content
-400  Bad Request
-401  Unauthorized
-403  Forbidden
-404  Not Found
-409  Conflict
-429  Too Many Requests
-500  Internal Server Error
-```
-
-Domain-specific exceptions (e.g., `DeviceNotFoundException`, `OrganizationNotFoundException`) are translated into structured error responses.
-
----
-
-# Data Sources and Dependencies
-
-The module integrates with:
-
-- MongoDB (devices, organizations, tools)
-- Apache Pinot (log analytics)
-- Integrated tool APIs (via proxy)
-- Core domain services from the API layer
-
-It does not directly manage persistence; instead, it orchestrates existing services.
-
----
-
-# Key Design Characteristics
-
-## 1. Separation of Concerns
-
-- Controllers handle HTTP concerns
-- Services perform business logic
-- Mappers transform domain → external DTO
-- Proxy service handles external tool routing
-
-## 2. External-First Contract
-
-The REST surface is optimized for:
-
-- Predictable filtering
-- Explicit query parameters
-- Stable versioning (`/api/v1`)
-- API key–based automation
-
-## 3. Observability
-
-All controllers log:
-
-- Request parameters
-- User ID
-- API key ID
-- Pagination and sorting
-
-This enables auditability and traceability.
-
----
-
-# Summary
-
-The **External Api Service Core** module provides a secure, API key–driven REST interface for third-party integrations.
-
-It:
-
-- Exposes device, event, log, organization, and tool APIs
-- Implements cursor-based pagination and rich filtering
-- Proxies requests to integrated tools
-- Enforces API key authentication
-- Publishes OpenAPI documentation
-
-It acts as the official external integration boundary of the OpenFrame platform, enabling automation, ecosystem integrations, and partner access without exposing internal GraphQL or domain-layer complexity.
diff --git a/docs/reference/architecture/gateway-service-core-security-and-routing/gateway-service-core-security-and-routing.md b/docs/reference/architecture/gateway-service-core-security-and-routing/gateway-service-core-security-and-routing.md
deleted file mode 100644
index 8920d6d19..000000000
--- a/docs/reference/architecture/gateway-service-core-security-and-routing/gateway-service-core-security-and-routing.md
+++ /dev/null
@@ -1,368 +0,0 @@
-# Gateway Service Core Security And Routing
-
-## Overview
-
-The **Gateway Service Core Security And Routing** module is the reactive edge layer of the OpenFrame platform. It is responsible for:
-
-- Acting as the **entry point** for REST and WebSocket traffic
-- Enforcing **JWT-based authentication and role-based authorization**
-- Providing **API key authentication and rate limiting** for external APIs
-- Dynamically resolving **multi-tenant issuers**
-- Routing and proxying requests to integrated tools (e.g., MeshCentral, Tactical RMM)
-- Handling WebSocket proxying and session decoration
-
-Built on **Spring Cloud Gateway + WebFlux + Netty**, it provides a fully reactive, non-blocking gateway optimized for high concurrency and real-time integrations.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart TD
-    Client["Client / Agent / UI"] --> Gateway["Gateway Service Core Security And Routing"]
-
-    subgraph security_layer["Security Layer"]
-        AuthHeader["AddAuthorizationHeaderFilter"]
-        JwtConfig["JwtAuthConfig"]
-        SecurityConfig["GatewaySecurityConfig"]
-        ApiKeyFilter["ApiKeyAuthenticationFilter"]
-        OriginFilter["OriginSanitizerFilter"]
-    end
-
-    subgraph routing_layer["Routing & Proxy Layer"]
-        IntegrationCtrl["IntegrationController"]
-        WsConfig["WebSocketGatewayConfig"]
-        UpstreamResolvers["ToolUpstreamResolvers"]
-    end
-
-    Gateway --> security_layer
-    security_layer --> routing_layer
-    routing_layer --> Upstream["Integrated Tools / NATS / Services"]
-```
-
-The module is divided into four major concerns:
-
-1. **Reactive Server & Client Configuration (Netty + WebClient)**
-2. **Security (JWT, API Keys, Roles, CORS, Origin)**
-3. **WebSocket Routing & Decoration**
-4. **Tool Upstream Resolution & Proxying**
-
----
-
-## Reactive Infrastructure Configuration
-
-### NettySocketConfig
-
-Configures low-level TCP behavior for both:
-
-- Embedded Netty web server
-- Gateway outbound HTTP client
-- Reactor Netty WebSocket client
-
-Key socket options:
-
-- `SO_LINGER = 0` (fast connection teardown)
-- `TCP_NODELAY = true` (low-latency communication)
-
-This ensures optimal performance for high-throughput proxy and WebSocket traffic.
-
----
-
-### WebClientConfig
-
-Provides a preconfigured `WebClient.Builder` with:
-
-- 30s connection timeout
-- 30s response timeout
-- Read/write timeout handlers
-
-Used internally for REST proxying to upstream tools.
-
----
-
-## Security Architecture
-
-Security is layered and reactive. It supports:
-
-- Multi-tenant JWT validation
-- Role-based access control
-- API key authentication for external APIs
-- Bearer token resolution from multiple sources
-- CORS control
-- Origin header sanitization
-
-### Security Flow
-
-```mermaid
-flowchart TD
-    Request["Incoming Request"] --> Origin["OriginSanitizerFilter"]
-    Origin --> AuthHeader["AddAuthorizationHeaderFilter"]
-    AuthHeader --> JwtValidation["JWT Authentication"]
-    JwtValidation --> RoleCheck["Role Authorization Rules"]
-    RoleCheck --> ApiKeyCheck{"External API Path?"}
-    ApiKeyCheck -->|Yes| ApiKeyFilter["ApiKeyAuthenticationFilter"]
-    ApiKeyCheck -->|No| Continue["Continue Routing"]
-    ApiKeyFilter --> Continue
-    Continue --> Controller["Controller / Route"]
-```
-
----
-
-## JWT Authentication & Multi-Tenant Support
-
-### JwtAuthConfig
-
-- Uses a **Caffeine cache** to store `ReactiveAuthenticationManager` instances per issuer
-- Dynamically builds JWT decoders per tenant
-- Supports:
-  - Platform issuer (local public key)
-  - External issuers via OIDC discovery
-
-### IssuerUrlProvider
-
-Resolves allowed issuers dynamically from tenant configuration.
-
-- Reads tenants reactively
-- Builds issuer URLs using:
-  - `allowed-issuer-base`
-  - Tenant ID
-  - Optional super-tenant ID
-- Caches issuer URLs
-
-This enables strict issuer validation in multi-tenant deployments.
-
----
-
-## GatewaySecurityConfig
-
-Defines the reactive security filter chain.
-
-Key behavior:
-
-- Disables CSRF, HTTP Basic, form login
-- Enables OAuth2 Resource Server
-- Uses `ReactiveAuthenticationManagerResolver` for issuer-based validation
-- Injects `AddAuthorizationHeaderFilter` before authentication
-
-### Role Rules
-
-- `/api/**` → ADMIN
-- `/tools/agent/**` → AGENT
-- `/ws/tools/agent/**` → AGENT
-- `/ws/nats` → AGENT or ADMIN
-- `/guide/**` → ADMIN
-- `/clients/**` → AGENT
-
-All other paths default to `permitAll()` unless matched earlier.
-
----
-
-## AddAuthorizationHeaderFilter
-
-Ensures a Bearer token exists by resolving it from:
-
-1. Access token cookie
-2. Custom header
-3. Query parameter
-
-If found, it injects:
-
-```text
-Authorization: Bearer <token>
-```
-
-This enables WebSocket and browser flows that cannot always set headers directly.
-
----
-
-## API Key Authentication & Rate Limiting
-
-### ApiKeyAuthenticationFilter
-
-A `GlobalFilter` applied to `/external-api/**` endpoints.
-
-Flow:
-
-```mermaid
-flowchart TD
-    Req["/external-api/**"] --> CheckKey["Check X-API-Key Header"]
-    CheckKey --> Valid{"Valid Key?"}
-    Valid -->|No| Reject401["Return 401"]
-    Valid -->|Yes| RateCheck["RateLimitService.isAllowed"]
-    RateCheck --> Allowed{"Allowed?"}
-    Allowed -->|No| Reject429["Return 429 + Retry-After"]
-    Allowed -->|Yes| AddHeaders["Add RateLimit Headers"]
-    AddHeaders --> AddContext["Inject X-User-Id + X-Api-Key-Id"]
-    AddContext --> Forward["Forward to External API"]
-```
-
-Capabilities:
-
-- Validates API key
-- Increments usage stats
-- Enforces minute/hour/day limits
-- Adds rate limit headers
-- Injects user context headers
-
----
-
-## WebSocket Gateway Configuration
-
-### WebSocketGatewayConfig
-
-Defines WebSocket routing using Spring Cloud Gateway.
-
-Routes:
-
-- `/ws/tools/agent/{toolId}/**`
-- `/ws/tools/{toolId}/**`
-- `/ws/nats`
-- `/ws/nats-api`
-
-It also decorates:
-
-- `WebSocketClient` (optional proxy cleanup)
-- `WebSocketService` (security + metrics decorator)
-
----
-
-### WebSocket Proxy URL Filters
-
-#### ToolAgentWebSocketProxyUrlFilter
-
-- Extracts `toolId` from agent path
-- Resolves upstream WebSocket URL
-
-#### ToolApiWebSocketProxyUrlFilter
-
-- Extracts `toolId` from API path
-- Removes `Origin` header
-- Injects tool-specific API key headers
-
-These filters delegate actual resolution to the upstream resolver registry.
-
----
-
-## Tool Upstream Resolution
-
-The gateway uses a strategy pattern for resolving tool destinations.
-
-```mermaid
-flowchart LR
-    Request["Tool Request"] --> Registry["ToolUpstreamResolverRegistry"]
-    Registry -->|Specific Tool| Mesh["MeshCentralUpstreamResolver"]
-    Registry -->|Specific Tool| Tactical["TacticalRmmUpstreamResolver"]
-    Registry -->|Fallback| Default["DefaultToolUpstreamResolver"]
-    Mesh --> Proxy
-    Tactical --> Proxy
-    Default --> Proxy
-```
-
-### DefaultToolUpstreamResolver
-
-- Reads tool URLs from MongoDB
-- Uses `ToolUrlService`
-- Resolves API and WS URLs
-
-### MeshCentralUpstreamResolver
-
-- Uses configuration properties
-- Avoids DB lookup
-- Supports path prefix injection
-
-### TacticalRmmUpstreamResolver
-
-- Routes REST to backend
-- Routes WebSocket to:
-  - NATS (if path matches)
-  - Daphne (otherwise)
-
-This allows fine-grained routing without an intermediate nginx layer.
-
----
-
-## CORS & Origin Handling
-
-### CorsConfig
-
-- Enabled unless explicitly disabled
-- Uses Spring Cloud Gateway global CORS properties
-
-### OriginSanitizerFilter
-
-- Removes `Origin: null` headers
-- Prevents invalid origin propagation to upstream services
-
----
-
-## Internal Auth Probe
-
-### InternalAuthProbeController
-
-Conditional endpoint:
-
-```
-GET /internal/authz/probe
-```
-
-Used for health checks in internal deployments.
-
----
-
-## Path Constants
-
-`PathConstants` centralizes prefix definitions:
-
-- `/clients`
-- `/api`
-- `/tools`
-- `/ws/tools`
-- `/chat`
-- `/guide`
-
-Ensures consistent routing and security matching.
-
----
-
-## Request Lifecycle Summary
-
-```mermaid
-flowchart TD
-    Client --> Gateway
-    Gateway --> OriginFilter
-    OriginFilter --> AuthHeader
-    AuthHeader --> JwtResolver
-    JwtResolver --> RoleAuth
-    RoleAuth --> RouteDecision
-    RouteDecision -->|REST| IntegrationController
-    RouteDecision -->|WebSocket| WebSocketGatewayConfig
-    IntegrationController --> UpstreamResolver
-    WebSocketGatewayConfig --> UpstreamResolver
-    UpstreamResolver --> IntegratedTool
-```
-
----
-
-## Key Design Principles
-
-- Fully reactive (WebFlux + Reactor)
-- Strict multi-tenant issuer validation
-- Pluggable upstream resolution per tool
-- Centralized security enforcement at the edge
-- API key rate limiting for external APIs
-- Optimized Netty socket configuration
-- Clean separation between security, routing, and proxy concerns
-
----
-
-## Conclusion
-
-The **Gateway Service Core Security And Routing** module is the secure, reactive edge of the OpenFrame platform. It combines:
-
-- JWT-based multi-tenant authentication
-- Role-based authorization
-- API key validation and rate limiting
-- WebSocket proxying and decoration
-- Intelligent upstream resolution
-
-It ensures that all traffic entering the platform is authenticated, authorized, rate-limited, and routed efficiently to the correct internal or integrated service.
\ No newline at end of file
diff --git a/docs/reference/architecture/management-service-core-initializers-and-schedulers/management-service-core-initializers-and-schedulers.md b/docs/reference/architecture/management-service-core-initializers-and-schedulers/management-service-core-initializers-and-schedulers.md
deleted file mode 100644
index 2d3ed0a48..000000000
--- a/docs/reference/architecture/management-service-core-initializers-and-schedulers/management-service-core-initializers-and-schedulers.md
+++ /dev/null
@@ -1,433 +0,0 @@
-# Management Service Core Initializers And Schedulers
-
-The **Management Service Core Initializers And Schedulers** module is responsible for bootstrapping, orchestrating, and maintaining background operational workflows across the OpenFrame platform. It ensures that required configuration artifacts, streams, secrets, scripts, and distributed jobs are initialized correctly at startup and remain consistent throughout runtime.
-
-This module acts as the operational backbone for:
-
-- System bootstrapping (initial secrets, client configuration, tool agents)
-- Distributed scheduling with cluster-safe locking
-- Stream and messaging initialization (NATS)
-- External tool orchestration (e.g., Tactical RMM)
-- Maintenance and retry workflows
-- Pinot resynchronization and fleet setup tasks
-
----
-
-## Architectural Overview
-
-The module is structured into five major concerns:
-
-1. **Configuration Layer** – Enables scheduling, retries, and distributed locks.
-2. **Initializers** – Bootstrap critical data and external integrations at startup.
-3. **Schedulers** – Periodic maintenance and retry workflows.
-4. **Controllers** – Operational endpoints for manual triggers.
-5. **Processors & Services** – Extension points and domain orchestration logic.
-
-```mermaid
-flowchart TD
-    subgraph ConfigLayer["Configuration Layer"]
-        MgmtConfig["ManagementConfiguration"]
-        RetryConfig["RetryConfiguration"]
-        ShedLock["ShedLockConfig"]
-    end
-
-    subgraph Initializers["Startup Initializers"]
-        SecretInit["AgentRegistrationSecretInitializer"]
-        AgentInit["IntegratedToolAgentInitializer"]
-        NatsInit["NatsStreamConfigurationInitializer"]
-        ClientInit["OpenFrameClientConfigurationInitializer"]
-        TacticalInit["TacticalRmmScriptsInitializer"]
-    end
-
-    subgraph Schedulers["Background Schedulers"]
-        VersionFallback["AgentVersionUpdatePublishFallbackScheduler"]
-        ApiKeySync["ApiKeyStatsSyncScheduler"]
-        Heartbeat["DeviceHeartbeatOfflineDetectionScheduler"]
-        FleetMdm["FleetMdmSetupScheduler"]
-    end
-
-    subgraph Controllers["Operational Controllers"]
-        ToolCtrl["IntegratedToolController"]
-        PinotCtrl["DevicePinotResyncController"]
-        ReleaseCtrl["ReleaseVersionController"]
-    end
-
-    MgmtConfig --> Initializers
-    ShedLock --> Schedulers
-    RetryConfig --> Schedulers
-    Controllers --> Schedulers
-    Initializers --> Schedulers
-```
-
----
-
-# 1. Configuration Layer
-
-## ManagementConfiguration
-
-Provides the base Spring configuration for the module.
-
-Key responsibilities:
-- Component scanning across `com.openframe`
-- Excludes `CassandraHealthIndicator` to avoid unnecessary health wiring
-- Exposes a `PasswordEncoder` using BCrypt for secure hashing
-
-This ensures secure secret generation and compatibility with other security modules.
-
----
-
-## RetryConfiguration
-
-Enables Spring Retry using:
-
-```text
-@EnableRetry
-```
-
-This allows services and schedulers to use retry semantics for transient failures (e.g., network, external systems, Redis, NATS).
-
----
-
-## ShedLockConfig
-
-Enables:
-
-- `@EnableScheduling`
-- `@EnableSchedulerLock`
-
-Provides a Redis-backed distributed `LockProvider`.
-
-### Tenant-Scoped Locking
-
-Lock keys follow the pattern:
-
-```text
-of:{tenantId}:job-lock:<environment>:<lockName>
-```
-
-This ensures:
-- No duplicate scheduler execution across clustered nodes
-- Isolation per tenant
-- Environment separation
-
-```mermaid
-flowchart LR
-    Scheduler["Scheduled Job"] --> LockProvider["RedisLockProvider"]
-    LockProvider --> Redis[("Redis")]
-    Redis --> LockKey["Tenant Scoped Lock Key"]
-```
-
----
-
-# 2. Startup Initializers
-
-All initializers implement `ApplicationRunner`, meaning they execute after Spring Boot startup.
-
----
-
-## AgentRegistrationSecretInitializer
-
-Ensures an initial `AgentRegistrationSecret` exists at startup.
-
-Flow:
-
-```mermaid
-flowchart TD
-    Start["Application Startup"] --> SecretInit["AgentRegistrationSecretInitializer"]
-    SecretInit --> Service["AgentRegistrationSecretManagementService"]
-    Service --> Create["createInitialSecret()"]
-    Create --> Processor["DefaultAgentRegistrationSecretManagementProcessor"]
-```
-
-Features:
-- Idempotent secret creation
-- Pluggable post-processing via `AgentRegistrationSecretManagementProcessor`
-- Safe failure handling
-
----
-
-## IntegratedToolAgentInitializer
-
-Loads agent configurations from classpath resources.
-
-Responsibilities:
-- Reads JSON configuration files
-- Maps to `IntegratedToolAgentConfiguration`
-- Updates persisted configuration via `IntegratedToolAgentService`
-- Fails fast if no configuration is defined
-
-This guarantees consistent tool-agent configuration across environments.
-
----
-
-## NatsStreamConfigurationInitializer
-
-Pre-provisions required NATS streams:
-
-- TOOL_INSTALLATION
-- CLIENT_UPDATE
-- TOOL_UPDATE
-- TOOL_CONNECTIONS
-- INSTALLED_AGENTS
-
-Each stream defines:
-- Subjects (wildcard-based routing)
-- File storage
-- Retention policy
-
-Also supports extension via `AdditionalStreamConfigurationProvider`.
-
-```mermaid
-flowchart TD
-    Init["NatsStreamConfigurationInitializer"] --> DefaultStreams["Default Stream Configurations"]
-    Init --> Additional["AdditionalStreamConfigurationProvider"]
-    DefaultStreams --> NatsService["NatsStreamManagementService"]
-    Additional --> NatsService
-```
-
----
-
-## OpenFrameClientConfigurationInitializer
-
-Loads the default client configuration from:
-
-```text
-agent-configurations/client-configuration.json
-```
-
-Steps:
-1. Deserialize JSON
-2. Assign default ID
-3. Persist via `OpenFrameClientConfigurationService`
-
-Ensures the client always has a canonical configuration baseline.
-
----
-
-## TacticalRmmScriptsInitializer
-
-Bootstraps PowerShell scripts inside Tactical RMM.
-
-Workflow:
-
-```mermaid
-flowchart TD
-    Startup["Application Startup"] --> LoadTool["Load Tactical RMM Tool"]
-    LoadTool --> FetchScripts["Fetch Existing Scripts"]
-    FetchScripts --> Compare["Compare by Name"]
-    Compare -->|"Missing"| Create["Create Script"]
-    Compare -->|"Exists"| Update["Update Script"]
-```
-
-Features:
-- Loads script bodies from classpath
-- Idempotent create-or-update behavior
-- Uses API key stored in IntegratedTool
-- Logs per-script success/failure
-
-This guarantees consistent automation availability for OpenFrame client updates.
-
----
-
-# 3. Background Schedulers
-
-Schedulers run conditionally based on configuration properties and use ShedLock for distributed safety when needed.
-
----
-
-## AgentVersionUpdatePublishFallbackScheduler
-
-Purpose: Retry publishing client and tool-agent updates when previous attempts failed.
-
-Key concepts:
-- Checks `PublishState`
-- Retries until `maxPublishAttempts`
-- Publishes via NATS publishers
-
-```mermaid
-flowchart TD
-    Tick["Scheduled Tick"] --> ClientCheck["Check Client PublishState"]
-    ClientCheck --> RetryClient["Publish If Needed"]
-    Tick --> AgentCheck["Check Tool Agents"]
-    AgentCheck --> RetryAgent["Publish If Needed"]
-```
-
-This ensures eventual consistency for version update propagation.
-
----
-
-## ApiKeyStatsSyncScheduler
-
-Synchronizes API key statistics from Redis to MongoDB.
-
-Features:
-- Distributed lock (`apiKeyStatsSync`)
-- Configurable interval
-- Safe retry behavior
-
-Ensures durable persistence of usage metrics.
-
----
-
-## DeviceHeartbeatOfflineDetectionScheduler
-
-Periodically marks stale devices as offline.
-
-Flow:
-
-```mermaid
-flowchart LR
-    Scheduler["Heartbeat Scheduler"] --> Service["DeviceHeartbeatOfflineDetectionService"]
-    Service --> Mongo[("MongoDB Device Records")]
-```
-
-This keeps device health states accurate.
-
----
-
-## FleetMdmSetupScheduler
-
-Ensures Fleet MDM server is configured and API tokens are generated when necessary.
-
-Logic:
-- Looks up `fleetmdm-server` tool
-- Runs setup logic if present
-- Retries on failure
-
-This supports automated fleet provisioning.
-
----
-
-# 4. Operational Controllers
-
-These controllers provide operational endpoints for manual intervention.
-
----
-
-## IntegratedToolController
-
-Endpoint base: `/v1/tools`
-
-Responsibilities:
-- Retrieve tool configurations
-- Save tool configuration
-- Conditionally create/update Debezium connectors
-- Execute post-save hooks
-
-```mermaid
-flowchart TD
-    Client["API Client"] --> Controller["IntegratedToolController"]
-    Controller --> Save["IntegratedToolService.saveTool()"]
-    Save --> TenantCheck["TenantIdProvider"]
-    TenantCheck -->|"Registered"| Debezium["DebeziumService"]
-    Save --> Hooks["IntegratedToolPostSaveHook"]
-```
-
-Key design detail:
-- Debezium connectors are deferred until tenant registration.
-
----
-
-## DevicePinotResyncController
-
-Endpoint: `/v1/devices/pinot-resync`
-
-Purpose:
-- Replays all machines to Pinot
-- Uses `MachineTagEventService.processMachineSaveAll`
-
-This is typically used for analytics rehydration or recovery.
-
----
-
-## ReleaseVersionController
-
-Endpoint: `/v1/cluster-registrations`
-
-Delegates version processing to `ReleaseVersionService`.
-
-Intended to coordinate cluster-level version awareness and propagation.
-
----
-
-# 5. Services and Extension Points
-
-## OpenFrameClientVersionUpdateService
-
-Currently serves as a coordination entry point for client version publishing.
-
-Uses:
-- `OpenFrameClientUpdatePublisher`
-
-Designed for future expansion to centralize version update orchestration.
-
----
-
-## IntegratedToolPostSaveHook
-
-A lightweight extension mechanism:
-
-```text
-void onToolSaved(String toolId, IntegratedTool tool)
-```
-
-Advantages:
-- No Spring event overhead
-- Simple service-specific side effects
-- Clean separation of concerns
-
----
-
-## DefaultAgentRegistrationSecretManagementProcessor
-
-Default implementation used when no custom processor is defined.
-
-Behavior:
-- Logs secret creation
-- Supports override via Spring bean replacement
-
----
-
-# Runtime Interaction Summary
-
-The module ensures:
-
-1. Startup is safe and idempotent.
-2. Distributed jobs execute only once per cluster.
-3. External systems (NATS, Tactical RMM, Debezium) are reconciled.
-4. Retry and fallback logic guarantee eventual consistency.
-5. Operational APIs allow manual recovery and resync.
-
-```mermaid
-flowchart TD
-    Boot["Application Boot"] --> Initializers
-    Initializers --> Messaging["NATS Streams Ready"]
-    Messaging --> Schedulers
-    Schedulers --> External["External Systems"]
-    Controllers --> External
-```
-
----
-
-# Key Design Principles
-
-- **Idempotency First** – Initializers and schedulers tolerate repeated execution.
-- **Distributed Safety** – ShedLock prevents duplicate execution.
-- **Tenant Isolation** – Lock keys and processing are tenant-scoped.
-- **Eventual Consistency** – Fallback schedulers ensure propagation.
-- **Extensibility** – Hooks and processors enable modular extension.
-
----
-
-# Conclusion
-
-The **Management Service Core Initializers And Schedulers** module is the operational orchestrator of OpenFrame. It ensures that the system boots correctly, remains consistent across distributed nodes, maintains external integrations, and continuously reconciles state through scheduled processes.
-
-Without this module, OpenFrame would lack:
-
-- Safe distributed background processing
-- Automated stream and tool provisioning
-- Reliable publish retry mechanisms
-- Operational recovery endpoints
-
-It is a foundational module enabling stable, self-healing, multi-tenant management operations.
\ No newline at end of file
diff --git a/docs/reference/architecture/security-core-and-oauth-bff/security-core-and-oauth-bff.md b/docs/reference/architecture/security-core-and-oauth-bff/security-core-and-oauth-bff.md
deleted file mode 100644
index 95246761a..000000000
--- a/docs/reference/architecture/security-core-and-oauth-bff/security-core-and-oauth-bff.md
+++ /dev/null
@@ -1,351 +0,0 @@
-# Security Core And Oauth Bff
-
-## Overview
-
-The **Security Core And Oauth Bff** module provides the foundational security building blocks for the OpenFrame platform. It combines:
-
-- JWT encoding and decoding infrastructure
-- RSA key configuration and loading
-- PKCE (Proof Key for Code Exchange) utilities
-- OAuth2 Backend-for-Frontend (BFF) endpoints
-- Redirect resolution and state management
-
-This module acts as the bridge between the platform’s Authorization Server, Gateway, and frontend clients. It centralizes token handling, cookie management, and OAuth flows while remaining configurable and extensible.
-
----
-
-## Architectural Role in the Platform
-
-At runtime, Security Core And Oauth Bff sits between:
-
-- Frontend clients (browser-based applications)
-- The Authorization Server
-- The Gateway layer
-
-It is responsible for:
-
-- Initiating OAuth2 authorization flows
-- Managing PKCE and state
-- Exchanging authorization codes for tokens
-- Storing tokens securely in HTTP-only cookies
-- Refreshing and revoking tokens
-- Providing JWT encoder/decoder beans for internal services
-
-### High-Level Architecture
-
-```mermaid
-flowchart LR
-    Browser["Browser Client"] -->|"GET /oauth/login"| Bff["OAuth BFF Controller"]
-    Bff -->|"Redirect to authorize"| AuthServer["Authorization Server"]
-    AuthServer -->|"Callback with code"| Bff
-    Bff -->|"Exchange code for tokens"| AuthServer
-    Bff -->|"Set HttpOnly Cookies"| Browser
-
-    Browser -->|"API calls with cookies"| Gateway["Gateway Service"]
-    Gateway -->|"Validate JWT"| JwtDecoder["JwtDecoder Bean"]
-```
-
----
-
-## Core Components
-
-### 1. JwtSecurityConfig
-
-**Class:** `JwtSecurityConfig`
-
-This Spring configuration class provides the core JWT infrastructure:
-
-- `JwtEncoder` bean using `NimbusJwtEncoder`
-- `JwtDecoder` bean using `NimbusJwtDecoder`
-- RSA-based signing and verification
-
-#### Responsibilities
-
-- Build a JWK set from configured RSA keys
-- Expose a `JwtEncoder` for signing tokens
-- Expose a `JwtDecoder` for validating tokens
-
-### JWT Bean Configuration Flow
-
-```mermaid
-flowchart TD
-    JwtConfig["JwtConfig"] -->|"loadPublicKey()"| PublicKey["RSAPublicKey"]
-    JwtConfig -->|"loadPrivateKey()"| PrivateKey["RSAPrivateKey"]
-
-    PublicKey --> RsaKey["RSAKey Builder"]
-    PrivateKey --> RsaKey
-
-    RsaKey --> JwkSet["JWKSet"]
-    JwkSet --> JwtEncoder["NimbusJwtEncoder"]
-
-    PublicKey --> JwtDecoder["NimbusJwtDecoder"]
-```
-
-This design ensures:
-
-- Strong asymmetric cryptography (RSA)
-- Compatibility with Spring Security OAuth2 Resource Server
-- Clean separation of configuration and usage
-
----
-
-### 2. JwtConfig
-
-**Class:** `JwtConfig`
-
-`JwtConfig` is a Spring `@ConfigurationProperties` service that binds properties under the `jwt` prefix.
-
-#### Properties
-
-- `publicKey`
-- `privateKey`
-- `issuer`
-- `audience`
-
-#### Key Responsibilities
-
-- Load RSA public key
-- Parse and decode PEM-encoded private key
-- Produce `RSAPublicKey` and `RSAPrivateKey` instances
-
-The private key loading process:
-
-```mermaid
-flowchart TD
-    PemString["PEM Private Key"] --> StripHeaders["Remove BEGIN/END markers"]
-    StripHeaders --> Base64Decode["Base64 Decode"]
-    Base64Decode --> KeySpec["PKCS8EncodedKeySpec"]
-    KeySpec --> KeyFactory["KeyFactory RSA"]
-    KeyFactory --> RsaPrivate["RSAPrivateKey"]
-```
-
-This encapsulation prevents direct cryptographic handling throughout the codebase and centralizes key logic.
-
----
-
-### 3. SecurityConstants
-
-**Class:** `SecurityConstants`
-
-Defines standardized names used across OAuth flows:
-
-- `authorization` query parameter
-- `access_token`
-- `refresh_token`
-- `Access-Token` header
-- `Refresh-Token` header
-
-This prevents string duplication and ensures consistent token propagation between:
-
-- BFF controller
-- Cookie service
-- Gateway filters
-
----
-
-### 4. PKCEUtils
-
-**Class:** `PKCEUtils`
-
-Utility class implementing PKCE for secure OAuth2 Authorization Code flows.
-
-#### Provided Methods
-
-- `generateState()` – 128-bit random value
-- `generateCodeVerifier()` – 256-bit random value
-- `generateCodeChallenge()` – SHA-256 based challenge
-- `urlEncode()` – Safe redirect parameter encoding
-
-### PKCE Flow
-
-```mermaid
-flowchart TD
-    Verifier["Code Verifier (random 32 bytes)"] --> Hash["SHA-256"]
-    Hash --> Challenge["Base64URL Encode"]
-
-    Challenge -->|"Sent to Authorization Server"| AuthServer["Authorization Server"]
-    Verifier -->|"Stored by BFF"| BffStore["State JWT / Cookie"]
-```
-
-This ensures:
-
-- Protection against authorization code interception
-- CSRF mitigation via state parameter
-- Strong cryptographic randomness via `SecureRandom`
-
----
-
-## OAuth Backend-For-Frontend (BFF)
-
-### OAuthBffController
-
-**Class:** `OAuthBffController`
-
-This is the central HTTP interface for browser-based authentication.
-
-It is conditionally enabled via:
-
-- `openframe.gateway.oauth.enable=true`
-
-### Exposed Endpoints
-
-| Endpoint | Method | Purpose |
-|-----------|--------|----------|
-| `/oauth/login` | GET | Start OAuth flow |
-| `/oauth/continue` | GET | Continue flow without clearing session |
-| `/oauth/callback` | GET | Handle authorization code |
-| `/oauth/refresh` | POST | Refresh tokens |
-| `/oauth/logout` | GET | Revoke refresh token and clear cookies |
-| `/oauth/dev-exchange` | GET | Exchange development ticket |
-
----
-
-## End-to-End Login Flow
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant BFF as OAuth BFF Controller
-    participant Auth as Authorization Server
-
-    Browser->>BFF: GET /oauth/login
-    BFF->>Auth: Redirect with state and PKCE challenge
-    Auth->>Browser: Login UI
-    Auth->>BFF: Callback with code and state
-    BFF->>Auth: Exchange code for tokens
-    Auth->>BFF: Access and Refresh tokens
-    BFF->>Browser: Set HttpOnly cookies and redirect
-```
-
-### Key Mechanics
-
-1. State is signed as a JWT.
-2. State cookie is stored with configurable TTL.
-3. Tokens are returned as HTTP-only cookies.
-4. Optional development ticket injection.
-5. Errors redirect to configured error URL.
-
----
-
-## Token Refresh Flow
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant BFF
-    participant Auth as Authorization Server
-
-    Browser->>BFF: POST /oauth/refresh
-    BFF->>Auth: Refresh token request
-    Auth->>BFF: New tokens
-    BFF->>Browser: Set new cookies
-```
-
-Features:
-
-- Supports refresh via cookie or header
-- Supports tenant-based lookup
-- Returns 401 if token missing or invalid
-
----
-
-## Logout Flow
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant BFF
-    participant Auth as Authorization Server
-
-    Browser->>BFF: GET /oauth/logout
-    BFF->>Auth: Revoke refresh token
-    BFF->>Browser: Clear auth cookies
-```
-
-Logout ensures:
-
-- Refresh token revocation
-- Cookie invalidation
-- Stateless cleanup
-
----
-
-## Redirect Resolution
-
-### DefaultRedirectTargetResolver
-
-Provides fallback redirect resolution logic:
-
-1. Use explicit `redirectTo` parameter if provided
-2. Fallback to `Referer` header
-3. Default to `/`
-
-```mermaid
-flowchart TD
-    Requested["Requested redirectTo"] -->|"Has value"| UseRequested["Use requested value"]
-    Requested -->|"Empty"| RefererCheck["Check Referer header"]
-    RefererCheck -->|"Present"| UseReferer["Use Referer"]
-    RefererCheck -->|"Missing"| DefaultRoot["Use /"]
-```
-
-This allows safe continuation after login without tight frontend coupling.
-
----
-
-## Security Design Principles
-
-Security Core And Oauth Bff follows these principles:
-
-- **Asymmetric cryptography** for JWT signing
-- **Short-lived state tokens** for CSRF prevention
-- **PKCE enforcement** for public clients
-- **HttpOnly cookie storage** for tokens
-- **Tenant-aware flows**
-- **Reactive non-blocking controllers** using Project Reactor
-
----
-
-## Configuration Overview
-
-### JWT Properties
-
-```text
-jwt.publicKey.value=<PEM_PUBLIC_KEY>
-jwt.privateKey.value=<PEM_PRIVATE_KEY>
-jwt.issuer=openframe
-jwt.audience=openframe-api
-```
-
-### OAuth BFF Properties
-
-```text
-openframe.gateway.oauth.enable=true
-openframe.gateway.oauth.state-cookie-ttl-seconds=180
-openframe.gateway.oauth.dev-ticket-enabled=true
-openframe.auth.error-url=/auth/error
-```
-
----
-
-## Extension Points
-
-Security Core And Oauth Bff is designed to be extended:
-
-- Replace `RedirectTargetResolver`
-- Customize cookie behavior via `CookieService`
-- Extend `OAuthBffService`
-- Plug in alternative key loading mechanisms
-
----
-
-## Summary
-
-The **Security Core And Oauth Bff** module provides:
-
-- JWT cryptographic infrastructure
-- OAuth2 BFF endpoints
-- PKCE and CSRF protection
-- Token refresh and revocation logic
-- Redirect safety and cookie management
-
-It is a foundational module that secures the entire OpenFrame request lifecycle, enabling multi-tenant, OAuth2-compliant, and browser-safe authentication flows.
\ No newline at end of file
diff --git a/docs/reference/architecture/stream-service-core-kafka-and-handlers/stream-service-core-kafka-and-handlers.md b/docs/reference/architecture/stream-service-core-kafka-and-handlers/stream-service-core-kafka-and-handlers.md
deleted file mode 100644
index cc6d0eb16..000000000
--- a/docs/reference/architecture/stream-service-core-kafka-and-handlers/stream-service-core-kafka-and-handlers.md
+++ /dev/null
@@ -1,356 +0,0 @@
-# Stream Service Core Kafka And Handlers
-
-## Overview
-
-The **Stream Service Core Kafka And Handlers** module is the event ingestion, normalization, enrichment, and distribution backbone of the OpenFrame platform.
-
-It is responsible for:
-
-- Consuming Debezium CDC events from integrated tools (MeshCentral, Tactical RMM, Fleet MDM)
-- Deserializing tool-specific payloads into unified internal models
-- Enriching events with tenant, organization, and device metadata
-- Mapping tool-specific event types to unified event types
-- Persisting events (e.g., Cassandra)
-- Republishing normalized events to outbound Kafka topics
-- Running Kafka Streams pipelines for activity enrichment
-
-This module acts as the **bridge between external tool ecosystems and the unified OpenFrame event model** used across API, analytics, notifications, and management services.
-
----
-
-## High-Level Architecture
-
-```mermaid
-flowchart LR
-    subgraph Tools["Integrated Tools"]
-        MeshCentral["MeshCentral"]
-        Tactical["Tactical RMM"]
-        Fleet["Fleet MDM"]
-    end
-
-    subgraph KafkaIn["Inbound Kafka Topics"]
-        InTopics["Debezium Topics"]
-    end
-
-    subgraph StreamCore["Stream Service Core Kafka And Handlers"]
-        Listener["JsonKafkaListener"]
-        Processor["GenericJsonMessageProcessor"]
-        Deserializer["Tool Event Deserializers"]
-        Enrichment["IntegratedToolDataEnrichmentService"]
-        Mapper["EventTypeMapper"]
-        Handler["DebeziumMessageHandler"]
-        CassandraHandler["DebeziumCassandraMessageHandler"]
-        TenantKafkaHandler["TenantDebeziumKafkaMessageHandler"]
-    end
-
-    subgraph Storage["Storage & Downstream"]
-        Cassandra["Cassandra UnifiedLogEvent"]
-        KafkaOut["Outbound Kafka Topics"]
-    end
-
-    MeshCentral --> InTopics
-    Tactical --> InTopics
-    Fleet --> InTopics
-
-    InTopics --> Listener
-    Listener --> Processor
-    Processor --> Deserializer
-    Deserializer --> Enrichment
-    Enrichment --> Mapper
-    Mapper --> Handler
-
-    Handler --> CassandraHandler
-    Handler --> TenantKafkaHandler
-
-    CassandraHandler --> Cassandra
-    TenantKafkaHandler --> KafkaOut
-```
-
----
-
-## Processing Flow
-
-The module follows a structured event pipeline:
-
-```mermaid
-flowchart TD
-    A["Kafka Debezium Event"] --> B["JsonKafkaListener"]
-    B --> C["GenericJsonMessageProcessor"]
-    C --> D["Tool-Specific Deserializer"]
-    D --> E["Unified DeserializedDebeziumMessage"]
-    E --> F["IntegratedToolDataEnrichmentService"]
-    F --> G["EventTypeMapper"]
-    G --> H["DebeziumMessageHandler"]
-    H --> I["Destination Handler"]
-    I --> J["Cassandra or Kafka"]
-```
-
-### Key Stages
-
-1. **Kafka Consumption** – `JsonKafkaListener` consumes multi-topic integrated tool events.
-2. **Deserialization** – Tool-specific deserializers convert raw CDC JSON into structured internal messages.
-3. **Enrichment** – Tenant, machine, and organization metadata are resolved via Redis cache services.
-4. **Type Mapping** – `EventTypeMapper` maps tool-specific source types into `UnifiedEventType`.
-5. **Handling & Dispatch** – Generic and specialized handlers route events to storage or outbound topics.
-
----
-
-## Kafka Configuration Layer
-
-### KafkaConfig
-
-Provides:
-
-- `Converter<byte[], MessageType>` for resolving message type headers.
-- Integration with Spring Kafka infrastructure.
-
-This enables dynamic routing of heterogeneous tool events through a unified processing layer.
-
-### KafkaStreamsConfig
-
-Enables Kafka Streams processing when `kafka.stream.enabled=true`.
-
-Key responsibilities:
-
-- Configures `application.id` (namespaced by cluster ID)
-- Defines custom `Serde` for:
-  - `ActivityMessage`
-  - `HostActivityMessage`
-- Configures state store, threading, and processing guarantees
-
-Processing guarantee: `AT_LEAST_ONCE`
-
----
-
-## Kafka Streams: Activity Enrichment
-
-`ActivityEnrichmentService` builds a Kafka Streams topology that:
-
-- Consumes:
-  - Fleet activity topic
-  - Fleet host activity topic
-- Performs a time-windowed left join
-- Enriches activity events with host information
-- Adds required Kafka headers
-- Publishes enriched events back to an inbound topic
-
-```mermaid
-flowchart LR
-    ActivityTopic["Fleet Activities"] --> Join
-    HostActivityTopic["Fleet Host Activities"] --> Join
-    Join["Left Join (5s Window)"] --> Enriched["Enriched ActivityMessage"]
-    Enriched --> HeaderAdder["Add MESSAGE_TYPE_HEADER"]
-    HeaderAdder --> OutputTopic["Fleet MDM Events Topic"]
-```
-
-This allows Fleet policy and activity events to be normalized before entering the main Debezium event processing path.
-
----
-
-## Tool-Specific Deserializers
-
-Each integrated tool has a dedicated deserializer extending `IntegratedToolEventDeserializer`.
-
-### Fleet MDM
-
-- `FleetEventDeserializer`
-- `FleetPolicyActivityDeserializer`
-- `FleetPolicyMembershipEventDeserializer`
-- `FleetQueryResultEventDeserializer`
-
-Responsibilities:
-
-- Extract agent ID
-- Resolve policy/query metadata via cache services
-- Build structured `result` or `error` JSON
-- Normalize timestamps using `TimestampParser`
-- Assign correct `MessageType`
-
-### Tactical RMM
-
-- `TrmmAgentHistoryEventDeserializer`
-- `TrmmAuditEventDeserializer`
-- `TrmmTaskResultEventDeserializer`
-
-Responsibilities:
-
-- Resolve primary key IDs to logical agent IDs via cache
-- Parse script results and command outputs
-- Convert execution results into structured JSON payloads
-
-### MeshCentral
-
-- `MeshCentralEventDeserializer`
-
-Responsibilities:
-
-- Parse nested JSON payloads
-- Extract `etype.action` composite source type
-- Extract tenant domain for shared cluster resolution
-
----
-
-## Unified Event Mapping
-
-`EventTypeMapper` maps:
-
-- `IntegratedToolType`
-- Source event type string
-
-To:
-
-- `UnifiedEventType`
-
-```mermaid
-flowchart LR
-    ToolType["IntegratedToolType"] --> Key
-    SourceType["Source Event Type"] --> Key
-    Key["tool:sourceType"] --> Mapper["EventTypeMapper"]
-    Mapper --> Unified["UnifiedEventType"]
-```
-
-If no mapping exists, the system falls back to `UNKNOWN`.
-
-This ensures:
-
-- Cross-tool normalization
-- Consistent severity assignment
-- Unified downstream analytics
-
----
-
-## Data Enrichment Layer
-
-`IntegratedToolDataEnrichmentService` enriches deserialized events with:
-
-- Machine ID
-- Hostname
-- Organization ID and name
-- Tenant ID
-
-It integrates with:
-
-- Redis cache via `MachineIdCacheService`
-- Tenant resolution via `TenantIdProvider`
-- Optional `ClusterTenantIdResolver` (shared cluster mode)
-
-```mermaid
-flowchart TD
-    Event["DeserializedDebeziumMessage"] --> MachineLookup["MachineIdCacheService"]
-    MachineLookup --> OrgLookup["Organization Cache"]
-    OrgLookup --> TenantResolution["TenantIdProvider or ClusterTenantIdResolver"]
-    TenantResolution --> Enriched["IntegratedToolEnrichedData"]
-```
-
-This ensures that all downstream consumers receive fully contextualized events.
-
----
-
-## Message Handling Framework
-
-### GenericMessageHandler
-
-Provides a template pattern:
-
-- Validate message
-- Transform to destination model
-- Resolve operation type (CREATE, UPDATE, DELETE, READ)
-- Route to appropriate handler method
-
-### DebeziumMessageHandler
-
-Specialization for CDC events:
-
-- Extracts operation code from Debezium payload (`c`, `u`, `d`, `r`)
-- Maps to `OperationType`
-
-### DebeziumCassandraMessageHandler
-
-Transforms events into `UnifiedLogEvent` and writes to Cassandra.
-
-Responsibilities:
-
-- Construct partition key
-- Populate severity and unified type
-- Persist to `UnifiedLogEventRepository`
-
-### TenantDebeziumKafkaMessageHandler
-
-Publishes validated events to tenant-scoped outbound Kafka topics using `OssTenantRetryingKafkaProducer`.
-
----
-
-## Validation Layer
-
-`TenantIdRequiredDebeziumEventValidator` ensures:
-
-- All events have a resolved tenant ID
-- Events without tenant context are dropped
-
-This prevents cross-tenant contamination and guarantees multi-tenant isolation.
-
----
-
-## Timestamp Normalization
-
-`TimestampParser` standardizes ISO-8601 timestamps into epoch milliseconds.
-
-All integrated tools rely on Debezium ISO format, ensuring:
-
-- Consistent event ordering
-- Reliable partitioning
-- Accurate time-based queries
-
----
-
-## Multi-Tenant and Cluster Modes
-
-The module supports two deployment modes:
-
-1. **Tenant Cluster Mode**
-   - One tenant per Kafka cluster
-   - `TenantIdProvider` resolves tenant ID directly
-
-2. **Shared Cluster Mode**
-   - Multiple tenants share Kafka
-   - `ClusterTenantIdResolver` maps tool-specific domain identifiers to canonical tenant IDs
-
-This design ensures compatibility across SaaS and dedicated deployments.
-
----
-
-## Integration with Other Modules
-
-This module integrates tightly with:
-
-- Data Mongo domain model (for unified event storage references)
-- Data Cassandra repositories (for log persistence)
-- Data Kafka configuration and retry (for producer reliability)
-- Data Redis cache (for machine and organization lookups)
-- Management and API services (downstream consumers of normalized events)
-
-It serves as the **event normalization boundary** between external tools and the internal OpenFrame domain model.
-
----
-
-## Summary
-
-The **Stream Service Core Kafka And Handlers** module provides:
-
-- Reliable Kafka ingestion
-- Tool-specific deserialization
-- Unified event type normalization
-- Tenant-aware enrichment
-- Cassandra persistence
-- Kafka republishing
-- Kafka Streams activity joins
-
-It is a critical infrastructure layer enabling:
-
-- Cross-tool observability
-- Unified audit trails
-- Analytics and reporting
-- Real-time notification pipelines
-- Multi-tenant isolation guarantees
-
-Without this module, the OpenFrame platform would lack a consistent, normalized, and tenant-safe event backbone.
\ No newline at end of file

From 391a01511858897933f6882ba7fc9be724e74499 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 19:17:32 +0000
Subject: [PATCH 3/7] docs: Stage 1 - Inline documentation (402 files) [skip
 ci]

---
 .../dto/command/.CancelDispatchResponse.md    |  16 +++
 .../api/dto/command/.CancelExecutionInput.md  |  22 ++++
 .../dto/command/.CommandDispatchResponse.md   |  22 ++++
 .../api/dto/command/.RunCommandInput.md       |  25 +++++
 .../api/dto/script/.CreateScriptInput.md      |  35 ++++++
 .../api/dto/script/.ScriptEnvVarInput.md      |  30 ++++++
 .../api/dto/script/.ScriptFilterInput.md      |  32 ++++++
 .../api/dto/script/.ScriptResponse.md         |  40 +++++++
 .../api/dto/script/.UpdateScriptInput.md      |  39 +++++++
 .../com/openframe/api/mapper/.ScriptMapper.md |  42 ++++++++
 .../.KnowledgeBaseTempAttachmentService.md    |  67 ++++++------
 .../api/service/rmm/.ScriptService.md         |  45 ++++++++
 .../api/datafetcher/.CommandDataFetcher.md    |  50 +++++++++
 .../datafetcher/.NotificationDataFetcher.md   |  50 ++++-----
 .../api/datafetcher/.ScriptDataFetcher.md     |  48 +++++++++
 .../api/mapper/.GraphQLScriptMapper.md        |  33 ++++++
 .../service/.ForceToolAgentUpdateService.md   |  37 ++++---
 .../service/.ForceToolInstallationService.md  |  49 +++++----
 .../api/service/.NotificationService.md       |  54 +++++-----
 .../service/.ReleaseVersionQueryService.md    |  12 +--
 .../service/rmm/.CommandDispatchService.md    |  38 +++++++
 .../.NotificationDataFetcherIT.md             |  59 +++++------
 .../notification/.TestApprovalContext.md      |  33 +++---
 .../service/.NotificationServiceIT.md         |  71 ++++++-------
 .../openframe/api/mapper/.ScriptMapperTest.md |  39 +++++++
 .../rmm/.CommandDispatchServiceTest.md        |  43 ++++++++
 .../api/service/rmm/.ScriptServiceTest.md     |  47 ++++++++
 .../.OwnerCannotSwitchTenantException.md      |  19 ++++
 .../processor/.RegistrationProcessor.md       |  41 ++++---
 .../user/.InvitationRegistrationService.md    |  75 ++++++++-----
 .../openframe/client/config/.AsyncConfig.md   |  32 ++++++
 .../client/controller/.AgentController.md     |  52 +++++----
 .../dto/agent/.AgentRegistrationRequest.md    |  63 +++++------
 .../.InvalidClientSecretException.md          |  18 ++++
 .../listener/.MachineHeartbeatListener.md     |  47 ++++----
 .../listener/.ToolConnectionListener.md       |  51 +++++----
 .../client/service/.MachineStatusService.md   |  48 ++++-----
 .../.AgentRegistrationService.md              |  41 +++----
 ...gentRegistrationToolInstallationService.md |  38 +++----
 .../.OrganizationIdResolver.md                |  29 +++++
 .../validator/.ClientSecretValidator.md       |  35 ++++++
 .../client/controller/.AgentControllerTest.md |  58 +++++-----
 .../service/.AgentRegistrationServiceTest.md  |  54 +++++-----
 .../.OrganizationIdResolverTest.md            |  45 ++++++++
 .../validator/.ClientSecretValidatorTest.md   |  43 ++++++++
 .../impl/.MachineTagEventServiceImpl.md       |  57 +++++++---
 .../kafka/producer/.GenericKafkaProducer.md   |  52 ++++-----
 .../openframe/data/document/.TenantScoped.md  |  34 ++++++
 .../agent/.AgentRegistrationSecret.md         |  32 +++---
 .../openframe/data/document/apikey/.ApiKey.md |  43 ++++----
 .../data/document/apikey/.ApiKeyStats.md      |  37 ++++---
 .../document/assignment/.ItemAssignment.md    |  52 ++++-----
 .../data/document/auth/.AuthInvitation.md     |  35 +++---
 .../openframe/data/document/auth/.AuthUser.md |  66 ++++++------
 .../.OpenFrameClientConfiguration.md          |  36 +++----
 .../document/connector/.ConnectorAlert.md     |  41 +++----
 .../openframe/data/document/device/.Device.md |  43 ++++----
 .../data/document/device/.Machine.md          |  43 ++++----
 .../data/document/event/.CoreEvent.md         |  33 +++---
 .../openframe/data/document/event/.Event.md   |  40 +++----
 .../event/.ExternalApplicationEvent.md        |  53 +++++-----
 .../installedagents/.InstalledAgent.md        |  30 +++---
 .../document/notification/.GenericContext.md  |  39 +++----
 .../notification/.NotificationContext.md      |  43 ++++----
 .../oauth/.MongoOAuth2Authorization.md        |  62 +++++------
 .../document/oauth/.MongoRegisteredClient.md  |  41 +++----
 .../data/document/oauth/.OAuthClient.md       |  40 ++++---
 .../data/document/oauth/.OAuthToken.md        |  27 +++--
 .../document/organization/.Organization.md    |  42 ++++----
 .../openframe/data/document/rmm/.Script.md    |  38 +++++++
 .../data/document/rmm/.ScriptEnvVar.md        |  30 ++++++
 .../data/document/rmm/.ScriptPlatform.md      |  30 ++++++
 .../data/document/rmm/.ScriptShell.md         |  25 +++++
 .../data/document/rmm/.ScriptStatus.md        |  30 ++++++
 .../document/rmm/filter/.ScriptQueryFilter.md |  27 +++++
 .../openframe/data/document/sso/.SSOConfig.md |  39 +++----
 .../com/openframe/data/document/tag/.Tag.md   |  41 ++++---
 .../data/document/tag/.TagAssignment.md       |  47 ++++----
 .../document/tenant/.SSOPerTenantConfig.md    |  28 +++--
 .../data/document/tenant/.TenantKey.md        |  43 ++++----
 .../data/document/ticket/.TempAttachment.md   |  44 ++++----
 .../openframe/data/document/ticket/.Ticket.md |  56 +++++-----
 .../data/document/ticket/.TicketAttachment.md |  27 +++--
 .../data/document/ticket/.TicketNote.md       |  34 +++---
 .../data/document/ticket/.TicketStatus.md     |  59 +++++------
 .../ticket/.TicketStatusDefinition.md         |  37 +++++++
 .../data/document/ticket/.TicketStatusKind.md |  34 ++++++
 .../ticket/filter/.TicketQueryFilter.md       |  38 ++++---
 .../data/document/tool/.IntegratedTool.md     |  48 ++++-----
 .../data/document/tool/.ToolConnection.md     |  48 ++++-----
 .../toolagent/.IntegratedToolAgent.md         |  47 ++++----
 .../data/document/user/.Invitation.md         |  40 +++----
 .../com/openframe/data/document/user/.User.md |  40 ++++---
 .../data/document/version/.ReleaseVersion.md  |  60 +++++------
 .../data/repository/.TenantAwareRepository.md |  36 +++++++
 .../tool/.BaseIntegratedToolRepository.md     |  51 ++++-----
 .../data/service/.DefaultTenantIdProvider.md  |  32 ++++++
 .../data/service/.TenantIdProvider.md         |  47 ++++++++
 .../tool/.ReactiveIntegratedToolRepository.md |  25 +++--
 .../data/config/.MongoInfraConfig.md          |  46 ++++++++
 .../openframe/data/config/.MongoSyncConfig.md |  55 ++++------
 .../config/.NotificationContextMongoConfig.md |  34 +++---
 .../data/config/.TenantAwareSyncConfig.md     |  24 +++++
 ....OpenFrameClientConfigurationRepository.md |  37 +++----
 .../.CustomNotificationRepository.md          |  50 +++++----
 .../.NotificationContextWriteConverter.md     |  45 ++++++++
 .../.NotificationReadStateRepository.md       |  41 ++++---
 .../impl/.CustomNotificationRepositoryImpl.md |  54 ++++++----
 .../oauth/.OAuthClientRepository.md           |  34 +++---
 .../repository/rmm/.CustomScriptRepository.md |  35 ++++++
 .../rmm/.CustomScriptRepositoryImpl.md        |  39 +++++++
 .../data/repository/rmm/.ScriptRepository.md  |  38 +++++++
 .../ticket/.CustomTicketRepository.md         |  50 +++++----
 .../ticket/.CustomTicketRepositoryImpl.md     |  65 ++++++------
 .../repository/ticket/.TicketRepository.md    |  63 ++++++-----
 .../.TicketStatusDefinitionRepository.md      |  46 ++++++++
 .../tool/.IntegratedToolRepository.md         |  39 ++++---
 .../.IntegratedToolAgentRepository.md         |  29 +++--
 .../version/.ReleaseVersionRepository.md      |  27 ++---
 .../seed/ticket/.TicketStatusSeedCatalog.md   |  30 ++++++
 .../service/.IntegratedToolAgentService.md    |  49 ++++-----
 .../data/service/.IntegratedToolService.md    |  52 ++++-----
 .../.OpenFrameClientConfigurationService.md   |  47 ++++----
 .../.NotificationReadStateService.md          |  41 +++----
 .../.NotificationContextDispatchIT.md         |  57 +++++-----
 .../notification/.TestExtendedContext.md      |  31 +++---
 .../performance/.NotificationLoadTestIT.md    |  53 +++++-----
 .../.NotificationReadStateIndexUsageIT.md     |  52 ++++-----
 ...ustomNotificationRepositoryPaginationIT.md |  74 ++++++-------
 .../repository/rmm/.ScriptRepositoryIT.md     |  33 ++++++
 .../support/.RmmIntegrationTestApplication.md |  40 +++++++
 .../.NotificationContextWriteConverterTest.md |  43 ++++++++
 .../.ToolAgentUpdateUpdatePublisher.md        |  57 +++-------
 .../.ToolInstallationNatsPublisher.md         |  34 +++---
 .../data/nats/rmm/model/.CancelMessage.md     |  24 +++++
 .../data/nats/rmm/model/.CommandMessage.md    |  30 ++++++
 .../rmm/publisher/.CommandNatsPublisher.md    |  39 +++++++
 .../publisher/.CommandNatsPublisherTest.md    |  45 ++++++++
 .../debezium/service/.DebeziumService.md      |  53 +++++-----
 .../openframe/core/exception/.ErrorCode.md    |  49 +++++----
 .../external/service/.RestProxyService.md     |  47 ++++----
 openframe-frontend-core/.tsup.config.md       |  59 +++++------
 .../components/.content-loading-container.md  |  52 +++++----
 .../src/components/.empty-state.md            |  49 ++++-----
 .../src/components/.faq-accordion.md          |  42 +++-----
 .../src/components/.footer-waitlist-button.md |  42 ++++----
 .../src/components/.index.md                  |  59 ++++++-----
 .../src/components/.logs-list.md              |  36 +++----
 .../src/components/.media-carousel.md         |  68 ++++++------
 .../src/components/.open-source-features.md   |  38 ++++---
 .../src/components/.vendor-icon.md            |  67 ++++++------
 .../src/components/.vendor-tag.md             |  80 +++++++-------
 .../src/components/.why-it-matters.md         |  43 ++++----
 .../src/components/chat/.chat-archive-page.md |  39 +++++++
 .../components/chat/.chat-attachment-bar.md   |  79 +++++---------
 .../src/components/chat/.chat-composer.md     |  60 +++++++++++
 .../src/components/chat/.chat-container.md    |  59 ++++++-----
 .../chat/.chat-header-icon-button.md          |  34 ++++++
 .../src/components/chat/.chat-input.md        |  78 +++++++-------
 .../components/chat/.chat-message-enhanced.md |  51 ++++-----
 .../src/components/chat/.chat-message-list.md |  56 +++-------
 .../src/components/chat/.chat-message-row.md  |  46 ++++++++
 .../components/chat/.chat-message-skeleton.md |  68 +++++++-----
 .../chat/.chat-panel-header-mobile.md         |  39 +++++++
 .../src/components/chat/.chat-panel-header.md |  40 +++++++
 .../components/chat/.chat-quick-action-row.md |  37 +++++++
 .../src/components/chat/.embeddable-chat.md   |  90 +++++++++-------
 .../src/components/chat/.guide-mode-banner.md |  36 +++++++
 .../src/components/chat/.guide-welcome.md     |  40 +++++++
 .../src/components/chat/.index.md             |  54 ++++++----
 .../components/chat/.mingo-chat-history.md    |  38 +++++++
 .../src/components/chat/.mingo-chat-modals.md |  46 ++++++++
 .../src/components/chat/.mingo-info-card.md   |  51 +++++++++
 .../components/chat/.mingo-onboarding-card.md |  73 +++++--------
 .../src/components/chat/.mingo-welcome.md     |  69 ++++++++++++
 .../chat/.nav-link-anchor-via-runtime.md      |  38 +++----
 .../chat/entity-cards/.blog-card.md           |  47 ++++----
 .../chat/entity-cards/.case-study-card.md     |  59 ++++-------
 .../chat/entity-cards/.chat-ticket-item.md    |  55 ++++++----
 .../entity-cards/.customer-interview-card.md  |  63 +++++------
 .../components/chat/entity-cards/.dispatch.md |  47 ++++----
 .../entity-cards/.github-activity-card.md     |  78 ++++++--------
 .../components/chat/entity-cards/.index.md    |  68 ++++++------
 .../entity-cards/.investor-update-card.md     |  42 ++++----
 .../entity-cards/.onboarding-guide-card.md    |  53 ++++------
 .../.product-release-card-defaults.md         |  53 ++++++----
 .../chat/entity-cards/.program-card.md        |  67 ++++++------
 .../entity-cards/.use-entity-card-link.md     |  40 +++++++
 .../.use-entity-card-placeholder.md           |  49 +++++++++
 .../chat/hooks/.use-chat-dialog-manager.md    |  53 ++++++++++
 .../chat/hooks/.use-chat-identity.md          |  59 +++++++----
 .../.use-jetstream-dialog-subscription.md     |  53 +++++-----
 .../chat/hooks/.use-nats-chat-adapter.md      | 100 +++++++++++-------
 .../hooks/.use-nats-dialog-subscription.md    |  80 +++++++-------
 .../chat/hooks/.use-slash-commands.md         |  54 +++++-----
 .../chat/hooks/.use-sse-chat-adapter.md       |  60 +++++++----
 .../chat/hooks/.use-unified-chat.md           |  54 ++++------
 .../src/components/chat/types/.chat.types.md  |  85 +++++++++------
 .../components/chat/types/.component.types.md |  65 +++++-------
 .../chat/types/.unified-chat-state.types.md   |  54 +++++-----
 .../chat/utils/.execute-navigation.md         |  63 +++++++++++
 .../src/components/chat/utils/.index.md       |  85 +++++++--------
 .../chat/utils/.nav-click-handler.md          |  52 ++++-----
 .../utils/.process-historical-messages.md     |  75 ++++++-------
 .../components/chat/utils/.source-row-cta.md  |  58 +++++-----
 .../src/components/features/.captions-url.md  |  28 +++++
 .../components/features/.changelog-manager.md |  64 ++++++-----
 .../features/.highlight-config-section.md     |  41 +++----
 .../src/components/features/.index.md         |  77 +++++++-------
 .../src/components/features/.mux-origins.md   |  28 +++++
 .../components/features/.og-editor-preview.md |  51 +++++----
 .../features/.release-media-manager.md        |  33 +++---
 .../components/features/.use-video-warmup.md  |  44 ++++++++
 .../features/board/.board-column-header.md    |  37 +++----
 .../features/board/.board-column.md           |  55 +++++-----
 .../src/components/features/board/.board.md   |  72 ++++++-------
 .../src/components/features/board/.types.md   |  54 +++++-----
 .../features/notifications/.index.md          |  52 ++++-----
 .../notifications/.notification-drawer.md     |  41 ++++---
 .../notifications/.notification-popups.md     |  45 ++++++++
 .../notifications/.notifications-context.md   |  94 +++++++---------
 .../features/notifications/.types.md          |  61 ++++++-----
 .../.ticket-status-config-list.md             |  52 +++++++++
 .../icons/.vendor-directory-icon.md           |  39 ++++---
 .../src/components/layout/.page-heading.md    |  36 +++++++
 .../src/components/layout/.title-block.md     |  43 ++++----
 .../src/components/loading/.card-skeleton.md  |  71 ++++++-------
 .../loading/.device-card-skeleton.md          |  53 ++++------
 .../loading/.margin-report-skeleton.md        |  60 +++++------
 .../loading/.organization-card-skeleton.md    |  41 +++----
 .../loading/.organization-icon-skeleton.md    |  60 +++++------
 .../loading/.page-layout-skeleton.md          |  67 ++++++------
 .../loading/.users-grid-skeleton.md           |  59 +++++------
 .../src/components/navigation/.app-header.md  |  83 +++++++--------
 .../navigation/.app-layout-drawer.md          |  49 +++++++++
 .../src/components/navigation/.app-layout.md  |  45 ++++----
 .../navigation/.header-mingo-button.md        |  44 ++++++++
 .../src/components/navigation/.index.md       |  85 ++++++---------
 .../components/onboarding-guides/.index.md    |  42 ++++++++
 .../.onboarding-guide-detail-view.md          |  50 +++++++++
 .../.onboarding-guides-catalog-skeleton.md    |  28 +++++
 .../.onboarding-guides-catalog-view.md        |  40 +++++++
 .../hooks/.use-onboarding-guides.md           |  52 +++++++++
 .../components/platform/.ShellTypeBadge.md    |  27 ++---
 .../shared/delivery/.delivery-lists.md        |  33 ++----
 .../shared/dev-section/.dev-card-row.md       |  46 +++-----
 .../shared/dev-section/.dev-section-page.md   |  52 ++++-----
 .../shared/dev-section/.dev-section-view.md   |  48 ++++-----
 .../shared/doc-search/.doc-search-bar.md      |  46 ++++++++
 .../doc-search/.doc-search-result-row.md      |  32 ++++++
 .../doc-search/.format-relative-path.md       |  21 ++++
 .../components/shared/doc-search/.index.md    |  48 +++++++++
 .../doc-search/.map-doc-search-results.md     |  33 ++++++
 .../.resolve-search-result-action.md          |  48 +++++++++
 .../components/shared/doc-search/.types.md    |  43 ++++++++
 .../shared/doc-search/.use-doc-search.md      |  46 ++++++++
 .../legal-document/.legal-document-page.md    |  35 +++---
 .../shared/legal-document/.use-legal-docs.md  |  67 +++++++-----
 .../shared/product-release/.index.md          |  45 ++++----
 .../product-release/.product-releases-view.md |  42 ++++++++
 .../src/components/shared/roadmap/.index.md   |  39 ++++---
 .../shared/roadmap/.roadmap-grid.md           |  88 ++++++---------
 .../shared/roadmap/.roadmap-view.md           |  32 ++++++
 .../components/tickets/.help-center-card.md   |  49 +++------
 .../components/tickets/.help-center-list.md   |  41 +++----
 .../src/components/tickets/.index.md          |  76 ++++++-------
 .../tickets/.ticket-detail-drawer.md          |  46 +++-----
 .../tickets/.ticket-reply-composer.md         |  35 ++++++
 .../src/components/tickets/.types.md          |  82 +++++++-------
 .../tickets/hooks/.use-ticket-actions.md      |  89 ++++++++--------
 .../tickets/hooks/.use-ticket-engagements.md  |  60 +++++------
 .../tickets/hooks/.use-tickets-list.md        |  53 ++++------
 .../src/components/ui/.actions-menu.md        |  66 ++++--------
 .../components/ui/.allowed-domains-input.md   |  44 ++++----
 .../src/components/ui/.color-preset-select.md |  39 +++++++
 .../src/components/ui/.cursor-pagination.md   |  70 ++++++------
 .../src/components/ui/.dropdown-button.md     |  36 +++----
 .../src/components/ui/.dropdown-menu.md       |  68 +++++++-----
 .../src/components/ui/.filter-pill-row.md     |  48 +++++++++
 .../src/components/ui/.index.md               |  62 +++++------
 .../src/components/ui/.info-row.md            |  53 +++++-----
 .../src/components/ui/.input.md               |  54 ++++------
 .../src/components/ui/.modal-v2.md            |  50 ++++-----
 .../src/components/ui/.more-actions-menu.md   |  50 +++++----
 .../src/components/ui/.portal-container.md    |  42 ++++++++
 .../ui/.simple-markdown-renderer.md           |  52 +++++----
 .../src/components/ui/.square-avatar.md       |  52 +++++----
 .../src/components/ui/.tags-input.md          |  64 ++++++-----
 .../src/components/ui/.textarea.md            |  46 ++++----
 .../components/ui/.ticket-attachments-list.md |  54 +++++-----
 .../src/components/ui/.ticket-info-section.md |  88 +++++++--------
 .../ui/.ticket-status-config-row.md           |  46 ++++++++
 .../src/components/ui/.ticket-status-tag.md   |  77 ++++++++------
 .../src/components/ui/.toaster.md             |  31 +++---
 .../src/components/ui/.tooltip.md             |  30 +++---
 .../src/contexts/.chat-runtime-context.md     |  29 +++--
 .../src/hooks/.use-self-fetch.md              |  47 ++++++++
 .../src/hooks/ui/.use-auto-limit-tags.md      |  80 +++++++-------
 openframe-frontend-core/src/nats/.index.md    |  27 +++++
 .../src/nats/.nats-provider.md                |  55 ++++++++++
 openframe-frontend-core/src/nats/.nats.md     |  60 +++++------
 .../src/nats/.shared-connection.md            |  38 +++++++
 .../src/nats/.use-nats-subscription.md        |  41 +++++++
 .../src/stories/.ActionsMenu.stories.md       |  50 +++++++++
 .../src/stories/.AppLayoutDrawer.stories.md   |  55 ++++++++++
 .../src/stories/.AppLayoutSidebar.stories.md  |  46 ++++++++
 .../src/stories/.BlogCard.stories.md          |  45 ++++++++
 .../src/stories/.Board.stories.md             |  46 ++++----
 .../src/stories/.CampaignCardAdmin.stories.md |  36 +++++++
 .../src/stories/.CaseStudyCard.stories.md     |  38 +++++++
 .../src/stories/.ChatContainer.stories.md     |  43 ++++++++
 .../stories/.ChatInlineVideoPill.stories.md   |  24 +++++
 .../stories/.ChatMingoInfoCards.stories.md    |  29 +++++
 .../src/stories/.ChatTicketList.stories.md    |  39 ++++---
 .../stories/.CustomerInterviewCard.stories.md |  31 ++++++
 .../src/stories/.DataRoomDocCard.stories.md   |  35 ++++++
 .../src/stories/.DataTable.stories.md         |  62 +++++------
 .../src/stories/.EmbeddableChat.stories.md    |  77 ++++++++------
 .../src/stories/.GenericEntityCard.stories.md |  34 ++++++
 .../stories/.GitHubActivityCard.stories.md    |  42 ++++++++
 .../src/stories/.GuideWelcome.stories.md      |  44 ++++++++
 .../src/stories/.HubspotTicketCard.stories.md |  46 ++++++++
 .../stories/.InvestorUpdateCard.stories.md    |  39 +++++++
 .../src/stories/.MingoChatModals.stories.md   |  42 ++++++++
 .../src/stories/.MingoInfoCard.stories.md     |  44 ++++++++
 .../stories/.MingoOnboardingCard.stories.md   |  38 +++----
 .../src/stories/.MingoWelcome.stories.md      |  41 +++++++
 .../src/stories/.Modal.stories.md             |  26 ++---
 .../stories/.NotificationDrawer.stories.md    |  72 ++++++-------
 .../stories/.OnboardingGuideCard.stories.md   |  40 +++++++
 .../src/stories/.PageActions.stories.md       |  64 +++++------
 .../src/stories/.PageContainer.stories.md     |  48 ++++-----
 .../src/stories/.PageLayout.stories.md        |  28 ++---
 .../stories/.ProductReleaseCard.stories.md    |  32 ++++++
 .../src/stories/.ProgramCard.stories.md       |  34 ++++++
 .../src/stories/.RoadmapCard.stories.md       |  39 +++++++
 .../src/stories/.SlackMessageCard.stories.md  |  36 +++++++
 .../src/stories/.TabSelector.stories.md       |  51 ++++-----
 .../src/stories/.Tag.stories.md               |  58 +++++-----
 .../src/stories/.TicketInfoSection.stories.md |  67 ++++++------
 .../src/stories/.Toaster.stories.md           |  54 +++++-----
 .../__fixtures__/.chat-card-decorator.md      |  37 +++++++
 .../src/stories/__fixtures__/.chat-cards.md   |  53 ++++++++++
 .../src/types/.product-release.md             |  94 +++++++---------
 openframe-frontend-core/src/utils/.cn.md      |  55 +++++-----
 .../src/utils/.content-href.md                |  56 ++++++++++
 .../src/utils/.embed-authed-fetch.md          |  64 +++++------
 openframe-frontend-core/src/utils/.index.md   |  68 +++++++-----
 .../src/utils/.list-url.md                    |  35 ++++++
 .../src/utils/.ods-color-utils.md             |  94 ++++++++--------
 .../src/utils/.release-badge.md               |  42 ++++++++
 .../src/utils/.release-cover.md               |  43 ++++++++
 .../src/utils/.scroll-into-view.md            |  40 ++++---
 .../dev-sections/.dev-section-param-keys.md   |  30 ++++++
 .../dev-sections/.openframe-dev-sections.md   |  53 +++++-----
 .../ws/.ProxySessionCleanupWebSocketClient.md |  40 +++----
 .../config/ws/.ToolWebSocketProxyUrlFilter.md |  44 ++++----
 .../ws/.WebSocketServiceSecurityDecorator.md  |  70 ++++++------
 .../security/.GatewaySecurityConfig.md        |  69 ++++++------
 .../gateway/security/.PathConstants.md        |  42 ++++----
 .../filter/.AddAuthorizationHeaderFilter.md   |  67 +++++-------
 .../tenant/.DefaultIssuerUrlProvider.md       |  40 +++++++
 .../security/tenant/.IssuerUrlProvider.md     |  57 +++++-----
 .../gateway/service/.IntegrationService.md    |  45 ++++----
 .../gateway/service/.RestProxyService.md      |  49 ++++-----
 .../upstream/.DefaultToolUpstreamResolver.md  |  39 ++++---
 .../controller/.IntegratedToolController.md   |  71 +++++--------
 ...OpenFrameClientConfigurationInitializer.md |  47 +++++---
 .../.TacticalRmmScriptsInitializer.md         |  39 ++++---
 .../.BackfillDocumentVersionChangeUnit.md     |  37 +++----
 .../.BackfillTicketOrdersChangeUnit.md        |  44 ++++----
 .../.MigrateTicketStatusesChangeUnit.md       |  43 ++++++++
 .../scheduler/.FleetMdmSetupScheduler.md      |  35 +++---
 .../service/.ReleaseVersionService.md         |  47 +++++---
 .../.IntegratedToolDataEnrichmentService.md   |  57 +++++-----
 .../test/helpers/.RequestSpecHelper.md        |  56 +++++-----
 .../test/tests/.KnowledgeBaseTest.md          |  53 ++++------
 .../com/openframe/test/tests/.TicketsTest.md  |  51 ++++-----
 react-embedding-example/.tailwind.config.md   |  35 ++++++
 react-embedding-example/.vite.config.md       |  30 ++++++
 react-embedding-example/src/.app-routes.md    |  42 ++++++++
 react-embedding-example/src/.main.md          |  31 ++++++
 react-embedding-example/src/.vite-env.d.md    |  25 +++++
 .../src/components/.app-shell.md              |  33 ++++++
 .../src/components/.ask-ai.md                 |  35 ++++++
 .../src/components/.page-state.md             |  28 +++++
 .../src/config/.content.md                    |  18 ++++
 .../src/config/.endpoints.md                  |  38 +++++++
 react-embedding-example/src/pages/.contact.md |  28 +++++
 .../src/pages/.delivery.md                    |  29 +++++
 react-embedding-example/src/pages/.home.md    |  33 ++++++
 react-embedding-example/src/pages/.legal.md   |  26 +++++
 .../src/pages/.onboarding-catalog.md          |  41 +++++++
 .../src/pages/.onboarding-detail.md           |  42 ++++++++
 .../src/pages/.release-detail.md              |  35 ++++++
 .../src/pages/.releases.md                    |  29 +++++
 react-embedding-example/src/pages/.roadmap.md |  30 ++++++
 react-embedding-example/src/pages/.tickets.md |  31 ++++++
 .../src/providers/.app-providers.md           |  42 ++++++++
 .../src/providers/.content-runtime.md         |  36 +++++++
 .../src/providers/.embed-router-bridge.md     |  29 +++++
 .../src/stubs/.next-font-google.md            |  36 +++++++
 402 files changed, 12330 insertions(+), 6537 deletions(-)
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelDispatchResponse.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelExecutionInput.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CommandDispatchResponse.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/command/.RunCommandInput.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/script/.CreateScriptInput.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptEnvVarInput.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptFilterInput.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptResponse.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/dto/script/.UpdateScriptInput.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/mapper/.ScriptMapper.md
 create mode 100644 openframe-api-lib/src/main/java/com/openframe/api/service/rmm/.ScriptService.md
 create mode 100644 openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.CommandDataFetcher.md
 create mode 100644 openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.ScriptDataFetcher.md
 create mode 100644 openframe-api-service-core/src/main/java/com/openframe/api/mapper/.GraphQLScriptMapper.md
 create mode 100644 openframe-api-service-core/src/main/java/com/openframe/api/service/rmm/.CommandDispatchService.md
 create mode 100644 openframe-api-service-core/src/test/java/com/openframe/api/mapper/.ScriptMapperTest.md
 create mode 100644 openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.CommandDispatchServiceTest.md
 create mode 100644 openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.ScriptServiceTest.md
 create mode 100644 openframe-authorization-service-core/src/main/java/com/openframe/authz/exception/.OwnerCannotSwitchTenantException.md
 create mode 100644 openframe-client-core/src/main/java/com/openframe/client/config/.AsyncConfig.md
 create mode 100644 openframe-client-core/src/main/java/com/openframe/client/exception/.InvalidClientSecretException.md
 create mode 100644 openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.OrganizationIdResolver.md
 create mode 100644 openframe-client-core/src/main/java/com/openframe/client/service/validator/.ClientSecretValidator.md
 create mode 100644 openframe-client-core/src/test/java/com/openframe/client/service/agentregistration/.OrganizationIdResolverTest.md
 create mode 100644 openframe-client-core/src/test/java/com/openframe/client/service/validator/.ClientSecretValidatorTest.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/.TenantScoped.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.Script.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptEnvVar.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptPlatform.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptShell.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptStatus.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/filter/.ScriptQueryFilter.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusDefinition.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusKind.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/repository/.TenantAwareRepository.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/service/.DefaultTenantIdProvider.md
 create mode 100644 openframe-data-mongo-common/src/main/java/com/openframe/data/service/.TenantIdProvider.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoInfraConfig.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.TenantAwareSyncConfig.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationContextWriteConverter.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepository.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepositoryImpl.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.ScriptRepository.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketStatusDefinitionRepository.md
 create mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/seed/ticket/.TicketStatusSeedCatalog.md
 create mode 100644 openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/rmm/.ScriptRepositoryIT.md
 create mode 100644 openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/support/.RmmIntegrationTestApplication.md
 create mode 100644 openframe-data-mongo-sync/src/test/java/com/openframe/data/repository/notification/.NotificationContextWriteConverterTest.md
 create mode 100644 openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CancelMessage.md
 create mode 100644 openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CommandMessage.md
 create mode 100644 openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisher.md
 create mode 100644 openframe-data-nats/src/test/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisherTest.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-archive-page.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-composer.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-header-icon-button.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-message-row.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-panel-header-mobile.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-panel-header.md
 create mode 100644 openframe-frontend-core/src/components/chat/.chat-quick-action-row.md
 create mode 100644 openframe-frontend-core/src/components/chat/.guide-mode-banner.md
 create mode 100644 openframe-frontend-core/src/components/chat/.guide-welcome.md
 create mode 100644 openframe-frontend-core/src/components/chat/.mingo-chat-history.md
 create mode 100644 openframe-frontend-core/src/components/chat/.mingo-chat-modals.md
 create mode 100644 openframe-frontend-core/src/components/chat/.mingo-info-card.md
 create mode 100644 openframe-frontend-core/src/components/chat/.mingo-welcome.md
 create mode 100644 openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-link.md
 create mode 100644 openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-placeholder.md
 create mode 100644 openframe-frontend-core/src/components/chat/hooks/.use-chat-dialog-manager.md
 create mode 100644 openframe-frontend-core/src/components/chat/utils/.execute-navigation.md
 create mode 100644 openframe-frontend-core/src/components/features/.captions-url.md
 create mode 100644 openframe-frontend-core/src/components/features/.mux-origins.md
 create mode 100644 openframe-frontend-core/src/components/features/.use-video-warmup.md
 create mode 100644 openframe-frontend-core/src/components/features/notifications/.notification-popups.md
 create mode 100644 openframe-frontend-core/src/components/features/ticket-status-config-list/.ticket-status-config-list.md
 create mode 100644 openframe-frontend-core/src/components/layout/.page-heading.md
 create mode 100644 openframe-frontend-core/src/components/navigation/.app-layout-drawer.md
 create mode 100644 openframe-frontend-core/src/components/navigation/.header-mingo-button.md
 create mode 100644 openframe-frontend-core/src/components/onboarding-guides/.index.md
 create mode 100644 openframe-frontend-core/src/components/onboarding-guides/.onboarding-guide-detail-view.md
 create mode 100644 openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-skeleton.md
 create mode 100644 openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-view.md
 create mode 100644 openframe-frontend-core/src/components/onboarding-guides/hooks/.use-onboarding-guides.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.doc-search-bar.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.doc-search-result-row.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.format-relative-path.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.index.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.map-doc-search-results.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.resolve-search-result-action.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.types.md
 create mode 100644 openframe-frontend-core/src/components/shared/doc-search/.use-doc-search.md
 create mode 100644 openframe-frontend-core/src/components/shared/product-release/.product-releases-view.md
 create mode 100644 openframe-frontend-core/src/components/shared/roadmap/.roadmap-view.md
 create mode 100644 openframe-frontend-core/src/components/tickets/.ticket-reply-composer.md
 create mode 100644 openframe-frontend-core/src/components/ui/.color-preset-select.md
 create mode 100644 openframe-frontend-core/src/components/ui/.filter-pill-row.md
 create mode 100644 openframe-frontend-core/src/components/ui/.portal-container.md
 create mode 100644 openframe-frontend-core/src/components/ui/.ticket-status-config-row.md
 create mode 100644 openframe-frontend-core/src/hooks/.use-self-fetch.md
 create mode 100644 openframe-frontend-core/src/nats/.index.md
 create mode 100644 openframe-frontend-core/src/nats/.nats-provider.md
 create mode 100644 openframe-frontend-core/src/nats/.shared-connection.md
 create mode 100644 openframe-frontend-core/src/nats/.use-nats-subscription.md
 create mode 100644 openframe-frontend-core/src/stories/.ActionsMenu.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.AppLayoutDrawer.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.AppLayoutSidebar.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.BlogCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.CampaignCardAdmin.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.CaseStudyCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.ChatContainer.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.ChatInlineVideoPill.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.ChatMingoInfoCards.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.CustomerInterviewCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.DataRoomDocCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.GenericEntityCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.GitHubActivityCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.GuideWelcome.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.HubspotTicketCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.InvestorUpdateCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.MingoChatModals.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.MingoInfoCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.MingoWelcome.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.OnboardingGuideCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.ProductReleaseCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.ProgramCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.RoadmapCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/.SlackMessageCard.stories.md
 create mode 100644 openframe-frontend-core/src/stories/__fixtures__/.chat-card-decorator.md
 create mode 100644 openframe-frontend-core/src/stories/__fixtures__/.chat-cards.md
 create mode 100644 openframe-frontend-core/src/utils/.content-href.md
 create mode 100644 openframe-frontend-core/src/utils/.list-url.md
 create mode 100644 openframe-frontend-core/src/utils/.release-badge.md
 create mode 100644 openframe-frontend-core/src/utils/.release-cover.md
 create mode 100644 openframe-frontend-core/src/utils/dev-sections/.dev-section-param-keys.md
 create mode 100644 openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.DefaultIssuerUrlProvider.md
 create mode 100644 openframe-management-service-core/src/main/java/com/openframe/management/migration/.MigrateTicketStatusesChangeUnit.md
 create mode 100644 react-embedding-example/.tailwind.config.md
 create mode 100644 react-embedding-example/.vite.config.md
 create mode 100644 react-embedding-example/src/.app-routes.md
 create mode 100644 react-embedding-example/src/.main.md
 create mode 100644 react-embedding-example/src/.vite-env.d.md
 create mode 100644 react-embedding-example/src/components/.app-shell.md
 create mode 100644 react-embedding-example/src/components/.ask-ai.md
 create mode 100644 react-embedding-example/src/components/.page-state.md
 create mode 100644 react-embedding-example/src/config/.content.md
 create mode 100644 react-embedding-example/src/config/.endpoints.md
 create mode 100644 react-embedding-example/src/pages/.contact.md
 create mode 100644 react-embedding-example/src/pages/.delivery.md
 create mode 100644 react-embedding-example/src/pages/.home.md
 create mode 100644 react-embedding-example/src/pages/.legal.md
 create mode 100644 react-embedding-example/src/pages/.onboarding-catalog.md
 create mode 100644 react-embedding-example/src/pages/.onboarding-detail.md
 create mode 100644 react-embedding-example/src/pages/.release-detail.md
 create mode 100644 react-embedding-example/src/pages/.releases.md
 create mode 100644 react-embedding-example/src/pages/.roadmap.md
 create mode 100644 react-embedding-example/src/pages/.tickets.md
 create mode 100644 react-embedding-example/src/providers/.app-providers.md
 create mode 100644 react-embedding-example/src/providers/.content-runtime.md
 create mode 100644 react-embedding-example/src/providers/.embed-router-bridge.md
 create mode 100644 react-embedding-example/src/stubs/.next-font-google.md

diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelDispatchResponse.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelDispatchResponse.md
new file mode 100644
index 000000000..248abff13
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelDispatchResponse.md
@@ -0,0 +1,16 @@
+<!-- source-hash: f082c2bd77cdc5b275cfbc30eb76c7e7 -->
+A response DTO representing the result of a cancellation request for a dispatched command execution.
+
+## Key Components
+
+- **`executionId`** — The unique identifier of the execution that was cancelled
+
+## Usage Example
+
+```java
+CancelDispatchResponse response = CancelDispatchResponse.builder()
+    .executionId("exec-abc-123")
+    .build();
+
+String id = response.getExecutionId();
+```
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelExecutionInput.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelExecutionInput.md
new file mode 100644
index 000000000..51f1939d2
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CancelExecutionInput.md
@@ -0,0 +1,22 @@
+<!-- source-hash: 98097b6c3e34973b0847ce76254a876f -->
+Data Transfer Object (DTO) for carrying the required identifiers to cancel an ongoing execution on a target machine.
+
+## Key Components
+
+| Field | Type | Constraint | Description |
+|-------|------|-----------|-------------|
+| `machineId` | `String` | `@NotBlank` | Identifier of the target machine running the execution |
+| `executionId` | `String` | `@NotBlank` | Identifier of the specific execution to cancel |
+
+## Usage Example
+
+```java
+CancelExecutionInput input = new CancelExecutionInput();
+input.setMachineId("machine-abc123");
+input.setExecutionId("exec-xyz789");
+
+// Pass to command handler or REST controller
+commandService.cancelExecution(input);
+```
+
+> Both fields are required — a blank `machineId` or `executionId` will trigger a validation error before the cancellation request is processed.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CommandDispatchResponse.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CommandDispatchResponse.md
new file mode 100644
index 000000000..c9ef597b3
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.CommandDispatchResponse.md
@@ -0,0 +1,22 @@
+<!-- source-hash: 9df064e41f5143d73c89b6aa50c9faa6 -->
+A DTO representing the server's response after dispatching a command for execution.
+
+## Key Components
+
+- **`executionId`** (`String`) — Unique identifier for the dispatched command execution, used to track or query execution status.
+
+Annotations:
+- `@Data` — Generates getters, setters, `equals`, `hashCode`, and `toString` via Lombok.
+- `@Builder` — Provides a fluent builder pattern for object construction via Lombok.
+
+## Usage Example
+
+```java
+// Building a response after dispatching a command
+CommandDispatchResponse response = CommandDispatchResponse.builder()
+    .executionId("exec-8f3a2c1d-4b56-7890")
+    .build();
+
+// Accessing the execution ID
+String id = response.getExecutionId();
+```
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.RunCommandInput.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.RunCommandInput.md
new file mode 100644
index 000000000..692cf1e85
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/command/.RunCommandInput.md
@@ -0,0 +1,25 @@
+<!-- source-hash: a16632a7b2d279f0575243405fac3d32 -->
+DTO representing the GraphQL input payload for dispatching an ad-hoc shell command to a remote agent.
+
+## Key Components
+
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| `machineId` | `String` | `@NotBlank` | Target machine identifier |
+| `command` | `String` | `@NotBlank` | Shell command to execute |
+| `shell` | `ScriptShell` | `@NotNull` | Shell interpreter (e.g. `POWERSHELL`, `CMD`, `BASH`) |
+| `privilegeLevel` | `PrivilegeLevel` | `@NotNull` | Execution privilege context (e.g. `SYSTEM`, `USER`) |
+| `timeoutSeconds` | `Integer` | `@Positive` | Optional execution timeout in seconds |
+
+## Usage Example
+
+```java
+RunCommandInput input = new RunCommandInput();
+input.setMachineId("machine-abc123");
+input.setCommand("Get-Process | Select-Object Name, CPU");
+input.setShell(ScriptShell.POWERSHELL);
+input.setPrivilegeLevel(PrivilegeLevel.SYSTEM);
+input.setTimeoutSeconds(30);
+```
+
+> Bean validation (`@NotBlank`, `@NotNull`, `@Positive`) is enforced automatically at the GraphQL layer before the command is dispatched to the agent.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.CreateScriptInput.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.CreateScriptInput.md
new file mode 100644
index 000000000..a21ea38ed
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.CreateScriptInput.md
@@ -0,0 +1,35 @@
+<!-- source-hash: 66f20d3f25c3e2571fe69e3415fe65d4 -->
+DTO for capturing client-supplied fields when creating a new script resource. Tenant attribution is intentionally excluded and resolved from the authenticated principal server-side.
+
+## Key Components
+
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| `name` | `String` | `@NotBlank` | Human-readable script name |
+| `shell` | `ScriptShell` | `@NotNull` | Target shell/interpreter (e.g. PowerShell, Bash) |
+| `scriptBody` | `String` | `@NotBlank` | Raw script content |
+| `description` | `String` | — | Optional human-readable description |
+| `tag` | `String` | — | Organizational tag |
+| `supportedPlatforms` | `List<ScriptPlatform>` | — | Target OS/platform list |
+| `defaultTimeoutSeconds` | `Integer` | `@Positive` | Execution timeout override |
+| `defaultArgs` | `List<String>` | — | Pre-filled argument defaults |
+| `envVars` | `List<ScriptEnvVarInput>` | `@Valid` | Environment variable definitions (cascading validation) |
+
+## Usage Example
+
+```java
+CreateScriptInput input = new CreateScriptInput();
+input.setName("Disk Cleanup");
+input.setShell(ScriptShell.POWERSHELL);
+input.setScriptBody("Remove-Item -Path $env:TEMP\\* -Recurse -Force");
+input.setDescription("Clears the Windows temp directory");
+input.setSupportedPlatforms(List.of(ScriptPlatform.WINDOWS));
+input.setDefaultTimeoutSeconds(120);
+
+ScriptEnvVarInput envVar = new ScriptEnvVarInput();
+envVar.setKey("LOG_LEVEL");
+envVar.setValue("INFO");
+input.setEnvVars(List.of(envVar));
+```
+
+> **Note:** Do not supply a tenant ID in this payload. The API resolves tenant attribution automatically from the authenticated principal at the controller/resolver layer.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptEnvVarInput.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptEnvVarInput.md
new file mode 100644
index 000000000..e5ca0ff29
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptEnvVarInput.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 368ed32c306a55cd149ab75fe6babb96 -->
+Symmetric DTO representing a script environment variable, used for both create/update input and response output payloads.
+
+## Key Components
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `String` | Environment variable name — required, validated with `@NotBlank` |
+| `value` | `String` | Environment variable value — optional |
+| `secret` | `boolean` | Marks the value as sensitive (passwords, API keys, tokens) |
+
+## Usage Example
+
+```java
+// Build a plain environment variable
+ScriptEnvVarInput envVar = ScriptEnvVarInput.builder()
+    .name("NODE_ENV")
+    .value("production")
+    .secret(false)
+    .build();
+
+// Build a sensitive environment variable
+ScriptEnvVarInput secretVar = ScriptEnvVarInput.builder()
+    .name("API_KEY")
+    .value("sk-abc123")
+    .secret(true)
+    .build();
+```
+
+> **⚠️ Security Note:** Secret values are currently stored in **plaintext** pending a full secret-management implementation (encryption at rest + secure agent delivery). UI layers, logs, and audit trails are responsible for masking and redacting sensitive values in the interim.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptFilterInput.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptFilterInput.md
new file mode 100644
index 000000000..3fb7841b5
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptFilterInput.md
@@ -0,0 +1,32 @@
+<!-- source-hash: d20a60ff8a5cae0bcc8871d1b3fa7c72 -->
+Data Transfer Object for filtering scripts in the OpenFrame RMM module, supporting multi-value filtering by shell type, status, platform compatibility, and tag.
+
+## Key Components
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `shells` | `List<ScriptShell>` | Filter scripts matching any of the specified shell types |
+| `statuses` | `List<ScriptStatus>` | Filter by script status; defaults to excluding `DELETED` when null/empty |
+| `supportedPlatforms` | `List<ScriptPlatform>` | Filter scripts compatible with ANY of the specified platforms |
+| `tag` | `String` | Case-insensitive exact match on a single tag |
+
+All fields are optional — omitting a field applies no constraint for that dimension.
+
+## Usage Example
+
+```java
+// Filter for active PowerShell scripts targeting Windows
+ScriptFilterInput filter = ScriptFilterInput.builder()
+    .shells(List.of(ScriptShell.POWERSHELL))
+    .statuses(List.of(ScriptStatus.ACTIVE))
+    .supportedPlatforms(List.of(ScriptPlatform.WINDOWS))
+    .tag("patching")
+    .build();
+
+// Filter for all Bash/ZSH scripts regardless of status
+ScriptFilterInput shellOnly = ScriptFilterInput.builder()
+    .shells(List.of(ScriptShell.BASH, ScriptShell.ZSH))
+    .build();
+```
+
+> **Note:** When `statuses` is `null` or empty, the service layer automatically excludes `DELETED` scripts — pass `ScriptStatus.DELETED` explicitly only if soft-deleted scripts are intentionally required.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptResponse.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptResponse.md
new file mode 100644
index 000000000..cc3069d0b
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.ScriptResponse.md
@@ -0,0 +1,40 @@
+<!-- source-hash: 02108fb61f884d1bc79d2d7250c988cd -->
+Data Transfer Object (DTO) representing a script resource in API responses, exposing all script metadata while intentionally omitting the internal `tenantId` field.
+
+## Key Components
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `String` | Unique script identifier |
+| `name` / `description` | `String` | Human-readable script metadata |
+| `shell` | `String` | Shell enum name (e.g. `POWERSHELL`, `BASH`) |
+| `scriptBody` | `String` | Raw script content |
+| `supportedPlatforms` | `List<String>` | Platform enum names the script targets |
+| `defaultTimeoutSeconds` | `Integer` | Execution timeout default |
+| `defaultArgs` | `List<String>` | Pre-configured argument defaults |
+| `envVars` | `List<ScriptEnvVarInput>` | Environment variable definitions |
+| `status` | `String` | Lifecycle enum name (e.g. `ACTIVE`, `DISABLED`) |
+| `statusChangedAt` / `createdAt` / `updatedAt` | `Instant` | Audit timestamps |
+
+Uses Lombok `@Data` and `@Builder` for boilerplate-free construction and accessor generation.
+
+## Usage Example
+
+```java
+ScriptResponse response = ScriptResponse.builder()
+    .id("script-abc123")
+    .name("Disk Cleanup")
+    .description("Removes temp files from Windows endpoints")
+    .shell("POWERSHELL")
+    .scriptBody("Remove-Item -Path $env:TEMP\\* -Recurse -Force")
+    .tag("maintenance")
+    .supportedPlatforms(List.of("WINDOWS"))
+    .defaultTimeoutSeconds(120)
+    .defaultArgs(List.of("-Verbose"))
+    .status("ACTIVE")
+    .createdAt(Instant.now())
+    .updatedAt(Instant.now())
+    .build();
+```
+
+> **Security note:** `tenantId` is deliberately excluded — tenant context is resolved server-side from the authenticated session and never returned to the caller.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.UpdateScriptInput.md b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.UpdateScriptInput.md
new file mode 100644
index 000000000..f301d4be0
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/dto/script/.UpdateScriptInput.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 0ace9d8e61f4dd700615dc46ea81df5d -->
+Data Transfer Object (DTO) representing the full-replacement (PUT) request payload for updating an existing script resource.
+
+## Key Components
+
+| Field | Type | Constraint | Description |
+|---|---|---|---|
+| `name` | `String` | `@NotBlank` | Script display name |
+| `description` | `String` | optional | Human-readable description |
+| `shell` | `ScriptShell` | `@NotNull` | Target shell/interpreter |
+| `scriptBody` | `String` | `@NotBlank` | Full script source code |
+| `tag` | `String` | optional | Categorization tag |
+| `supportedPlatforms` | `List<ScriptPlatform>` | optional | Target OS/platform list |
+| `defaultTimeoutSeconds` | `Integer` | `@Positive` | Execution timeout |
+| `defaultArgs` | `List<String>` | optional | Default runtime arguments |
+| `envVars` | `List<ScriptEnvVarInput>` | `@Valid` | Environment variable definitions |
+
+## Key Behavior
+
+- **PUT semantics** — every field overwrites the stored document; optional fields sent as `null` **clear** the stored value
+- Partial updates are **not supported** — callers must send the complete resource on every request
+- Required fields (`name`, `shell`, `scriptBody`) mirror `CreateScriptInput` constraints, preventing the document from reaching an invalid state
+
+## Usage Example
+
+```java
+UpdateScriptInput input = new UpdateScriptInput();
+input.setName("Disk Cleanup");
+input.setShell(ScriptShell.POWERSHELL);
+input.setScriptBody("Get-PSDrive -PSProvider FileSystem | ...");
+input.setDefaultTimeoutSeconds(120);
+input.setSupportedPlatforms(List.of(ScriptPlatform.WINDOWS));
+
+// Null optional fields clear stored values
+input.setDescription(null);  // clears existing description
+input.setTag(null);          // clears existing tag
+```
+
+> **Note:** Because this is a full-replacement operation, always populate all fields you wish to retain — omitting optional fields will erase previously stored data.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/mapper/.ScriptMapper.md b/openframe-api-lib/src/main/java/com/openframe/api/mapper/.ScriptMapper.md
new file mode 100644
index 000000000..195f9306c
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/mapper/.ScriptMapper.md
@@ -0,0 +1,42 @@
+<!-- source-hash: c8ad36243d1448e48a90307d6ce4e804 -->
+Handles bidirectional mapping between `Script` entities and their corresponding DTOs (`CreateScriptInput`, `UpdateScriptInput`, `ScriptResponse`) for the OpenFrame RMM script management domain.
+
+## Key Components
+
+| Method | Description |
+|--------|-------------|
+| `toEntity(tenantId, input)` | Maps a `CreateScriptInput` DTO to a new `Script` document, scoped to the given tenant |
+| `updateEntity(existing, input)` | Mutates an existing `Script` entity in-place from an `UpdateScriptInput` DTO |
+| `toResponse(entity)` | Converts a `Script` entity to a `ScriptResponse` DTO, normalizing enums to their string names |
+| `mapEnvVarsToEntity(...)` | Private helper — maps `ScriptEnvVarInput` list to `ScriptEnvVar` document list |
+| `mapEnvVarsToResponse(...)` | Private helper — maps `ScriptEnvVar` document list back to `ScriptEnvVarInput` list |
+| `mapPlatformsToResponse(...)` | Private helper — converts `ScriptPlatform` enum list to `List<String>` |
+
+> **Note:** Secret masking for env vars (`secret == true`) is pending implementation once secret-management support lands (see inline TODO).
+
+## Usage Example
+
+```java
+@Service
+public class ScriptService {
+
+    private final ScriptMapper scriptMapper;
+    private final ScriptRepository scriptRepository;
+
+    // Create a new script
+    public ScriptResponse createScript(String tenantId, CreateScriptInput input) {
+        Script entity = scriptMapper.toEntity(tenantId, input);
+        Script saved = scriptRepository.save(entity);
+        return scriptMapper.toResponse(saved);
+    }
+
+    // Update an existing script
+    public ScriptResponse updateScript(String id, UpdateScriptInput input) {
+        Script existing = scriptRepository.findById(id).orElseThrow();
+        scriptMapper.updateEntity(existing, input);
+        return scriptMapper.toResponse(scriptRepository.save(existing));
+    }
+}
+```
+
+> This mapper is transport-agnostic — GraphQL-specific concerns (cursor pagination, Relay Connection/Edge envelopes) are handled separately in `GraphQLScriptMapper`.
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/service/.KnowledgeBaseTempAttachmentService.md b/openframe-api-lib/src/main/java/com/openframe/api/service/.KnowledgeBaseTempAttachmentService.md
index 6df506d03..8b2023e54 100644
--- a/openframe-api-lib/src/main/java/com/openframe/api/service/.KnowledgeBaseTempAttachmentService.md
+++ b/openframe-api-lib/src/main/java/com/openframe/api/service/.KnowledgeBaseTempAttachmentService.md
@@ -1,52 +1,57 @@
-<!-- source-hash: 5cee5bb06bfbbd6548384b67aeb0723b -->
-Manages temporary file uploads for Knowledge Base articles before they are permanently saved, mirroring the ticket-based `TempAttachmentService` pattern.
+<!-- source-hash: 2436f8dbfe9355840d4a7b609566f4d5 -->
+Manages temporary file uploads for Knowledge Base articles before they are permanently saved, mirroring the ticket-based `TempAttachmentService` pattern with GCS-backed presigned URL support.
 
 ## Key Components
 
 | Method | Description |
 |--------|-------------|
-| `createUploadUrl()` | Creates a `TempAttachment` record and generates a unique GCS storage path for a pending upload |
-| `generateUploadUrl()` | Returns a presigned GCS PUT URL for direct frontend-to-storage upload |
+| `createUploadUrl()` | Creates a `TempAttachment` record with a unique GCS temp path and returns it for presigned URL generation |
+| `generateUploadUrl()` | Generates a time-limited GCS presigned PUT URL for direct frontend-to-GCS upload |
 | `deleteTempAttachment()` | Deletes a temp attachment from GCS and the database, enforcing uploader ownership |
-| `linkTempAttachmentsToArticle()` | Moves temp files to permanent `kb-attachments/` paths and creates `KnowledgeBaseItemAttachment` records |
-| `moveToArticle()` *(private)* | Handles per-file GCS move, temp record cleanup, and permanent attachment creation |
-
-**Configuration property:** `openframe.kb.presigned-url-expiration-minutes` (default: `15`)
+| `linkTempAttachmentsToArticle()` | Promotes temp files to permanent `kb-attachments/` storage, creates `KnowledgeBaseItemAttachment` records, and cleans up temp entries |
+| `moveToArticle()` *(private)* | Moves a single file from `temp/{id}/` to `kb-attachments/{articleId}/` via GCS, with per-file error isolation |
 
 ## Upload Flow
 
 ```mermaid
 sequenceDiagram
-    participant U as User
-    participant S as KBTempAttachmentService
-    participant GCS as GCS Storage
-    participant DB as Database
-
-    U->>S: createUploadUrl(fileName, contentType)
-    S->>DB: Save TempAttachment (temp/{id}/file)
-    S->>U: Return TempAttachment + presigned PUT URL
-    U->>GCS: Upload file directly
-    U->>S: linkTempAttachmentsToArticle(articleId, tempIds)
-    S->>GCS: moveFile(temp path → kb-attachments path)
-    S->>DB: Delete TempAttachment
-    S->>DB: Save KnowledgeBaseItemAttachment
+    participant Frontend
+    participant Service
+    participant GCS
+    participant DB
+
+    Frontend->>Service: createUploadUrl(uploaderId, fileName, ...)
+    Service->>DB: Save TempAttachment
+    Service->>Frontend: TempAttachment + presigned PUT URL
+    Frontend->>GCS: PUT file directly
+    Frontend->>Service: linkTempAttachmentsToArticle(articleId, tempIds)
+    Service->>GCS: moveFile(temp/ → kb-attachments/)
+    Service->>DB: Delete TempAttachment
+    Service->>DB: Save KnowledgeBaseItemAttachment
 ```
 
 ## Usage Example
 
 ```java
-// Step 1: Request an upload URL
-TempAttachment temp = kbTempAttachmentService.createUploadUrl(
-    userId, "diagram.png", "image/png", 204800L
-);
-String presignedUrl = kbTempAttachmentService.generateUploadUrl(temp);
-// Frontend uploads directly to presignedUrl via HTTP PUT
+// Step 1: Create temp upload record and get presigned URL
+TempAttachment temp = knowledgeBaseTempAttachmentService
+    .createUploadUrl("user-123", "diagram.png", "image/png", 204800L);
+
+String uploadUrl = knowledgeBaseTempAttachmentService
+    .generateUploadUrl(temp);
+// Frontend uploads directly to uploadUrl via HTTP PUT
 
 // Step 2: On article save, promote temp files to permanent storage
 List<KnowledgeBaseItemAttachment> attachments =
-    kbTempAttachmentService.linkTempAttachmentsToArticle(
-        articleId,
+    knowledgeBaseTempAttachmentService.linkTempAttachmentsToArticle(
+        "article-456",
         List.of(temp.getId()),
-        userId
+        "user-123"
     );
-```
\ No newline at end of file
+```
+
+## Configuration
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `openframe.kb.presigned-url-expiration-minutes` | `15` | Lifetime of the GCS presigned upload URL |
\ No newline at end of file
diff --git a/openframe-api-lib/src/main/java/com/openframe/api/service/rmm/.ScriptService.md b/openframe-api-lib/src/main/java/com/openframe/api/service/rmm/.ScriptService.md
new file mode 100644
index 000000000..ff0fb5cd1
--- /dev/null
+++ b/openframe-api-lib/src/main/java/com/openframe/api/service/rmm/.ScriptService.md
@@ -0,0 +1,45 @@
+<!-- source-hash: f2162d1dccd014ffdbac1fdf33d94cb2 -->
+Manages CRUD operations for RMM scripts within a tenant-scoped context, enforcing name uniqueness, soft-delete semantics, and cursor-based pagination.
+
+## Key Components
+
+| Member | Description |
+|---|---|
+| `create(CreateScriptInput)` | Creates a new script; throws `ConflictException` on duplicate name |
+| `get(String id)` | Fetches a single visible (non-deleted) script by ID |
+| `list(...)` | Returns a cursor-paginated, filterable, sortable list of scripts |
+| `update(String id, UpdateScriptInput)` | Full replacement (PUT semantics); validates name uniqueness |
+| `delete(String id)` | Soft-deletes by setting status to `DELETED`; idempotent |
+| `loadVisibleOrThrow(...)` | Internal helper treating `DELETED` documents as not found |
+| `loadOrThrow(...)` | Internal helper loading any document regardless of status |
+| `toQueryFilter(ScriptFilterInput)` | Translates API-layer filter DTO to repository-layer `ScriptQueryFilter` |
+
+**Tenant scoping** is resolved via `TenantIdProvider` — JWT claims are deliberately not trusted for tenant scoping to support super-admin tokens safely.
+
+## Usage Example
+
+```java
+// Create
+ScriptResponse created = scriptService.create(
+    CreateScriptInput.builder().name("patch-windows").build()
+);
+
+// Read (throws NotFoundException if deleted or missing)
+ScriptResponse script = scriptService.get("script-id-123");
+
+// Paginated list with filter and sort
+GenericQueryResult<ScriptResponse> page = scriptService.list(
+    ScriptFilterInput.builder().tag("security").build(),
+    "patch",
+    SortInput.builder().field("name").direction(SortDirection.ASC).build(),
+    CursorPaginationCriteria.builder().limit(20).build()
+);
+
+// Update
+ScriptResponse updated = scriptService.update("script-id-123",
+    UpdateScriptInput.builder().name("patch-windows-v2").build()
+);
+
+// Soft-delete (idempotent)
+scriptService.delete("script-id-123");
+```
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.CommandDataFetcher.md b/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.CommandDataFetcher.md
new file mode 100644
index 000000000..9a16bd700
--- /dev/null
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.CommandDataFetcher.md
@@ -0,0 +1,50 @@
+<!-- source-hash: 28e548bd6e69f0c22024f41406ff72b0 -->
+GraphQL mutation resolver for RMM (Remote Monitoring & Management) ad-hoc command dispatch operations. Exposes two mutations for running and cancelling commands on managed devices.
+
+## Key Components
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `commandDispatchService` | `CommandDispatchService` | Injected service handling command dispatch logic |
+| `runCommand` | `@DgsMutation` | Dispatches an ad-hoc command to a remote device |
+| `cancelExecution` | `@DgsMutation` | Cancels a previously dispatched command execution |
+
+## Usage Example
+
+```java
+// GraphQL mutation — run a command
+mutation {
+  runCommand(input: {
+    deviceId: "device-123",
+    command: "ipconfig /all"
+  }) {
+    dispatchId
+    status
+  }
+}
+
+// GraphQL mutation — cancel an execution
+mutation {
+  cancelExecution(input: {
+    dispatchId: "dispatch-456"
+  }) {
+    success
+    message
+  }
+}
+```
+
+```java
+// Direct service delegation (internal)
+RunCommandInput input = new RunCommandInput("device-123", "ipconfig /all");
+CommandDispatchResponse response = commandDispatchService.runCommand(input);
+
+CancelExecutionInput cancelInput = new CancelExecutionInput("dispatch-456");
+CancelDispatchResponse cancelResponse = commandDispatchService.cancelExecution(cancelInput);
+```
+
+## Notes
+
+- Inputs are validated via Jakarta Bean Validation (`@Valid`) and Spring's `@Validated`
+- All business logic is delegated to `CommandDispatchService` — this class is a thin resolver layer
+- Registered as a DGS component, automatically discovered by the Netflix DGS framework
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.NotificationDataFetcher.md b/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.NotificationDataFetcher.md
index bbd5f16df..d7317df9b 100644
--- a/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.NotificationDataFetcher.md
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.NotificationDataFetcher.md
@@ -1,53 +1,49 @@
-<!-- source-hash: f00865072b0dad68d6e8cb0cf52378aa -->
-GraphQL DGS data fetcher that handles all notification-related queries and mutations for authenticated ADMIN and AGENT users, including listing, read-state management, and deletion operations.
+<!-- source-hash: 8e4deb3d7d7977fc6b9f144daafa4ef8 -->
+GraphQL DGS data fetcher that exposes notification queries and mutations for authenticated `ADMIN` and `AGENT` actors, resolving the current recipient from the JWT principal and delegating to `NotificationService` and `NotificationReadStateService`.
 
 ## Key Components
 
 | Member | Type | Description |
-|--------|------|-------------|
-| `notificationNodeId` | `@DgsData` | Encodes the notification's raw ID into a Relay-compliant global ID |
-| `notifications` | `@DgsQuery` | Returns a paginated, cursor-based connection of `NotificationView` items with optional filter and search |
-| `hasUnreadNotifications` | `@DgsQuery` | Returns `true` if the current recipient has any unread notifications |
-| `unreadCountsByCategory` | `@DgsQuery` | Returns per-category unread counts as a list of `UnreadCategoryCount` |
+|---|---|---|
+| `notifications` | `@DgsQuery` | Paginated, filterable list of notifications for the current user or machine |
+| `hasUnreadNotifications` | `@DgsQuery` | Returns `true` if the recipient has any unread notifications |
+| `unreadCountsByCategory` | `@DgsQuery` | Returns per-category unread counts as `List<UnreadCategoryCount>` |
 | `markNotificationAsRead` | `@DgsMutation` | Marks a single notification (by Relay global ID) as read |
-| `markAllNotificationsAsRead` | `@DgsMutation` | Marks all notifications as read; returns count affected |
+| `markAllNotificationsAsRead` | `@DgsMutation` | Marks every notification as read; returns the affected count |
 | `deleteNotification` | `@DgsMutation` | Deletes a single notification by Relay global ID |
-| `deleteAllReadNotifications` | `@DgsMutation` | Deletes all read notifications; returns count deleted |
-| `currentRecipient()` | Private helper | Resolves the caller to a `Recipient` record — `MACHINE` for AGENT actors, `USER` otherwise |
-| `decodeNotificationId()` | Private helper | Decodes and validates a Relay global ID, asserting the `Notification` type |
+| `deleteAllReadNotifications` | `@DgsMutation` | Deletes all read notifications; returns the affected count |
+| `notificationNodeId` | `@DgsData` | Resolves the Relay-spec global `id` field on the `Notification` type |
+| `currentRecipient()` | Private helper | Extracts `RecipientType.USER` or `RecipientType.MACHINE` from the JWT principal |
+| `decodeNotificationId()` | Private helper | Decodes and validates a Relay global ID, asserting it references the `Notification` type |
 
 ## Usage Example
 
 ```java
-# GraphQL — List notifications with pagination and filter
+// GraphQL query — list paginated notifications with an unread filter
 query {
-  notifications(first: 10, filter: { read: false }) {
+  notifications(filter: { read: false }, first: 20, sort: { field: "createdAt", direction: DESC }) {
     edges {
       node {
         id
         title
-        category
+        createdAt
       }
     }
-    pageInfo {
-      hasNextPage
-      endCursor
-    }
+    pageInfo { hasNextPage endCursor }
   }
+  hasUnreadNotifications
+  unreadCountsByCategory { category count }
 }
 
-# GraphQL — Mark a single notification as read
+// GraphQL mutation — mark a single notification as read
 mutation {
-  markNotificationAsRead(notificationId: "Notification:abc123")
+  markNotificationAsRead(notificationId: "Tm90aWZpY2F0aW9uOjEyMw==")
 }
 
-# GraphQL — Unread counts per category
-query {
-  unreadCountsByCategory {
-    category
-    count
-  }
+// GraphQL mutation — bulk delete all read notifications
+mutation {
+  deleteAllReadNotifications
 }
 ```
 
-> All operations require a valid JWT and the `ADMIN` or `AGENT` authority. AGENT actors are resolved to their `machine_id` claim; all other authenticated users resolve to their `userId`.
\ No newline at end of file
+> All operations require a valid JWT with the `ADMIN` or `AGENT` authority. `AGENT` principals must carry a `machine_id` claim; otherwise an `UnauthorizedException` is thrown.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.ScriptDataFetcher.md b/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.ScriptDataFetcher.md
new file mode 100644
index 000000000..bb50361a6
--- /dev/null
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/datafetcher/.ScriptDataFetcher.md
@@ -0,0 +1,48 @@
+<!-- source-hash: 21c8bb7c198735521df77937d16d6ce8 -->
+GraphQL data fetcher (DGS component) for RMM script CRUD operations, acting as a thin passthrough layer between the GraphQL layer and `ScriptService`.
+
+## Key Components
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `script` | `@DgsQuery` | Fetches a single script by ID |
+| `scripts` | `@DgsQuery` | Returns a paginated, filterable, sortable connection of scripts |
+| `createScript` | `@DgsMutation` | Creates a new RMM script |
+| `updateScript` | `@DgsMutation` | Updates an existing script by ID |
+| `deleteScript` | `@DgsMutation` | Deletes a script by ID, returns `true` on success |
+| `ScriptService` | Dependency | Handles business logic and tenant scoping via `TenantIdProvider` |
+| `GraphQLScriptMapper` | Dependency | Maps connection args to pagination criteria and results to GraphQL connections |
+
+## Usage Example
+
+```java
+// Query — fetch a single script
+ScriptResponse s = scriptDataFetcher.script("script-uuid-123");
+
+// Query — paginated list with filter and sort
+GenericConnection<GenericEdge<ScriptResponse>> page = scriptDataFetcher.scripts(
+    ScriptFilterInput.builder().category("maintenance").build(),
+    "disk cleanup",                // free-text search
+    SortInput.builder().field("name").direction(SortDirection.ASC).build(),
+    10,    // first
+    null,  // after cursor
+    null,  // last
+    null   // before cursor
+);
+
+// Mutation — create
+ScriptResponse created = scriptDataFetcher.createScript(
+    CreateScriptInput.builder().name("Disk Cleanup").content("...").build()
+);
+
+// Mutation — update
+ScriptResponse updated = scriptDataFetcher.updateScript(
+    "script-uuid-123",
+    UpdateScriptInput.builder().name("Disk Cleanup v2").build()
+);
+
+// Mutation — delete
+boolean deleted = scriptDataFetcher.deleteScript("script-uuid-123"); // → true
+```
+
+> **Note:** Tenant scoping is resolved inside `ScriptService`. Role-based authorization is not yet enforced at this layer and is planned for a future security pass once the RMM role model is finalized.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/mapper/.GraphQLScriptMapper.md b/openframe-api-service-core/src/main/java/com/openframe/api/mapper/.GraphQLScriptMapper.md
new file mode 100644
index 000000000..2eae1d212
--- /dev/null
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/mapper/.GraphQLScriptMapper.md
@@ -0,0 +1,33 @@
+<!-- source-hash: f648ccff13388e936f22cb149d9fae85 -->
+Assembles Relay-compliant GraphQL Connection envelopes for script queries and converts `ConnectionArgs` into `CursorPaginationCriteria` for the GraphQL layer.
+
+## Key Components
+
+| Method | Description |
+|--------|-------------|
+| `toCursorPaginationCriteria(ConnectionArgs)` | Converts Relay-style connection arguments into cursor pagination criteria via `CursorPaginationCriteria.fromConnectionArgs()` |
+| `toConnection(GenericQueryResult<ScriptResponse>)` | Builds a `GenericConnection` envelope by mapping each `ScriptResponse` item to a `GenericEdge` with a Base64-encoded cursor derived from the script's ID |
+
+## Design Notes
+
+- **Separation of concerns:** Pure entity ↔ DTO mapping is delegated to `ScriptMapper` in `openframe-api-lib`, keeping non-GraphQL callers free from DGS/Relay dependencies.
+- **Mirrors the pattern** established by `GraphQLDeviceMapper` and `GraphQLNotificationMapper`.
+
+## Usage Example
+
+```java
+@Component
+public class ScriptDataFetcher {
+
+    private final GraphQLScriptMapper graphQLScriptMapper;
+
+    public GenericConnection<GenericEdge<ScriptResponse>> getScripts(ConnectionArgs args) {
+        CursorPaginationCriteria criteria =
+            graphQLScriptMapper.toCursorPaginationCriteria(args);
+
+        GenericQueryResult<ScriptResponse> result = scriptService.findAll(criteria);
+
+        return graphQLScriptMapper.toConnection(result);
+    }
+}
+```
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolAgentUpdateService.md b/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolAgentUpdateService.md
index fecda7810..0e347584b 100644
--- a/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolAgentUpdateService.md
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolAgentUpdateService.md
@@ -1,38 +1,37 @@
-<!-- source-hash: 6d29d0e267e59c4393e79c709d44eb1c -->
-Orchestrates forced tool agent update operations across managed machines by validating requests, fetching agent configurations, and publishing update events via NATS messaging.
+<!-- source-hash: 32017c9ddfd80121dd8f26dcd9a722e2 -->
+Handles forced update dispatch for integrated tool agents across one or more managed machines, publishing update messages via NATS and aggregating per-machine results.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `process()` | Public Method | Handles update requests for a specific list of machine IDs |
-| `processAll()` | Public Method | Triggers updates for all registered machines in the repository |
-| `processMachine()` | Private Method | Fetches the tool agent config and publishes the update event for a single machine |
-| `buildResponseItem()` | Private Method | Constructs a `ForceToolAgentUpdateResponseItem` with machine ID, agent ID, and status |
-| `validateToolAgentId()` | Private Method | Guards against blank tool agent IDs |
-| `validateMachineIds()` | Private Method | Guards against empty machine ID lists |
-| `toolAgentUpdateUpdatePublisher` | Dependency | NATS publisher that dispatches the update message to the tool agent |
+| `process(ForceToolAgentUpdateRequest)` | `public` | Dispatches a forced update for a tool agent to a specific list of machine IDs |
+| `processAll(String toolAgentId)` | `public` | Dispatches a forced update for a tool agent to **all** registered machines |
+| `processMachines(List<String>, String)` | `private` | Iterates machine IDs and delegates to `processMachine` |
+| `processMachine(String, String)` | `private` | Looks up the tool agent config, publishes the update via NATS, and returns a `PROCESSED` or `FAILED` status item |
+| `buildResponseItem(...)` | `private` | Constructs a `ForceToolAgentUpdateResponseItem` with machine ID, tool agent ID, and status |
+| `validateToolAgentId` / `validateMachineIds` | `private` | Guards against blank/empty inputs, throwing `IllegalArgumentException` |
 
 ## Usage Example
 
 ```java
-// Force update a specific set of machines
+// Targeted update — specific machines
 ForceToolAgentUpdateRequest request = new ForceToolAgentUpdateRequest();
-request.setToolAgentId("agent-123");
+request.setToolAgentId("zabbix-agent");
 request.setMachineIds(List.of("machine-001", "machine-002"));
 
 ForceToolAgentUpdateResponse response = forceToolAgentUpdateService.process(request);
 response.getItems().forEach(item ->
-    log.info("Machine: {}, Status: {}", item.getMachineId(), item.getStatus())
+    log.info("Machine {} → {}", item.getMachineId(), item.getStatus())
 );
 
-// Force update ALL registered machines for a given agent
-ForceToolAgentUpdateResponse allResponse = forceToolAgentUpdateService.processAll("agent-123");
+// Broadcast update — all registered machines
+ForceToolAgentUpdateResponse broadcastResponse =
+    forceToolAgentUpdateService.processAll("zabbix-agent");
 ```
 
-## Status Outcomes
+## Behavior Notes
 
-Each processed machine returns one of two statuses from `ForceAgentStatus`:
-
-- **`PROCESSED`** — Update event successfully published via NATS
-- **`FAILED`** — Exception occurred (agent not found or publish error); logged and gracefully captured per machine
\ No newline at end of file
+- Each machine is processed independently — a failure on one machine (`FAILED`) does not halt processing of others
+- The update is published via `ToolAgentUpdateUpdatePublisher` (NATS), using the resolved `IntegratedToolAgent` configuration
+- If the tool agent ID is not found in the repository, the machine item is marked `FAILED` and the error is logged
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolInstallationService.md b/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolInstallationService.md
index 043ad134b..eb0100c62 100644
--- a/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolInstallationService.md
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/service/.ForceToolInstallationService.md
@@ -1,35 +1,38 @@
-<!-- source-hash: 2f835c151e4cfc7aa811772db3f348d4 -->
-A Spring service that orchestrates forced tool agent installations and reinstallations across machines, providing batch processing capabilities for both specific machine sets and all available machines.
+<!-- source-hash: 25d09e214a6dc90ba0fa4320c9e8ff32 -->
+Orchestrates forced tool agent installation and reinstallation across managed machines, validating inputs and delegating to underlying installation services per machine.
 
 ## Key Components
 
-- **`process(ForceToolInstallationRequest)`** - Installs a tool agent on specified machines
-- **`processAll(String toolAgentId)`** - Installs a tool agent on all available machines
-- **`processReinstall(ForceToolInstallationRequest)`** - Forces reinstallation on specified machines  
-- **`processReinstallAll(String toolAgentId)`** - Forces reinstallation on all machines
-- **`processMachines(List<String>, String, boolean)`** - Internal batch processor for machine operations
-- **`processMachine(String, String, boolean)`** - Handles individual machine installations with error handling
+| Method | Description |
+|--------|-------------|
+| `process(request)` | Triggers installation for a specific list of machine IDs |
+| `processAll(toolAgentId)` | Triggers installation across all machines in the repository |
+| `processAll(toolAgentId, reinstall)` | Same as above with optional reinstall flag |
+| `processReinstall(request)` | Forces reinstallation for a specific list of machine IDs |
+| `processReinstallAll(toolAgentId)` | Forces reinstallation across all machines |
+| `processMachine(...)` | Per-machine handler; resolves agent config and delegates to `ToolInstallationService` |
+| `buildResponseItem(...)` | Constructs a response item with `PROCESSED` or `FAILED` status |
 
 ## Usage Example
 
 ```java
-@Autowired
-private ForceToolInstallationService forceInstallationService;
-
-// Install tool on specific machines
+// Force install a tool agent on specific machines
 ForceToolInstallationRequest request = new ForceToolInstallationRequest();
-request.setToolAgentId("my-tool-agent");
-request.setMachineIds(Arrays.asList("machine-1", "machine-2"));
-
-ForceToolAgentInstallationResponse response = forceInstallationService.process(request);
+request.setToolAgentId("zabbix-agent");
+request.setMachineIds(List.of("machine-001", "machine-002"));
 
-// Install on all machines
-ForceToolAgentInstallationResponse allResponse = 
-    forceInstallationService.processAll("my-tool-agent");
+ForceToolAgentInstallationResponse response = forceToolInstallationService.process(request);
+response.getItems().forEach(item ->
+    log.info("Machine {} → {}", item.getMachineId(), item.getStatus())
+);
 
-// Force reinstall on specific machines
-ForceToolAgentInstallationResponse reinstallResponse = 
-    forceInstallationService.processReinstall(request);
+// Force reinstall across all machines
+ForceToolAgentInstallationResponse allResponse =
+    forceToolInstallationService.processReinstallAll("zabbix-agent");
 ```
 
-The service validates inputs, retrieves tool agent configurations, and delegates to `ToolInstallationService` while providing comprehensive error handling and status reporting through response items.
\ No newline at end of file
+## Notes
+
+- Each machine is processed independently; failures are caught and returned as `ForceAgentStatus.FAILED` without aborting the batch.
+- Throws `IllegalArgumentException` if `toolAgentId` is blank or `machineIds` is empty.
+- Throws `IllegalStateException` if no agent configuration is found for the given `toolAgentId`.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/service/.NotificationService.md b/openframe-api-service-core/src/main/java/com/openframe/api/service/.NotificationService.md
index c48e59efe..324a20f85 100644
--- a/openframe-api-service-core/src/main/java/com/openframe/api/service/.NotificationService.md
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/service/.NotificationService.md
@@ -1,44 +1,40 @@
-<!-- source-hash: 0265dd1ed4bbf9f5eefdbd373a0021b7 -->
-Provides paginated listing of notifications for a recipient, with support for read/unread filtering, search normalization, and cursor-based pagination.
+<!-- source-hash: 763fa24207f29fcfa67cfe9c1254fbc6 -->
+Handles paginated retrieval of notifications for a given recipient, supporting cursor-based pagination, read/unread filtering, text search, and configurable sort direction.
 
 ## Key Components
 
-| Member | Type | Description |
-|--------|------|-------------|
-| `SEARCH_MIN_LENGTH` | Constant | Minimum character threshold (2) before a search term is applied |
-| `list()` | Method | Fetches a cursor-paginated page of `NotificationView` items for a given recipient |
-| `normalizeSearch()` | Private Method | Trims and nullifies search strings shorter than `SEARCH_MIN_LENGTH` |
-| `buildPageInfo()` | Private Method | Constructs `PageInfo` with cursor positions and forward/backward pagination flags |
+| Member | Description |
+|--------|-------------|
+| `list(...)` | Overloaded public method that fetches a paginated `GenericQueryResult<NotificationView>` for a recipient, with optional `SortInput` |
+| `normalizeSearch(String)` | Trims and nullifies search strings shorter than `SEARCH_MIN_LENGTH` (2 chars) |
+| `resolveSortDirection(SortInput)` | Maps a `SortInput` to `Sort.Direction`; logs a warning and falls back to `DESC` if an invalid field is requested |
+| `buildPageInfo(...)` | Constructs cursor-based `PageInfo` (start/end cursors, `hasNextPage`, `hasPreviousPage`) from the result slice |
+| `ALLOWED_SORT_FIELDS` | Whitelist of valid sort fields: `"id"` and `"createdAt"` |
 
 ## Usage Example
 
 ```java
-// Fetch first page of unread notifications for a user
-NotificationFilter filter = new NotificationFilter(/* read= */ false, /* search= */ null);
-CursorPaginationCriteria pagination = CursorPaginationCriteria.builder()
-        .limit(20)
-        .build();
+// Inject the service
+@Autowired
+private NotificationService notificationService;
 
+// Build filter and pagination
+NotificationFilter filter = new NotificationFilter(/* read= */ false, /* search= */ "alert");
+CursorPaginationCriteria pagination = CursorPaginationCriteria.of(20, null, false);
+SortInput sort = new SortInput("createdAt", SortDirection.DESC);
+
+// Fetch notifications for a user recipient
 GenericQueryResult<NotificationView> result = notificationService.list(
-        "user-123",
-        RecipientType.USER,
-        filter,
-        pagination
+    "user-123",
+    RecipientType.USER,
+    filter,
+    pagination,
+    sort
 );
 
-// Access results
 List<NotificationView> notifications = result.getItems();
 PageInfo pageInfo = result.getPageInfo();
-
-// Fetch next page using end cursor
-CursorPaginationCriteria nextPage = CursorPaginationCriteria.builder()
-        .limit(20)
-        .cursor(pageInfo.getEndCursor())
-        .build();
+// pageInfo.isHasNextPage(), pageInfo.getEndCursor(), etc.
 ```
 
-## Pagination Behavior
-
-- Uses a **limit + 1** fetch strategy to determine if a next/previous page exists without a separate count query.
-- Result order is **reversed** automatically when paginating backward.
-- Cursors are encoded via `CursorCodec` using the notification's ID as the key.
\ No newline at end of file
+> **Note:** When paginating backwards, the result list is automatically reversed before mapping, ensuring consistent chronological ordering regardless of traversal direction.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/service/.ReleaseVersionQueryService.md b/openframe-api-service-core/src/main/java/com/openframe/api/service/.ReleaseVersionQueryService.md
index bbf54cb82..dd43a1dec 100644
--- a/openframe-api-service-core/src/main/java/com/openframe/api/service/.ReleaseVersionQueryService.md
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/service/.ReleaseVersionQueryService.md
@@ -1,13 +1,13 @@
-<!-- source-hash: 4531f7cb8bd0e06a206c37cf6b74051b -->
-Provides read-only access to the current release version of the OpenFrame platform by querying the underlying data store.
+<!-- source-hash: 72292403a22dd54b2c3982563687487b -->
+Provides read-only access to the current release version by querying the underlying repository.
 
 ## Key Components
 
 | Element | Description |
 |---|---|
-| `ReleaseVersionQueryService` | Spring `@Service` bean for querying release version data |
-| `getReleaseVersion()` | Fetches the singleton `ReleaseVersion` document using `ReleaseVersion.DEFAULT_ID` |
-| `ReleaseVersionRepository` | Injected repository (via `@RequiredArgsConstructor`) used to perform the lookup |
+| `ReleaseVersionQueryService` | Spring service bean for retrieving release version metadata |
+| `getReleaseVersion()` | Returns the first available `ReleaseVersion` document wrapped in an `Optional` |
+| `ReleaseVersionRepository` | Injected repository dependency used to query the version data store |
 
 ## Usage Example
 
@@ -27,4 +27,4 @@ public class VersionController {
 }
 ```
 
-> **Note:** `getReleaseVersion()` returns an `Optional<ReleaseVersion>`, so callers should handle the case where no version document has been persisted yet (e.g., on a fresh deployment).
\ No newline at end of file
+> **Note:** `getReleaseVersion()` uses `findFirstBy()` under the hood, meaning it assumes a single version document exists in the data store at any given time. If no document is present, an empty `Optional` is returned rather than throwing an exception.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/main/java/com/openframe/api/service/rmm/.CommandDispatchService.md b/openframe-api-service-core/src/main/java/com/openframe/api/service/rmm/.CommandDispatchService.md
new file mode 100644
index 000000000..24532b1b9
--- /dev/null
+++ b/openframe-api-service-core/src/main/java/com/openframe/api/service/rmm/.CommandDispatchService.md
@@ -0,0 +1,38 @@
+<!-- source-hash: bee0dc0ab619f4ebf84567bfddfc08dc -->
+Handles dispatching ad-hoc shell commands and cancellation requests from the dashboard to remote agents via core NATS (fire-and-forget), with no backend persistence.
+
+## Key Components
+
+| Method | Description |
+|--------|-------------|
+| `runCommand(RunCommandInput)` | Generates a unique `executionId`, builds a `CommandMessage`, and publishes it to the target agent via NATS |
+| `cancelExecution(CancelExecutionInput)` | Builds a `CancelMessage` and publishes a cancel request for an in-flight execution |
+
+**Dependencies:**
+- `CommandNatsPublisher` — handles the underlying NATS publish for both command and cancel messages
+
+## Usage Example
+
+```java
+// Dispatch a shell command to a remote machine
+RunCommandInput input = RunCommandInput.builder()
+    .machineId("agent-abc123")
+    .command("Get-Process")
+    .shell("powershell")
+    .privilegeLevel("admin")
+    .timeoutSeconds(30)
+    .build();
+
+CommandDispatchResponse response = commandDispatchService.runCommand(input);
+String executionId = response.getExecutionId(); // track async result separately
+
+// Cancel an in-flight execution
+CancelExecutionInput cancelInput = CancelExecutionInput.builder()
+    .machineId("agent-abc123")
+    .executionId(executionId)
+    .build();
+
+CancelDispatchResponse cancelResponse = commandDispatchService.cancelExecution(cancelInput);
+```
+
+> **Note:** This service is pure transport — it assigns an `executionId` for correlation but does not store results. Responses from the agent arrive on a separate NATS subject and are handled by the execution service.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.NotificationDataFetcherIT.md b/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.NotificationDataFetcherIT.md
index 302f985bb..6acededed 100644
--- a/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.NotificationDataFetcherIT.md
+++ b/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.NotificationDataFetcherIT.md
@@ -1,46 +1,37 @@
-<!-- source-hash: adf719a2ddea9c324a6288f6b5e39c11 -->
-Integration test suite for the `NotificationDataFetcher` GraphQL layer, verifying end-to-end notification query and mutation behavior against a real MongoDB instance using DGS and Spring Boot test infrastructure.
+<!-- source-hash: 0bb77b7b2d1bfb87cd3c776ebe98af78 -->
+Integration test suite that verifies the `NotificationDataFetcher` GraphQL layer end-to-end against a real MongoDB instance, covering queries, mutations, and JWT-based principal resolution for both admin users and machine agents.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `NotificationDataFetcherIT` | Main test class extending `BaseMongoIntegrationTest`; runs only when `-Dintegration.tests=true` is set |
-| `DgsQueryExecutor` | Executes raw GraphQL query/mutation strings against the full DGS schema |
-| `NotificationReadStateService` | Service under test; used to seed `NotificationReadState` documents before assertions |
-| `MongoTemplate` | Used in `@BeforeEach` to drop and reset `Notification` and `NotificationReadState` collections |
-| `loginAsAdmin` / `loginAsAgent` | Helpers that inject a synthetic `JwtAuthenticationToken` into the `SecurityContextHolder` for role-based test isolation |
-
-## Test Coverage
-
-| Test | Scenario |
-|------|----------|
-| `admin_lists_own_rows` | ADMIN JWT resolves USER-addressed notification rows via `notifications` query |
-| `agent_lists_machine_rows` | AGENT JWT with `machine_id` claim resolves MACHINE-addressed rows |
-| `has_unread` | `hasUnreadNotifications` flips from `true` → `false` after `markRead` |
-| `mark_as_read` | `markNotificationAsRead` mutation accepts a Relay global ID and returns `true` |
-| `mark_all_as_read` | `markAllNotificationsAsRead` returns count of UNREAD rows updated |
-| `delete_notification` | `deleteNotification` mutation soft-deletes a single row by Relay global ID |
-| `delete_all_read` | `deleteAllReadNotifications` transitions only READ rows to DELETED |
-| `unread_counts_by_category` | `unreadCountsByCategory` returns one entry per category in UNREAD rows |
+- **`admin_lists_own_rows`** — Confirms an ADMIN JWT principal retrieves only their own `USER`-addressed read-state rows via the `notifications` query.
+- **`agent_lists_machine_rows`** — Confirms an AGENT JWT principal with a `machine_id` claim retrieves `MACHINE`-addressed rows without requiring an explicit schema argument.
+- **`has_unread`** — Verifies `hasUnreadNotifications` returns `true` for unread rows and flips to `false` after `markRead` is called.
+- **`mark_as_read`** — Exercises the `markNotificationAsRead` mutation using a Relay global ID and asserts the mutation returns `true`.
+- **`mark_all_as_read`** — Exercises `markAllNotificationsAsRead` and asserts the returned count equals the number of unread rows.
+- **`delete_notification`** — Exercises `deleteNotification` with a Relay global ID and asserts soft-deletion (returns `true`).
+- **`delete_all_read`** — Exercises `deleteAllReadNotifications` and asserts only READ rows are transitioned to DELETED.
+- **`admin_lists_oldest_first_with_sort_asc`** — Verifies `sort: { direction: ASC }` returns edges oldest-first.
+- **`admin_lists_newest_first_by_default`** — Verifies default sort order is newest-first (DESC) when no `sort` argument is provided.
 
 ## Usage Example
 
 ```java
-// Run integration tests (requires a running MongoDB; enable via system property)
-./mvnw verify -Dintegration.tests=true
+// Run integration tests with the required system property
+// mvn verify -Dintegration.tests=true
+
+// Typical test pattern used throughout the suite
+loginAsAdmin(ALICE);
+Notification n = mongoTemplate.save(NotificationFixtures.basic("welcome"));
+readStateService.createForAudience(
+    n.getId(), NotificationCategory.TICKETS, "title",
+    RecipientType.USER, Set.of(ALICE)
+);
 
-// Example query exercised in tests
-queryExecutor.execute("""
+ExecutionResult res = queryExecutor.execute("""
     query { notifications(first: 10) { edges { node { id title read } } } }
 """);
-
-// Example mutation with Relay global ID
-String globalId = new Relay().toGlobalId("Notification", n.getId());
-queryExecutor.execute(
-    "mutation($id: ID!) { markNotificationAsRead(notificationId: $id) }",
-    Map.of("id", globalId)
-);
+assertThat(res.getErrors()).isEmpty();
+assertThat(edges(res)).hasSize(1);
 ```
 
-> **Note:** Tests are gated by `@EnabledIfSystemProperty(named = "integration.tests", matches = "true")` and tagged `@Tag("integration")`. Cloud Stream auto-configurations are excluded to prevent messaging infrastructure from being required at test startup.
\ No newline at end of file
+> **Note:** Tests are gated behind `-Dintegration.tests=true` and require a running MongoDB instance provided by `BaseMongoIntegrationTest`. Spring Cloud Stream auto-configurations are excluded to keep the test context lightweight.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.TestApprovalContext.md b/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.TestApprovalContext.md
index 9cc6371c9..e670a1ef3 100644
--- a/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.TestApprovalContext.md
+++ b/openframe-api-service-core/src/test/java/com/openframe/api/integration/datafetcher/notification/.TestApprovalContext.md
@@ -1,24 +1,33 @@
-<!-- source-hash: 3de3c0fa9e7b37ec0787d06c7f1ca386 -->
-A data model class representing the context payload for test approval notifications, extending the base `NotificationContext` with ticket and approval request identifiers.
+<!-- source-hash: 963db2a6dd09b3880b0462661c75bffd -->
+A notification context payload for test approval workflow events, extending `NotificationContext` to carry ticket and approval request identifiers.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `ticketId` | `String` | Identifier of the associated support ticket |
-| `approvalRequestId` | `String` | Identifier of the approval request being tested |
-
-Inherits all fields and behavior from `NotificationContext` via Lombok's `@SuperBuilder`, `@EqualsAndHashCode(callSuper = true)`, and `@ToString(callSuper = true)`.
+| `TYPE` | `String` constant | Discriminator value sourced from `TestApprovalContextDescriptor.TYPE` |
+| `ticketId` | `String` | Reference to the associated support ticket |
+| `approvalRequestId` | `String` | Reference to the specific approval request |
+| `getType()` | `@Override` method | Returns the fixed `TYPE` discriminator for polymorphic serialization |
 
 ## Usage Example
 
 ```java
-// Build a TestApprovalContext using the generated builder
-TestApprovalContext context = TestApprovalContext.builder()
-    .ticketId("TKT-1234")
+TestApprovalContext ctx = TestApprovalContext.builder()
+    .ticketId("TICK-1234")
     .approvalRequestId("APR-5678")
     .build();
 
-// Pass context to a notification dispatcher
-notificationService.sendTestApproval(context);
-```
\ No newline at end of file
+// Type discriminator is readable but excluded from deserialization input
+String type = ctx.getType(); // → TestApprovalContextDescriptor.TYPE
+
+// Typically attached to a Notification before dispatch
+Notification notification = Notification.builder()
+    .context(ctx)
+    .build();
+```
+
+## Notes
+
+- `@JsonIgnoreProperties(value = "type", allowGetters = true)` ensures the `type` field is **serialized** (readable) but **ignored on deserialization**, preventing conflicts during polymorphic JSON mapping.
+- Inherits base fields and behavior from `NotificationContext` via `@SuperBuilder` and `callSuper = true` on `@EqualsAndHashCode` / `@ToString`.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/test/java/com/openframe/api/integration/service/.NotificationServiceIT.md b/openframe-api-service-core/src/test/java/com/openframe/api/integration/service/.NotificationServiceIT.md
index 06ca94d6d..92883be28 100644
--- a/openframe-api-service-core/src/test/java/com/openframe/api/integration/service/.NotificationServiceIT.md
+++ b/openframe-api-service-core/src/test/java/com/openframe/api/integration/service/.NotificationServiceIT.md
@@ -1,50 +1,47 @@
-<!-- source-hash: 0486b351401c69ade344597b6b93a20d -->
-Integration test suite for `NotificationService.list()`, validating pagination behavior, read-flag merging, audience isolation, search normalization, and soft-delete exclusion against a real MongoDB instance.
+<!-- source-hash: 9c786fb59850257d5c2143d078bad36f -->
+Integration test suite for `NotificationService.list()`, verifying pagination, read-flag merging, audience isolation, search normalization, soft-delete exclusion, and sort behavior against a real MongoDB instance.
 
 ## Key Components
 
 | Component | Role |
-|---|---|
-| `NotificationService` | Service under test — handles `list()` with filters and cursor pagination |
-| `NotificationReadStateService` | Creates and mutates read-state records used by `list()` |
-| `BaseMongoIntegrationTest` | Base class providing embedded/real MongoDB wiring |
-| `NotificationFixtures` | Helper that constructs `Notification` documents for seeding |
-| `NotificationFilter` | Filter DTO accepting `read` boolean and search string |
-| `CursorPaginationCriteria` | Pagination input (limit-based cursor) |
-
-## Test Coverage
-
-| Test | Scenario |
-|---|---|
-| `list_user_with_read_flag` | Read state is merged into `NotificationView.read` |
-| `list_machine_recipient` | `RecipientType.MACHINE` audience visibility works |
-| `audience_isolation_by_id` | Notifications scoped to other users are hidden |
-| `audience_isolation_by_type` | Same ID, different `RecipientType` → isolated pages |
-| `read_filter_narrows_page` | `read=true` / `read=false` filters return correct rows |
-| `short_search_normalized_to_no_search` | 1-char search terms are ignored |
-| `whitespace_search_normalized_to_no_search` | Whitespace-only search is treated as no-op |
-| `search_no_match_returns_empty_page` | Non-matching search returns empty page with `hasNextPage=false` |
-| `deleted_excluded` | Soft-deleted read states are excluded from listing |
+|-----------|------|
+| `NotificationServiceIT` | Main test class extending `BaseMongoIntegrationTest` |
+| `NotificationService` | Service under test — `list()` method with filtering, pagination, and sort |
+| `NotificationReadStateService` | Supporting service for seeding read-state rows and marking notifications |
+| `NotificationFixtures` | Test data factory for building `Notification` documents |
+| `NotificationFilter` | Filter DTO controlling `read` flag and search term |
+| `CursorPaginationCriteria` | Cursor-based pagination input (limit, cursor) |
+| `SortInput` / `SortDirection` | Sort configuration passed to the 5-arg `list()` overload |
 
 ## Usage Example
 
 ```java
-// Seed a notification and mark it read for a user
+// Seed a notification and a read-state row, then assert the view reflects the read flag
 Notification n = mongoTemplate.save(NotificationFixtures.basic("welcome"));
-readStateService.createForAudience(
-    n.getId(), NotificationCategory.TICKETS, "title", RecipientType.USER, Set.of("user-alice")
-);
-readStateService.markRead("user-alice", RecipientType.USER, n.getId());
-
-// List with no filter — returns the notification with read=true
-GenericQueryResult<NotificationView> result = notificationService.list(
-    "user-alice",
-    RecipientType.USER,
-    NotificationFilter.EMPTY,
-    CursorPaginationCriteria.builder().limit(10).build()
-);
+readStateService.createForAudience(n.getId(), NotificationCategory.TICKETS, "title", U, Set.of(ALICE));
+readStateService.markRead(ALICE, U, n.getId());
 
+GenericQueryResult<NotificationView> result =
+    notificationService.list(ALICE, U, NotificationFilter.EMPTY, page10());
+
+assertThat(result.getItems()).hasSize(1);
 assertThat(result.getItems().get(0).read()).isTrue();
 ```
 
-> **Note:** Tests are gated by the system property `integration.tests=true` and require a live MongoDB connection. Operations on `markRead`, `markAllAsRead`, `delete`, `hasUnread`, and counts are covered in `NotificationReadStateServiceIT`.
\ No newline at end of file
+## Test Coverage
+
+| Scenario | Assertion |
+|----------|-----------|
+| Read flag merge | `NotificationView.read()` reflects `ReadStatus` |
+| Audience isolation by ID | Caller only sees their own `read_state` rows |
+| Audience isolation by type | `USER` vs `MACHINE` rows are non-overlapping |
+| Read/unread filter | `NotificationFilter(true/false, null)` narrows results correctly |
+| Short search term (`< 2` chars) | Normalized to no-search; full page returned |
+| Whitespace-only search | Trimmed to empty; full page returned |
+| Search with no match | Empty page, `hasNextPage=false` |
+| Soft-deleted notifications | Excluded from default listings |
+| Sort `ASC` | Oldest-first ordering |
+| Sort `null` | Defaults to newest-first (`DESC`) |
+| Sort with unsupported field | Unknown field ignored; direction still honored |
+
+> **Note:** `markRead`, `markAllAsRead`, `delete`, `hasUnread`, and counts are covered in `NotificationReadStateServiceIT`, not here.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/test/java/com/openframe/api/mapper/.ScriptMapperTest.md b/openframe-api-service-core/src/test/java/com/openframe/api/mapper/.ScriptMapperTest.md
new file mode 100644
index 000000000..44d9d9e75
--- /dev/null
+++ b/openframe-api-service-core/src/test/java/com/openframe/api/mapper/.ScriptMapperTest.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 008ee76e6ca3ddd975a3f6c3c5423cce -->
+Unit tests for `ScriptMapper#updateEntity`, verifying PUT semantics — that every writable field is correctly overwritten on the entity, including explicit `null` values that must clear previously-set data.
+
+## Key Components
+
+| Test | Description |
+|------|-------------|
+| `updateEntity_nullsInInput_clearFieldsOnEntity` | Asserts all writable fields are set to `null` when input has no values set |
+| `updateEntity_doesNotTouchInternalFields` | Confirms `id` and `tenantId` are never modified by the mapper |
+| `updateEntity_fullyPopulatedInput_overwritesAllFields` | Validates a fully populated `UpdateScriptInput` overwrites every writable field |
+| `updateEntity_emptyListInput_clearsListField` | Ensures empty lists (`[]`) explicitly clear list fields rather than being ignored |
+| `fullyPopulated()` | Private builder helper that constructs a `Script` with all fields set, used as the baseline entity across tests |
+
+## Usage Example
+
+```java
+// The mapper is instantiated directly (no Spring context needed)
+ScriptMapper mapper = new ScriptMapper();
+
+// Build a pre-existing entity
+Script existing = Script.builder()
+        .id("65f4a8000000000000000001")
+        .tenantId("tenant-1")
+        .name("Restart Spooler")
+        .shell(ScriptShell.POWERSHELL)
+        .build();
+
+// Apply a partial update — null fields will clear existing values (PUT semantics)
+UpdateScriptInput input = new UpdateScriptInput();
+input.setName("New Name");
+// description left null → will clear existing description
+
+mapper.updateEntity(existing, input);
+// existing.getName()        → "New Name"
+// existing.getDescription() → null  (cleared)
+// existing.getId()          → "65f4a8000000000000000001" (untouched)
+```
+
+> **Note:** `ScriptServiceTest` mocks the mapper; these tests exercise the real mapper instance to validate actual field-overwrite behaviour, including the distinction between `null` and empty `List.of()` inputs.
\ No newline at end of file
diff --git a/openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.CommandDispatchServiceTest.md b/openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.CommandDispatchServiceTest.md
new file mode 100644
index 000000000..bc57507db
--- /dev/null
+++ b/openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.CommandDispatchServiceTest.md
@@ -0,0 +1,43 @@
+<!-- source-hash: 7d38c8be3ce3a6e2aeb1b8746bdb6327 -->
+Unit test suite for `CommandDispatchService`, verifying command dispatch and cancellation behavior via NATS messaging in the OpenFrame RMM platform.
+
+## Key Components
+
+- **`runCommand` tests** — Validates that `CommandDispatchService.runCommand()` generates a unique `executionId`, correctly maps all fields from `RunCommandInput` (shell, command, privilege level, optional timeout) into a `CommandMessage`, and publishes it to the correct machine subject via `CommandNatsPublisher`.
+- **`cancelExecution` tests** — Validates that `cancelExecution()` relays the caller-supplied `executionId` verbatim in a `CancelMessage`, routes through `publishCancel` (not `publishCommand`), and never mints a new execution ID.
+- **`CommandNatsPublisher` (mock)** — Injected mock used with `ArgumentCaptor` to assert exact wire-payload contents without a live NATS broker.
+
+## Usage Example
+
+```java
+// Typical test pattern: capture and assert the published CommandMessage
+@Test
+void runCommand_publishesAndReturnsExecutionId() {
+    CommandDispatchResponse response = commandDispatchService.runCommand(input);
+
+    // Execution ID is non-blank and echoed in the response
+    assertThat(response.getExecutionId()).isNotBlank();
+
+    // Capture the exact message sent over NATS
+    ArgumentCaptor<CommandMessage> captor = ArgumentCaptor.forClass(CommandMessage.class);
+    verify(commandNatsPublisher).publishCommand(eq(MACHINE_ID), captor.capture());
+
+    CommandMessage sent = captor.getValue();
+    assertThat(sent.getExecutionId()).isEqualTo(response.getExecutionId());
+    assertThat(sent.getShell()).isEqualTo(ScriptShell.BASH);
+    assertThat(sent.getPrivilegeLevel()).isEqualTo(PrivilegeLevel.ADMIN);
+    assertThat(sent.getTimeout()).isNull(); // agent default applies
+}
+```
+
+## Test Coverage Summary
+
+| Scenario | Assertion Focus |
+|---|---|
+| `runCommand` basic dispatch | Non-blank ID, correct NATS subject, full payload mapping |
+| Privilege level forwarding | `USER` vs `ADMIN` not collapsed to a backend default |
+| Optional timeout forwarding | Timeout passed verbatim, not modified |
+| Distinct execution IDs | No global state leakage across invocations |
+| `cancelExecution` relay | Caller ID echoed verbatim, `CancelMessage` published |
+| Cancel idempotency | Same ID relayed on repeated calls |
+| Routing isolation | `publishCancel` and `publishCommand` use separate paths |
\ No newline at end of file
diff --git a/openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.ScriptServiceTest.md b/openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.ScriptServiceTest.md
new file mode 100644
index 000000000..2e11ee374
--- /dev/null
+++ b/openframe-api-service-core/src/test/java/com/openframe/api/service/rmm/.ScriptServiceTest.md
@@ -0,0 +1,47 @@
+<!-- source-hash: 42e09e80222e4143262d4f51943b373e -->
+Unit test suite for `ScriptService`, covering CRUD operations, cursor-based pagination, and tenant-scoped data access using Mockito and AssertJ.
+
+## Key Components
+
+| Component | Role |
+|-----------|------|
+| `ScriptServiceTest` | Main test class wiring `ScriptService` under test via `@InjectMocks` |
+| `ScriptRepository` (mock) | Simulates MongoDB document persistence and paginated queries |
+| `ScriptMapper` (mock) | Validates entity↔DTO mapping is delegated correctly |
+| `TenantIdProvider` (mock) | Provides tenant isolation (`tenant-1`) across all test scenarios |
+
+**Test methods:**
+
+- `create_whenNameUnique_persistsAndReturnsResponse` — happy path: entity is saved and response returned
+- `create_whenNameAlreadyExists_throwsConflict` — duplicate name within tenant throws `ConflictException`
+- `create_whenInputHasEnvVars_persistsThemThroughTheMapper` — env vars (including secrets) flow through mapper
+- `get_whenExists_returnsResponse` — tenant-scoped lookup returns mapped DTO
+- `get_whenNotFound_throwsNotFound` — missing script throws `NotFoundException`
+- `list_forwardFirstPage_dropsSentinelAndReportsHasNext` — forward pagination drops `limit+1` sentinel, sets `hasNextPage=true`
+- `list_forwardLastPage_hasNoNext` — last page correctly sets `hasNextPage=false`
+- `list_backwardPagination_reversesItemsAndFlipsHasMore` — backward cursor reverses item order and maps `hasMore` to `hasPreviousPage`
+- `list_emptyResult_returnsEmptyPageInfo` — empty dataset returns null cursors and `false` flags
+- `list_normalisesPaginationCriteria` — null `limit` is normalized before repository call
+
+## Usage Example
+
+```java
+// Typical forward pagination test pattern used in this suite
+CursorPaginationCriteria criteria = CursorPaginationCriteria.builder()
+        .limit(2)
+        .cursor(null)
+        .backward(false)
+        .build();
+
+when(scriptRepository.findPageForTenant(
+        eq(TENANT_ID), eq(null), eq(null),
+        eq("_id"), eq(Sort.Direction.DESC),
+        eq(null), eq(false), eq(3)))   // limit+1 sentinel fetch
+        .thenReturn(List.of(s1, s2, s3));
+
+GenericQueryResult<ScriptResponse> result = scriptService.list(null, null, null, criteria);
+
+assertThat(result.getItems()).hasSize(2);                        // sentinel dropped
+assertThat(result.getPageInfo().isHasNextPage()).isTrue();
+assertThat(result.getPageInfo().isHasPreviousPage()).isFalse(); // first page, no cursor supplied
+```
\ No newline at end of file
diff --git a/openframe-authorization-service-core/src/main/java/com/openframe/authz/exception/.OwnerCannotSwitchTenantException.md b/openframe-authorization-service-core/src/main/java/com/openframe/authz/exception/.OwnerCannotSwitchTenantException.md
new file mode 100644
index 000000000..1f7da713f
--- /dev/null
+++ b/openframe-authorization-service-core/src/main/java/com/openframe/authz/exception/.OwnerCannotSwitchTenantException.md
@@ -0,0 +1,19 @@
+<!-- source-hash: c5daa5b99ed6d57bab11141de5ef2e7e -->
+A specialized exception thrown when a tenant owner attempts to switch to a different tenant, which is a restricted operation in OpenFrame's authorization model.
+
+## Key Components
+
+- **`OwnerCannotSwitchTenantException`** — Extends `ConflictException` (HTTP 409), signaling a business rule violation rather than a system error.
+- **`ErrorCode.OWNER_CANNOT_SWITCH_TENANT`** — Structured error code passed to the parent for consistent API error responses.
+- **Constructor parameter:** `email` — The owner's email address, appended to the message for traceability.
+
+## Usage Example
+
+```java
+// Thrown during tenant-switch validation in the authorization service
+if (user.isOwner()) {
+    throw new OwnerCannotSwitchTenantException(user.getEmail());
+}
+```
+
+> Tenant owners are bound to their originating tenant. Attempting to switch tenants results in a `409 Conflict` response with error code `OWNER_CANNOT_SWITCH_TENANT`.
\ No newline at end of file
diff --git a/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/processor/.RegistrationProcessor.md b/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/processor/.RegistrationProcessor.md
index 28862a828..8842df0bd 100644
--- a/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/processor/.RegistrationProcessor.md
+++ b/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/processor/.RegistrationProcessor.md
@@ -1,43 +1,38 @@
-<!-- source-hash: 94a080f023c72101ebf540eef957362c -->
-Defines a hook-based interface for intercepting registration lifecycle events across tenant, invitation, and SSO auto-provisioning flows.
+<!-- source-hash: c53ec51e7b9ccc007ca7ed0767555012 -->
+Defines the `RegistrationProcessor` interface, providing pre/post processing hooks for tenant registration, invitation-based registration, SSO auto-provisioning, and tenant ID reservation.
 
 ## Key Components
 
-| Method | Trigger Point |
+| Method | Description |
 |---|---|
-| `preProcessTenantRegistration` | Before tenant registration logic executes |
-| `postProcessTenantRegistration` | After a tenant and user are successfully created |
-| `postProcessInvitationRegistration` | After a user registers via invitation link |
-| `postProcessAutoProvision` | After SSO first-login provisioning or subsequent SSO profile refresh |
+| `preProcessTenantRegistration` | Hook called before tenant registration logic executes |
+| `postProcessTenantRegistration` | Hook called after successful tenant registration, receives the created `Tenant` and `AuthUser` |
+| `postProcessInvitationRegistration` | Hook called after a user registers via an invitation link |
+| `postProcessAutoProvision` | Hook for SSO first-login provisioning and subsequent profile refresh (supports optional `pictureUrl`) |
+| `reserveTenantIdForRegistration` | Returns the `tenantId` for the new tenant — defaults to a fresh UUID; SaaS implementations atomically claim a pre-generated ID from a READY cluster |
 
-All methods provide default no-op implementations, making partial implementation safe — only override the hooks relevant to your use case.
+All methods ship as **no-op defaults**, so implementors only override what they need.
 
 ## Usage Example
 
 ```java
 @Component
-public class AuditRegistrationProcessor implements RegistrationProcessor {
-
-    private final AuditService auditService;
+public class CustomRegistrationProcessor implements RegistrationProcessor {
 
     @Override
     public void postProcessTenantRegistration(
-            Tenant tenant,
-            AuthUser user,
-            TenantRegistrationRequest request) {
-        auditService.logTenantCreated(tenant.getId(), user.getId());
+            Tenant tenant, AuthUser user, TenantRegistrationRequest request) {
+        // Send welcome email, provision default resources, etc.
+        notificationService.sendWelcome(user.getEmail(), tenant.getTenantId());
     }
 
     @Override
-    public void postProcessAutoProvision(AuthUser user, String pictureUrl) {
-        if (pictureUrl != null) {
-            auditService.logProfilePictureUpdated(user.getId(), pictureUrl);
-        }
+    public String reserveTenantIdForRegistration(TenantRegistrationRequest request) {
+        // SaaS: claim a pre-provisioned cluster ID
+        return clusterPoolService.claimNextReadyTenantId();
     }
 
     // preProcessTenantRegistration and postProcessInvitationRegistration
-    // intentionally left as no-ops via default implementations
+    // remain as no-ops via default interface methods
 }
-```
-
-> Implement this interface to inject custom business logic — such as audit logging, welcome emails, or CRM sync — at any stage of the registration pipeline without modifying core auth flows.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/user/.InvitationRegistrationService.md b/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/user/.InvitationRegistrationService.md
index 38704311e..78fc48180 100644
--- a/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/user/.InvitationRegistrationService.md
+++ b/openframe-authorization-service-core/src/main/java/com/openframe/authz/service/user/.InvitationRegistrationService.md
@@ -1,36 +1,57 @@
-<!-- source-hash: 78956d4215554e13d41b1450fa20da10 -->
-Service that handles user registration through invitation links in the OpenFrame multi-tenant authentication system. It manages tenant switching, user deactivation, and invitation acceptance workflows.
+<!-- source-hash: 0dd500b74c53072d63e3581f2726c340 -->
+Handles the full registration flow for invitation-based user sign-ups, resolving tenant assignment, managing existing active users, and finalizing invitation acceptance.
 
 ## Key Components
 
-- **registerByInvitation()** - Main entry point that processes invitation registration requests
-- **handleExistingActiveUser()** - Manages scenarios where user already exists in same or different tenant
-- **createUserForInvitation()** - Creates new user account from invitation details
-- **acceptInvitation()** - Marks invitation as accepted and triggers post-processing
-- **resolveTargetTenantId()** - Determines target tenant based on local tenant configuration
+| Member | Type | Description |
+|--------|------|-------------|
+| `registerByInvitation` | `public` | Entry point — validates invitation, resolves tenant, creates or reuses user, and accepts the invitation |
+| `resolveTargetTenantId` | `private` | Returns the first local tenant ID when `localTenant=true`, otherwise uses the tenant from the invitation |
+| `handleExistingActiveUser` | `private` | Handles collision when an active user already exists for the invited email — reuse, deactivate, or throw |
+| `createUserForInvitation` | `private` | Delegates new user creation to `UserService` using invitation and request data |
+| `acceptInvitation` | `private` | Marks invitation as `ACCEPTED`, persists it, and triggers post-processing |
+| `markVerifiedQuietly` | `private` | Silently marks email as verified; swallows exceptions to avoid blocking acceptance |
+
+## Configuration
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `openframe.tenancy.local-tenant` | `false` | When `true`, forces all invitations to resolve to the first tenant in the repository |
+
+## Tenant Switch Logic
+
+```mermaid
+graph TD
+    A["registerByInvitation()"] --> B["loadAndEnsureAcceptable()"]
+    B --> C["findActiveByEmail()"]
+    C --> D{"Existing user?"}
+    D -->|"No"| E["createUserForInvitation()"]
+    D -->|"Yes, same tenant"| F["reuse existing user"]
+    D -->|"Yes, different tenant"| G{"switchTenant=true?"}
+    G -->|"No"| H["UserActiveInAnotherTenantException"]
+    G -->|"Yes"| I{"Has OWNER role?"}
+    I -->|"Yes"| J["OwnerCannotSwitchTenantException"]
+    I -->|"No"| K["deactivateUser() + create new"]
+    E --> L["acceptInvitation()"]
+    F --> L
+    K --> L
+```
 
 ## Usage Example
 
 ```java
-@Autowired
-private InvitationRegistrationService registrationService;
-
-public void processUserInvitation() {
-    InvitationRegistrationRequest request = InvitationRegistrationRequest.builder()
-        .invitationId("inv-123")
-        .firstName("John")
-        .lastName("Doe")
-        .password("securePassword123")
-        .switchTenant(true) // Allow switching from current tenant
-        .build();
-    
-    try {
-        AuthUser newUser = registrationService.registerByInvitation(request);
-        log.info("User registered successfully: {}", newUser.getEmail());
-    } catch (UserActiveInAnotherTenantException e) {
-        log.error("User already active in different tenant: {}", e.getMessage());
-    }
-}
+// Called from a registration controller after user submits invitation form
+InvitationRegistrationRequest request = InvitationRegistrationRequest.builder()
+    .invitationId("inv_abc123")
+    .firstName("Jane")
+    .lastName("Doe")
+    .password("s3cur3P@ss")
+    .switchTenant(false)
+    .build();
+
+AuthUser registeredUser = invitationRegistrationService.registerByInvitation(request);
+// registeredUser is now active in the invitation's target tenant
+// invitation status set to ACCEPTED
 ```
 
-The service supports tenant switching scenarios - if a user is already active in another tenant and `switchTenant=true`, it deactivates the existing user account before creating a new one in the target tenant. For local tenant deployments, it automatically resolves to the first available tenant.
\ No newline at end of file
+> **Note:** Setting `switchTenant=true` deactivates the user's current tenant membership before registering under the new one. Users with the `OWNER` role are never permitted to switch tenants and will always throw `OwnerCannotSwitchTenantException`.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/config/.AsyncConfig.md b/openframe-client-core/src/main/java/com/openframe/client/config/.AsyncConfig.md
new file mode 100644
index 000000000..9c6d10a95
--- /dev/null
+++ b/openframe-client-core/src/main/java/com/openframe/client/config/.AsyncConfig.md
@@ -0,0 +1,32 @@
+<!-- source-hash: 1610bb2c9adc2527e8f734be0f19f0fc -->
+Configures asynchronous task execution for the OpenFrame client, enabling Spring's async processing with a virtual-thread-based executor optimized for tool installation tasks.
+
+## Key Components
+
+| Element | Description |
+|---------|-------------|
+| `AsyncConfig` | Spring `@Configuration` class that enables async processing via `@EnableAsync` |
+| `TOOL_INSTALL_EXECUTOR` | Constant (`"toolInstallExecutor"`) used to reference the named executor bean |
+| `toolInstallExecutor()` | Bean that wraps Java 21 virtual threads (`Executors.newVirtualThreadPerTaskExecutor()`) via `TaskExecutorAdapter` |
+
+## Usage Example
+
+Inject the executor by name into any Spring component to run tool installation tasks asynchronously on lightweight virtual threads:
+
+```java
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Service;
+
+@Service
+public class ToolInstallService {
+
+    @Async(AsyncConfig.TOOL_INSTALL_EXECUTOR)
+    public CompletableFuture<Void> installTool(String toolId) {
+        // Runs on a virtual thread - ideal for I/O-bound install operations
+        performInstallation(toolId);
+        return CompletableFuture.completedFuture(null);
+    }
+}
+```
+
+> **Note:** Uses Java 21 virtual threads (`Project Loom`), making it well-suited for I/O-bound workloads like downloading, installing, or configuring MSP tools — where high concurrency is needed without the overhead of platform threads.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/controller/.AgentController.md b/openframe-client-core/src/main/java/com/openframe/client/controller/.AgentController.md
index 2303b4c4c..5b4fc8e4a 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/controller/.AgentController.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/controller/.AgentController.md
@@ -1,31 +1,39 @@
-<!-- source-hash: cddddfc82b8f341f21174499ba5a40f3 -->
-A Spring Boot REST controller that handles agent registration functionality for the OpenFrame client system through a secure API endpoint.
+<!-- source-hash: 39e60a8110817afd576460c33231d663 -->
+REST controller handling agent registration and reinstallation endpoints for the OpenFrame platform, exposing two authenticated operations under `/api/agents`.
 
 ## Key Components
 
-- **AgentController**: Main REST controller class that exposes agent-related endpoints
-- **register()**: POST endpoint that handles agent registration with initial key authentication
-- **AgentRegistrationService**: Injected service that contains the business logic for agent registration
-- **Security Headers**: Uses `X-Initial-Key` header for authentication during registration
+| Element | Description |
+|---|---|
+| `AgentController` | `@RestController` mapped to `/api/agents` |
+| `POST /register` | Registers a new agent using an initial key and registration payload |
+| `POST /reinstall` | Reinstalls an existing agent using initial key, machine ID, and client secret |
+| `AgentRegistrationService` | Delegated service handling registration business logic |
+
+### Request Headers
+
+| Header | Endpoint(s) | Purpose |
+|---|---|---|
+| `X-Initial-Key` | Both | Bootstrap authentication key |
+| `X-Machine-Id` | `/reinstall` only | Identifies the existing machine |
+| `X-Client-Secret` | `/reinstall` only | Authenticates the existing agent |
 
 ## Usage Example
 
 ```java
-// Example request to register an agent
-@PostMapping("/register")
-public ResponseEntity<AgentRegistrationResponse> register(
-    @RequestHeader("X-Initial-Key") String initialKey,
-    @Valid @RequestBody AgentRegistrationRequest request) {
-    
-    // Service handles validation and registration logic
-    AgentRegistrationResponse response = agentRegistrationService.register(initialKey, request);
-    return ResponseEntity.ok(response);
-}
-
-// Example client usage (conceptual)
-// POST /api/agents/register
-// Headers: X-Initial-Key: your-initial-key
-// Body: AgentRegistrationRequest JSON payload
+// Register a new agent
+POST /api/agents/register
+Headers:
+  X-Initial-Key: <bootstrap-key>
+Body: AgentRegistrationRequest { ... }
+
+// Reinstall an existing agent
+POST /api/agents/reinstall
+Headers:
+  X-Initial-Key:     <bootstrap-key>
+  X-Machine-Id:      <machine-uuid>
+  X-Client-Secret:   <agent-secret>
+Body: AgentRegistrationRequest { ... }
 ```
 
-The controller uses constructor injection via Lombok's `@RequiredArgsConstructor` and validates incoming requests with `@Valid`. All agent registration requests require an initial authentication key provided through the `X-Initial-Key` header for security purposes.
\ No newline at end of file
+Both endpoints return an `AgentRegistrationResponse` and enforce `@Valid` bean validation on the request body. Authentication credentials are passed exclusively via HTTP headers, keeping them out of the request body.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/dto/agent/.AgentRegistrationRequest.md b/openframe-client-core/src/main/java/com/openframe/client/dto/agent/.AgentRegistrationRequest.md
index e1d54a2d3..5eff5f666 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/dto/agent/.AgentRegistrationRequest.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/dto/agent/.AgentRegistrationRequest.md
@@ -1,59 +1,48 @@
-<!-- source-hash: 1741d5e78c54af55efab58aae59b6413 -->
-Data Transfer Object (DTO) used to capture all device metadata submitted by an agent during the registration process with the OpenFrame platform.
+<!-- source-hash: 32094505ee8f3188887bffcdbdc335d6 -->
+Data Transfer Object (DTO) for registering a new agent/device with the OpenFrame platform, capturing device identity, network details, hardware specs, OS information, and optional tags.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `hostname` | `String` | Device hostname |
-| `organizationId` | `String` | Target organization for the device |
-| `ip` | `String` | Device IP address |
-| `macAddress` | `String` | Network MAC address |
-| `osUuid` | `String` | OS-level unique identifier |
-| `agentVersion` | `String` | **Required** — agent version string |
-| `status` | `DeviceStatus` | Current device status enum |
-| `displayName` | `String` | Human-readable device name |
-| `serialNumber` | `String` | Hardware serial number |
-| `manufacturer` | `String` | Device manufacturer |
-| `model` | `String` | Device model identifier |
-| `type` | `DeviceType` | Device type enum |
-| `osType` / `osVersion` / `osBuild` | `String` | OS details |
-| `timezone` | `String` | Device timezone |
-| `tags` | `List<AgentRegistrationTagInput>` | Tags to create and assign at registration |
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `hostname` | `String` | ✅ | Unique device hostname |
+| `organizationId` | `String` | ✅ | Owning organization |
+| `agentVersion` | `String` | ✅ | Version of the installed agent |
+| `osType` | `String` | ✅ | Operating system type identifier |
+| `ip` | `String` | ❌ | Device IP address |
+| `macAddress` | `String` | ❌ | Network MAC address |
+| `osUuid` | `String` | ❌ | OS-level unique identifier |
+| `status` | `DeviceStatus` | ❌ | Initial device status enum |
+| `type` | `DeviceType` | ❌ | Device type classification enum |
+| `tags` | `List<AgentRegistrationTagInput>` | ❌ | Tags to create and assign at registration |
 
 ## Usage Example
 
 ```java
 AgentRegistrationRequest request = new AgentRegistrationRequest();
 
-// Core identification
+// Required fields
 request.setHostname("workstation-01");
 request.setOrganizationId("org_abc123");
+request.setAgentVersion("2.4.1");
+request.setOsType("WINDOWS");
 
-// Network
-request.setIp("192.168.1.100");
+// Optional hardware/network fields
+request.setIp("192.168.1.42");
 request.setMacAddress("AA:BB:CC:DD:EE:FF");
-request.setAgentVersion("2.4.1"); // @NotBlank — required
-
-// Hardware
 request.setManufacturer("Dell");
-request.setModel("Latitude 5520");
-request.setSerialNumber("SN-987654");
-
-// OS
-request.setType(DeviceType.WORKSTATION);
-request.setOsType("Windows");
+request.setModel("OptiPlex 7090");
+request.setSerialNumber("SN123456");
 request.setOsVersion("11");
 request.setOsBuild("22H2");
 request.setTimezone("America/New_York");
+request.setStatus(DeviceStatus.ONLINE);
+request.setType(DeviceType.WORKSTATION);
 
-// Tags (validated with @Valid)
+// Optional tags
 AgentRegistrationTagInput tag = new AgentRegistrationTagInput();
-tag.setName("managed");
+tag.setName("office-nyc");
 request.setTags(List.of(tag));
 ```
 
-## Validation Notes
-
-- `agentVersion` is the only `@NotBlank` enforced field — registration will be rejected if omitted.
-- `tags` list is validated recursively via `@Valid`, delegating constraint checks to `AgentRegistrationTagInput`.
\ No newline at end of file
+> Validation is enforced via Jakarta Bean Validation — `@NotBlank` guards required string fields, and `@Valid` cascades validation into each `AgentRegistrationTagInput` entry in the `tags` list.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/exception/.InvalidClientSecretException.md b/openframe-client-core/src/main/java/com/openframe/client/exception/.InvalidClientSecretException.md
new file mode 100644
index 000000000..915075e01
--- /dev/null
+++ b/openframe-client-core/src/main/java/com/openframe/client/exception/.InvalidClientSecretException.md
@@ -0,0 +1,18 @@
+<!-- source-hash: 7f8194b862e347bb4fb8e95799fa0c8b -->
+Signals that a client has provided an invalid or unrecognized secret during authentication, extending `UnauthorizedException` to indicate an HTTP 401-level access denial.
+
+## Key Components
+
+- **`InvalidClientSecretException`** — Concrete exception class extending `UnauthorizedException`, used specifically when client secret validation fails.
+- **Constructor** — Accepts an `ErrorCode` (for machine-readable error classification) and a `String message` (for human-readable detail), delegating both to the parent via `super()`.
+
+## Usage Example
+
+```java
+if (!secretEncoder.matches(providedSecret, storedSecret)) {
+    throw new InvalidClientSecretException(
+        ErrorCode.INVALID_CLIENT_SECRET,
+        "The client secret provided does not match our records."
+    );
+}
+```
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/listener/.MachineHeartbeatListener.md b/openframe-client-core/src/main/java/com/openframe/client/listener/.MachineHeartbeatListener.md
index 35c1b778c..c279018fa 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/listener/.MachineHeartbeatListener.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/listener/.MachineHeartbeatListener.md
@@ -1,36 +1,29 @@
-<!-- source-hash: 4afc6138f1826af0eab39e1836a28616 -->
-A Spring component that listens for machine heartbeat messages via NATS messaging system and processes them to track machine status.
+<!-- source-hash: 4a4a62673275e6e4f92b290f0cb5e580 -->
+NATS message listener that subscribes to machine heartbeat events and delegates processing to `MachineStatusService`. It subscribes on application startup and gracefully drains the dispatcher on shutdown.
 
 ## Key Components
 
-- **`@EventListener(ApplicationReadyEvent.class)`** - Automatically subscribes to heartbeat messages when the application starts
-- **`subscribeToMachineHeartbeats()`** - Sets up NATS dispatcher to listen on `machine.*.heartbeat` subject pattern
-- **`handleMessage(Message)`** - Processes incoming heartbeat messages by extracting machine ID and timestamp
-- **`@PreDestroy cleanup()`** - Gracefully shuts down the NATS dispatcher on application shutdown
-
-## Dependencies
-
-- **`MachineStatusService`** - Processes heartbeat data for machine status tracking
-- **`NatsTopicMachineIdExtractor`** - Extracts machine ID from NATS topic patterns
-- **NATS Connection** - Handles message subscription and delivery
+| Member | Description |
+|--------|-------------|
+| `SUBJECT` | Wildcard topic pattern `machine.*.heartbeat` matching all machine heartbeat messages |
+| `subscribeToMachineHeartbeats()` | Initializes a NATS `Dispatcher` and subscribes on `ApplicationReadyEvent` |
+| `handleMessage(Message)` | Callback invoked per message; extracts machine ID, stamps the event time, and calls `machineStatusService.processHeartbeat()` |
+| `cleanup()` | `@PreDestroy` hook that drains the dispatcher with a 5-second timeout for graceful shutdown |
 
 ## Usage Example
 
+The listener is auto-registered as a Spring `@Component`. No manual wiring is needed — it activates when the application context is fully started.
+
 ```java
-// The listener automatically starts when the Spring application is ready
-// It subscribes to subjects like:
-// - machine.001.heartbeat
-// - machine.production-line-A.heartbeat
-// - machine.sensor-xyz.heartbeat
-
-// When a heartbeat message arrives, it:
-// 1. Extracts machine ID from the subject
-// 2. Generates current timestamp
-// 3. Calls machineStatusService.processHeartbeat(machineId, timestamp)
-
-// Configuration in application.yml:
-// nats:
-//   url: nats://localhost:4222
+// Triggered automatically on ApplicationReadyEvent.
+// To simulate the flow in a test:
+Message mockMessage = Mockito.mock(Message.class);
+when(mockMessage.getSubject()).thenReturn("machine.abc-123.heartbeat");
+
+machineHeartbeatListener.handleMessage(mockMessage);
+
+// MachineStatusService.processHeartbeat("abc-123", <now>) is called internally
+verify(machineStatusService).processHeartbeat(eq("abc-123"), any(Instant.class));
 ```
 
-The component uses Spring's lifecycle management to ensure clean startup and shutdown, with proper error handling and logging throughout the message processing pipeline.
\ No newline at end of file
+> The `Dispatcher` is thread-managed by the NATS client internally. `handleMessage` runs on a NATS-owned thread, so `MachineStatusService` implementations must be thread-safe.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/listener/.ToolConnectionListener.md b/openframe-client-core/src/main/java/com/openframe/client/listener/.ToolConnectionListener.md
index 953be7312..c66e46dc2 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/listener/.ToolConnectionListener.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/listener/.ToolConnectionListener.md
@@ -1,42 +1,39 @@
-<!-- source-hash: 15022f1e3c8f1a8980340af5aa347bb0 -->
-A Spring component that listens for tool connection events on a NATS JetStream subject, managing durable consumer lifecycle and delegating processing to `ToolConnectionService`.
+<!-- source-hash: 424f1a009dc3c1a6ec9dba589ec45553 -->
+A Spring component that subscribes to a NATS JetStream subject to process tool connection events for OpenFrame machines, handling consumer lifecycle management including creation, update, and graceful shutdown.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `STREAM_NAME` | Constant | Target JetStream stream (`TOOL_CONNECTIONS`) |
-| `SUBJECT` | Constant | Wildcard subject pattern (`machine.*.tool-connection`) |
-| `CONSUMER_NAME` | Constant | Durable consumer identifier (`tool-connection-processor-v2`) |
-| `MAX_DELIVER` | Constant | Maximum redelivery attempts before message is dead-lettered (50) |
-| `ACK_WAIT` | Constant | Acknowledgement timeout window (30 seconds) |
+| `STREAM_NAME` | Constant | JetStream stream identifier: `TOOL_CONNECTIONS` |
+| `SUBJECT` | Constant | Wildcard subject pattern: `machine.*.tool-connection` |
+| `CONSUMER_NAME` | Constant | Durable consumer name: `tool-connection-processor-v2` |
+| `MAX_DELIVER` | Constant | Maximum redelivery attempts before abandoning (`50`) |
+| `ACK_WAIT` | Constant | Acknowledgement timeout (`30s`) |
 | `subscribeToToolConnections()` | Method | Bootstraps JetStream push subscription on `ApplicationReadyEvent` |
-| `buildConsumerConfig()` | Method | Creates or updates the durable consumer with delivery group support |
-| `handleMessage()` | Method | Deserializes and routes each `ToolConnectionMessage` |
-| `cleanup()` | Method | Gracefully unsubscribes and drains the dispatcher on shutdown |
+| `buildConsumerConfig()` | Method | Creates or updates a durable consumer with explicit ack and delivery group |
+| `handleMessage()` | Method | Deserializes and dispatches each `ToolConnectionMessage` to `ToolConnectionService` |
+| `isLastAttempt()` | Method | Checks if current delivery equals `MAX_DELIVER` to signal final processing attempt |
+| `cleanup()` | Method | Gracefully unsubscribes and drains the dispatcher on application shutdown (`@PreDestroy`) |
 
 ## Usage Example
 
 ```java
-// Bean is auto-configured by Spring on startup.
-// Subscription is triggered automatically via ApplicationReadyEvent.
+// Bean is auto-registered via @Component and triggers on startup
+// No manual instantiation needed. Internally it behaves as follows:
 
-// Internally, messages are published to the subject pattern:
-// machine.<machineId>.tool-connection
+// 1. On ApplicationReadyEvent, subscription is established:
+// Subject   : machine.*.tool-connection
+// Consumer  : tool-connection-processor-v2 (durable, explicit ack)
+// Group     : tool-connection (load-balanced delivery group)
 
-// Example payload consumed by this listener:
-{
-  "toolType": "antivirus",
-  "agentToolId": "tool-abc-123"
-}
+// 2. Each received message is handled:
+ToolConnectionMessage msg = objectMapper.readValue(payload, ToolConnectionMessage.class);
+toolConnectionService.addToolConnection(machineId, msg.getToolType(), msg.getAgentToolId(), lastAttempt);
+message.ack();
 
-// On success: message.ack() is called.
-// On failure: message is left unacked for redelivery (up to MAX_DELIVER=50 attempts).
-// On last attempt: lastAttempt=true is passed to ToolConnectionService.
+// 3. On failure, the message is left unacked for redelivery up to MAX_DELIVER (50) times
+// 4. On shutdown, the subscription is cleanly drained over a 5-second window
 ```
 
-## Notes
-
-- The `v2` consumer suffix was introduced during a hotfix to support delivery groups, which cannot be applied to existing consumers retroactively.
-- Uses explicit ACK policy — failed processing never silently discards messages.
-- `@PreDestroy` ensures clean drain of in-flight messages during shutdown with a 5-second grace period.
\ No newline at end of file
+> **Note:** The `-v2` consumer name suffix was introduced during a hotfix to enable delivery group support, as existing consumers without a delivery group cannot be migrated in-place. The previous consumer (`tool-connection-processor`) is deprecated.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/service/.MachineStatusService.md b/openframe-client-core/src/main/java/com/openframe/client/service/.MachineStatusService.md
index 5ddc7d454..b8686162f 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/service/.MachineStatusService.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/service/.MachineStatusService.md
@@ -1,23 +1,17 @@
-<!-- source-hash: be4916a9f09334f62c5fe1b7cc1532a2 -->
-Manages machine (device) connectivity status transitions within the OpenFrame platform, handling online/offline updates, heartbeat processing, and first-connection event detection with stale-event protection.
+<!-- source-hash: 48c63db3ad547755882eb13d76118f5c -->
+Manages machine connectivity status transitions by processing online/offline events and heartbeats, with stale event protection and first-connection detection.
 
 ## Key Components
 
-| Method | Description |
-|--------|-------------|
-| `updateToOnline()` | Marks a machine as `ONLINE` for a given timestamp |
-| `updateToOffline()` | Marks a machine as `OFFLINE` for a given timestamp |
-| `processHeartbeat()` | Treats an incoming heartbeat as an `ONLINE` status update |
-| `update()` *(private)* | Core logic: loads the machine, validates event freshness, applies status change |
-| `isEventNewer()` *(private)* | Guards against out-of-order events by comparing timestamps |
-| `applyStatusUpdate()` *(private)* | Persists the new status and fires `DeviceFirstConnectedEvent` on `PENDING → ONLINE/OFFLINE` transition |
-| `logStaleEvent()` *(private)* | Warns when an older event arrives after a newer one has already been applied |
-
-## Behavior Notes
-
-- **Stale-event protection** — events with a timestamp older than `machine.lastSeen` are silently dropped with a warning log.
-- **First-connection detection** — when a device transitions out of `PENDING` status for the first time, a `DeviceFirstConnectedEvent` is published via Spring's `ApplicationEventPublisher`.
-- Throws `MachineNotFoundException` if the `machineId` does not exist in the repository.
+| Member | Type | Description |
+|--------|------|-------------|
+| `updateToOnline` | `public void` | Marks a machine as `ONLINE` for a given timestamp |
+| `updateToOffline` | `public void` | Marks a machine as `OFFLINE` for a given timestamp |
+| `processHeartbeat` | `public void` | Treats a heartbeat as an `ONLINE` status update |
+| `update` | `private void` | Core logic: resolves the machine, guards against stale events, delegates to `applyStatusUpdate` |
+| `isEventNewer` | `private boolean` | Returns `true` if `eventTimestamp` is after `lastSeen` (or `lastSeen` is null) |
+| `applyStatusUpdate` | `private void` | Persists the new status/timestamp and publishes `DeviceFirstConnectedEvent` on `PENDING → ONLINE/OFFLINE` transition |
+| `logStaleEvent` | `private void` | Emits a `WARN` log when an out-of-order event is discarded |
 
 ## Usage Example
 
@@ -26,12 +20,18 @@ Manages machine (device) connectivity status transitions within the OpenFrame pl
 @Autowired
 private MachineStatusService machineStatusService;
 
-// Device comes online
-machineStatusService.updateToOnline("machine-abc-123", Instant.now());
+// Agent comes online
+machineStatusService.updateToOnline("machine-abc123", Instant.now());
+
+// Agent sends a heartbeat
+machineStatusService.processHeartbeat("machine-abc123", Instant.now());
+
+// Agent goes offline
+machineStatusService.updateToOffline("machine-abc123", Instant.now());
+```
 
-// Device goes offline
-machineStatusService.updateToOffline("machine-abc-123", Instant.now());
+## Notes
 
-// Heartbeat received from agent
-machineStatusService.processHeartbeat("machine-abc-123", Instant.now());
-```
\ No newline at end of file
+- Throws `MachineNotFoundException` if the `machineId` is not found in `MachineRepository`.
+- Stale events (timestamp ≤ `lastSeen`) are silently discarded with a `WARN` log — no exception is raised.
+- The `DeviceFirstConnectedEvent` fires **once** per machine lifecycle, on the first `PENDING → ONLINE/OFFLINE` transition, enabling downstream provisioning or notification workflows.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationService.md b/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationService.md
index 9a9a43fe5..bd08f1bd0 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationService.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationService.md
@@ -1,35 +1,38 @@
-<!-- source-hash: e22c788970280667773d9404e3bcd9cf -->
-Handles the end-to-end registration of OpenFrame agents, orchestrating OAuth client creation, machine persistence, tag assignment, tool installation, and post-processing within a single transaction.
+<!-- source-hash: 76e0968ec76847d4bc59762cab0ebd98 -->
+Handles agent registration and reinstallation for OpenFrame client machines, managing OAuth client creation, machine record persistence, and post-registration processing workflows.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `register()` | Method | Entry point — validates the initial key, generates credentials, resolves the org, persists all entities, and returns the agent credentials |
-| `saveOAuthClient()` | Method | Creates and persists an `OAuthClient` with hashed secret and `AGENT` role using client-credentials grant |
-| `saveMachine()` | Method | Builds and persists a `Machine` document with `PENDING` status and `DESKTOP` type |
-| `resolveOrganizationId()` | Method | Uses the requested org ID if it exists, otherwise falls back to the tenant's default organization |
-| `saveInstalledAgent()` | Method | Optionally records the agent version via `InstalledAgentService` (feature-flagged by `openframe.feature.save-installed-agent-on-registration`) |
-| `AGENT_ROLE` | Constant | Role assigned to all registered agent OAuth clients (`"AGENT"`) |
-| `CLIENT_ID_TEMPLATE` | Constant | Pattern for client IDs: `agent_{machineId}` |
+| `register()` | Method | Registers a new agent: validates the initial key, generates IDs/secrets, creates OAuth client and machine records, then triggers post-processing |
+| `reinstall()` | Method | Reinstalls an existing agent: validates credentials, updates the existing machine record, and reruns post-processing without generating new credentials |
+| `createOAuthClient()` | Private Method | Persists a new `OAuthClient` with encoded secret, `client_credentials` grant type, and `AGENT` role |
+| `createMachine()` | Private Method | Persists a new `Machine` document with `PENDING` status and resolved organization ID |
+| `postProcessMachine()` | Private Method | Orchestrates post-registration steps: saves installed agent info, assigns tags, triggers tool installation, and runs the registration processor |
+| `updateMachine()` | Private Method | Overwrites machine fields and re-resolves the organization ID during reinstall |
 
 ## Usage Example
 
 ```java
-// Called from a registration endpoint, typically with a pre-shared initial key
+// New agent registration
 AgentRegistrationRequest request = new AgentRegistrationRequest();
 request.setHostname("workstation-01");
-request.setIp("192.168.1.50");
 request.setOsType("WINDOWS");
-request.setAgentVersion("1.4.2");
-request.setOrganizationId("org-abc123"); // optional; falls back to default org
+request.setAgentVersion("2.1.0");
+request.setOrganizationId("org-abc");
+request.setTags(List.of("office", "finance"));
 
-AgentRegistrationResponse response = agentRegistrationService.register(initialKey, request);
+AgentRegistrationResponse response = agentRegistrationService.register("initial-secret-key", request);
+// response contains: machineId, clientId (e.g. "agent_<uuid>"), clientSecret
 
-// Response contains credentials the agent uses for subsequent API calls
-String machineId    = response.getMachineId();
-String clientId     = response.getClientId();   // e.g. "agent_<uuid>"
-String clientSecret = response.getClientSecret();
+// Agent reinstall (retains existing credentials)
+AgentRegistrationResponse reinstallResponse = agentRegistrationService.reinstall(
+    "initial-secret-key",
+    response.getMachineId(),
+    response.getClientSecret(),
+    request
+);
 ```
 
-> **Note:** The entire `register()` flow runs inside a `@Transactional` boundary. A TODO marks a pending two-phase commit strategy for the NATS integration to handle distributed consistency.
\ No newline at end of file
+> **Note:** The `register` flow enforces uniqueness of generated machine IDs. If a collision is detected, an `IllegalStateException` is thrown before persisting. The `reinstall` flow throws `InvalidClientSecretException` if the provided `machineId`/`clientSecret` pair cannot be validated against an existing `OAuthClient`.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationToolInstallationService.md b/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationToolInstallationService.md
index 0a4107be7..534bf303a 100644
--- a/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationToolInstallationService.md
+++ b/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.AgentRegistrationToolInstallationService.md
@@ -1,34 +1,22 @@
-<!-- source-hash: f536d5b7df2919d40383afa7f31f83de -->
-A service that coordinates tool agent installation during the agent registration process by retrieving all enabled tool agents and installing them on a specified machine.
+<!-- source-hash: 6a526fd27b986902954d0b9bec0f398a -->
+Handles asynchronous tool installation for newly registered agents by retrieving all enabled tool agents and triggering their installation on a specified machine.
 
 ## Key Components
 
-- **process(String machineId)** - Main orchestration method that retrieves all enabled tool agents and triggers installation for each one
-- **integratedToolAgentService** - Service dependency for managing integrated tool agent data
-- **toolInstallationService** - Service dependency that handles the actual tool installation process
+- **`process(String machineId)`** — Async method (runs on `TOOL_INSTALL_EXECUTOR` thread pool) that fetches all enabled `IntegratedToolAgent` records and dispatches installation for each on the target machine.
 
 ## Usage Example
 
 ```java
-@Autowired
-private AgentRegistrationToolInstallationService installationService;
-
-// Install all enabled tools on a newly registered machine
-public void registerNewAgent(String machineId) {
-    // ... other registration logic
-    
-    // Install all available tools
-    installationService.process(machineId);
-    
-    log.info("Tool installation completed for machine: {}", machineId);
-}
-
-// Example in a registration controller
-@PostMapping("/register")
-public ResponseEntity<String> registerAgent(@RequestParam String machineId) {
-    installationService.process(machineId);
-    return ResponseEntity.ok("Agent registered with tools installed");
-}
+// Triggered during agent registration flow
+agentRegistrationToolInstallationService.process("machine-abc-123");
+// Runs asynchronously on TOOL_INSTALL_EXECUTOR; returns immediately
 ```
 
-The service follows a simple orchestration pattern where it retrieves all enabled tool agents from the data layer and delegates the actual installation work to the `ToolInstallationService` for each tool-machine combination.
\ No newline at end of file
+## Dependencies
+
+| Dependency | Role |
+|---|---|
+| `IntegratedToolAgentService` | Retrieves all enabled tool agent configurations |
+| `ToolInstallationService` | Executes the per-agent installation logic on the target machine |
+| `AsyncConfig.TOOL_INSTALL_EXECUTOR` | Dedicated thread pool for non-blocking tool installs |
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.OrganizationIdResolver.md b/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.OrganizationIdResolver.md
new file mode 100644
index 000000000..edfce4b31
--- /dev/null
+++ b/openframe-client-core/src/main/java/com/openframe/client/service/agentregistration/.OrganizationIdResolver.md
@@ -0,0 +1,29 @@
+<!-- source-hash: 0cba15f07acdd895d72b781dfabc9700 -->
+Resolves an organization ID during agent registration by validating a requested ID against the data store, falling back to the default organization if the requested ID is absent or not found.
+
+## Key Components
+
+- **`resolve(String requestedOrganizationId)`** — Primary entry point. Returns the requested organization ID if it exists, otherwise logs a warning and falls back to the default organization ID.
+- **`existsRequested(String)`** — Private helper that checks the ID is non-blank and exists via `OrganizationService`.
+- **`getDefaultOrganizationId()`** — Private helper that fetches the default organization; throws `IllegalStateException` if none is configured.
+
+## Usage Example
+
+```java
+@Component
+@RequiredArgsConstructor
+public class AgentRegistrationService {
+
+    private final OrganizationIdResolver organizationIdResolver;
+
+    public void registerAgent(AgentRegistrationRequest request) {
+        // Resolves to provided ID if valid, otherwise falls back to default
+        String organizationId = organizationIdResolver.resolve(request.getOrganizationId());
+
+        // Proceed with registration using the resolved organization ID
+        ...
+    }
+}
+```
+
+> **Note:** If no default organization exists (e.g., tenant setup was incomplete), `resolve()` will throw an `IllegalStateException`. Ensure the default organization is created during tenant registration to avoid this failure path.
\ No newline at end of file
diff --git a/openframe-client-core/src/main/java/com/openframe/client/service/validator/.ClientSecretValidator.md b/openframe-client-core/src/main/java/com/openframe/client/service/validator/.ClientSecretValidator.md
new file mode 100644
index 000000000..03056a4c2
--- /dev/null
+++ b/openframe-client-core/src/main/java/com/openframe/client/service/validator/.ClientSecretValidator.md
@@ -0,0 +1,35 @@
+<!-- source-hash: 75092166fe74a795a931290a2e43f4ea -->
+Validates the client secret provided during OAuth authentication against the stored encoded secret for an `OAuthClient`.
+
+## Key Components
+
+| Element | Description |
+|---|---|
+| `ClientSecretValidator` | Spring `@Component` responsible for client secret validation |
+| `validate(OAuthClient, String)` | Checks secret is non-empty, then verifies it against the BCrypt-encoded stored value |
+| `PasswordEncoder` | Injected Spring Security encoder used for secure hash comparison |
+| `InvalidClientSecretException` | Thrown with specific `ErrorCode` on empty (`CLIENT_SECRET_EMPTY`) or mismatched (`CLIENT_SECRET_INVALID`) secrets |
+
+## Usage Example
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OAuthTokenService {
+
+    private final ClientSecretValidator clientSecretValidator;
+    private final OAuthClientRepository clientRepository;
+
+    public TokenResponse issueToken(TokenRequest request) {
+        OAuthClient client = clientRepository.findByClientId(request.getClientId())
+            .orElseThrow(() -> new ClientNotFoundException(...));
+
+        // Throws InvalidClientSecretException if empty or invalid
+        clientSecretValidator.validate(client, request.getClientSecret());
+
+        return generateToken(client);
+    }
+}
+```
+
+> **Note:** The raw secret is never stored — comparison is delegated entirely to `PasswordEncoder.matches()`, ensuring the plain-text secret is only transiently held in memory during the request lifecycle.
\ No newline at end of file
diff --git a/openframe-client-core/src/test/java/com/openframe/client/controller/.AgentControllerTest.md b/openframe-client-core/src/test/java/com/openframe/client/controller/.AgentControllerTest.md
index 13e32af0b..7ca9bab01 100644
--- a/openframe-client-core/src/test/java/com/openframe/client/controller/.AgentControllerTest.md
+++ b/openframe-client-core/src/test/java/com/openframe/client/controller/.AgentControllerTest.md
@@ -1,47 +1,49 @@
-<!-- source-hash: 6ac89581f77f6f7bb4928c55e4fe9ee1 -->
-Unit test suite for the `AgentController`, validating HTTP behavior of the `/api/agents/register` endpoint using MockMvc with mocked service dependencies.
+<!-- source-hash: bde2f27969b3a1d8322b0e1ca68d5575 -->
+Unit tests for `AgentController`, verifying HTTP request/response behavior for agent registration and reinstallation endpoints using MockMvc and Mockito.
 
 ## Key Components
 
 | Component | Description |
 |-----------|-------------|
-| `AgentController` | Controller under test, wired with a mocked `AgentRegistrationService` |
-| `AgentRegistrationService` | Mocked service handling agent registration logic |
-| `AgentRegistrationRequest` | DTO with hostname, IP, MAC address, OS UUID, and agent version |
-| `AgentRegistrationResponse` | DTO returning `machineId`, `clientId`, and `clientSecret` |
-| `BaseGlobalExceptionHandler` | Applied via `setControllerAdvice` to validate error response shapes |
-| `TestAuthenticationManager` | Stub authentication manager injected via `BasicAuthenticationFilter` |
-
-## Test Coverage
-
-| Test | Expected Outcome |
-|------|-----------------|
-| `register_WithValidRequest_ReturnsOk` | `200 OK` with full credential payload |
-| `register_MissingHeader_ReturnsBadRequest` | `400 BAD_REQUEST` when `X-Initial-Key` is absent |
-| `register_WithoutInitialKey_ReturnsBadRequest` | `400 BAD_REQUEST` (duplicate missing-header scenario) |
-| `register_WithInvalidInitialKey_ReturnsUnauthorized` | `401 UNAUTHORIZED` on secret validation failure |
-| `register_WithDuplicateMachineId_ReturnsConflict` | `409 CONFLICT` when machine is already registered |
-| `register_WithValidRequest_ReturnsCredentials` | `200 OK` with `clientId` and `clientSecret` |
-| `register_WithValidRequest_StoresAgentInfo` | Verifies service receives all request fields correctly |
+| `AgentController` | Controller under test, wrapping `AgentRegistrationService` |
+| `AgentRegistrationService` | Mocked service handling registration/reinstall logic |
+| `AgentRegistrationRequest` | Request DTO with fields: `hostname`, `ip`, `macAddress`, `osUuid`, `osType`, `agentVersion` |
+| `AgentRegistrationResponse` | Response DTO returning `machineId`, `clientId`, `clientSecret` |
+| `TestAuthenticationManager` | Test utility simulating Basic Auth filter |
+| `BaseGlobalExceptionHandler` | Shared exception handler mapping domain exceptions to HTTP status codes |
+
+## Covered Test Cases
+
+**`POST /api/agents/register`**
+- Valid request → `200 OK` with credentials
+- Missing `X-Initial-Key` header → `400 Bad Request`
+- Invalid initial key → `401 Unauthorized`
+- Duplicate machine → `409 Conflict`
+- Missing mandatory `hostname` field → `400 VALIDATION_ERROR`
+- Verifies service receives correct request payload
+
+**`POST /api/agents/reinstall`**
+- Valid headers + body → `200 OK`
+- Missing `X-Initial-Key` → `400 Bad Request`
+- Missing `X-Machine-Id` → `400 Bad Request`
+- Missing `X-Client-Secret` → `400 Bad Request`
+- Invalid client secret → *(truncated in source)*
 
 ## Usage Example
 
 ```java
-// Example: how the service mock is configured and verified
-when(agentRegistrationService.register(eq("test-key"), any(AgentRegistrationRequest.class)))
-    .thenReturn(registrationResponse);
-
+// Example: how the controller under test is exercised
 mockMvc.perform(post("/api/agents/register")
         .header("X-Initial-Key", "test-key")
         .contentType(MediaType.APPLICATION_JSON)
         .content(objectMapper.writeValueAsString(registrationRequest)))
     .andExpect(status().isOk())
-    .andExpect(jsonPath("$.machineId").value("test-machine-id"));
+    .andExpect(jsonPath("$.machineId").value("test-machine-id"))
+    .andExpect(jsonPath("$.clientSecret").value("client-secret"));
 
-// Verify all fields are passed through to the service
+// Verify the service received the correct payload
 verify(agentRegistrationService).register(
     eq("test-key"),
-    argThat(req -> req.getHostname().equals("test-host") &&
-                  req.getMacAddress().equals("00:11:22:33:44:55"))
+    argThat(req -> req.getHostname().equals("test-host"))
 );
 ```
\ No newline at end of file
diff --git a/openframe-client-core/src/test/java/com/openframe/client/service/.AgentRegistrationServiceTest.md b/openframe-client-core/src/test/java/com/openframe/client/service/.AgentRegistrationServiceTest.md
index 71c0c8f8e..c8518d1cb 100644
--- a/openframe-client-core/src/test/java/com/openframe/client/service/.AgentRegistrationServiceTest.md
+++ b/openframe-client-core/src/test/java/com/openframe/client/service/.AgentRegistrationServiceTest.md
@@ -1,40 +1,36 @@
-<!-- source-hash: 4b6bf8d38be103ab50b25b672d22dd09 -->
-Unit test suite for `AgentRegistrationService`, validating agent registration flows including new machine creation, duplicate detection, and tag assignment.
+<!-- source-hash: d62a27bbe6c20d7ff553765ae609819b -->
+Unit test suite for `AgentRegistrationService`, validating agent registration and reinstallation workflows including credential generation, machine persistence, tag assignment, and secret validation ordering.
 
 ## Key Components
 
 | Test Method | Purpose |
 |---|---|
-| `registerAgent_WithNewMachine_ReturnsCredentials` | Verifies full registration lifecycle: credential generation, OAuth client persistence, and machine document creation |
-| `registerAgent_WithExistingMachine_ThrowsException` | Ensures duplicate machine detection throws `IllegalStateException` and prevents any saves |
-| `registerAgent_WithTags_AssignsTagsToDevice` | Confirms tag assignment is delegated to `RegistrationTagAssignmentService` when tags are present |
-| `registerAgent_WithoutTags_DoesNotAssignTags` | Confirms `assignTags` is still called with a `null` tag list when no tags are provided |
-
-**Mocked dependencies:** `OAuthClientRepository`, `MachineRepository`, `OrganizationService`, `AgentRegistrationSecretValidator`, `AgentSecretGenerator`, `MachineIdGenerator`, `PasswordEncoder`, `RegistrationTagAssignmentService`, `InstalledAgentService`, `AgentRegistrationToolInstallationService`, `AgentRegistrationProcessor`
+| `registerAgent_WithNewMachine_ReturnsCredentials` | Verifies full registration flow: ID generation, OAuth client creation, machine persistence, and credential response |
+| `registerAgent_WithExistingMachine_ThrowsException` | Ensures duplicate machine IDs throw `IllegalStateException` and prevent any saves |
+| `registerAgent_WithTags_AssignsTagsToDevice` | Confirms tag assignment is invoked with correct tag inputs when tags are present |
+| `registerAgent_WithoutTags_DoesNotAssignTags` | Confirms `assignTags` is still called with `null` when no tags are provided |
+| `reinstall_WithValidKeyAndSecret_OverwritesMachineAndReturnsExistingCreds` | Validates reinstall path: reuses existing OAuth credentials, overwrites machine data, resets status to `PENDING`, and enforces validation ordering |
 
 ## Usage Example
 
 ```java
-// Simulate a new agent registration with tags
-AgentRegistrationRequest request = new AgentRegistrationRequest();
-request.setHostname("workstation-01");
-request.setIp("10.0.0.5");
-request.setMacAddress("AA:BB:CC:DD:EE:FF");
-request.setOsUuid("os-uuid-xyz");
-request.setAgentVersion("2.1.0");
-request.setTags(List.of(
-    AgentRegistrationTagInput.builder()
-        .key("site")
-        .values(List.of("NEW_YORK"))
-        .build()
-));
-
-// Expected: response contains machineId, clientId ("agent_<machineId>"), and clientSecret
-AgentRegistrationResponse response = agentRegistrationService.register("initial-key", request);
+// Typical mock setup pattern used across tests
+when(machineIdGenerator.generate()).thenReturn(MACHINE_ID);
+when(oauthClientRepository.existsByMachineId(MACHINE_ID)).thenReturn(false);
+when(agentSecretGenerator.generate()).thenReturn(CLIENT_SECRET);
+when(passwordEncoder.encode(CLIENT_SECRET)).thenReturn("encoded-secret");
+when(oauthClientRepository.save(any())).thenAnswer(i -> i.getArguments()[0]);
+
+AgentRegistrationResponse response = agentRegistrationService.register(INITIAL_KEY, request);
+
+// Assert credentials returned correctly
+assertEquals(MACHINE_ID, response.getMachineId());
+assertEquals("agent_" + MACHINE_ID, response.getClientId());
+
+// Assert validation ordering on reinstall (initial key before client secret)
+InOrder inOrder = inOrder(agentRegistrationSecretValidator, clientSecretValidator);
+inOrder.verify(agentRegistrationSecretValidator).validate(INITIAL_KEY);
+inOrder.verify(clientSecretValidator).validate(existingClient, CLIENT_SECRET);
 ```
 
-**Key assertions validated across tests:**
-- `clientId` is always prefixed as `agent_<machineId>`
-- Saved `OAuthClient` uses `client_credentials` grant type and `AGENT` role
-- Saved `Machine` defaults to `DeviceStatus.PENDING` with a non-null `lastSeen` timestamp
-- Secret validator is always invoked before any persistence
\ No newline at end of file
+**Notable patterns:** Uses `ArgumentCaptor` to assert saved entity field values directly, `InOrder` to enforce validation sequence, and `never()` to assert no re-creation of IDs or OAuth clients during reinstall.
\ No newline at end of file
diff --git a/openframe-client-core/src/test/java/com/openframe/client/service/agentregistration/.OrganizationIdResolverTest.md b/openframe-client-core/src/test/java/com/openframe/client/service/agentregistration/.OrganizationIdResolverTest.md
new file mode 100644
index 000000000..d1c9ddea8
--- /dev/null
+++ b/openframe-client-core/src/test/java/com/openframe/client/service/agentregistration/.OrganizationIdResolverTest.md
@@ -0,0 +1,45 @@
+<!-- source-hash: f2d953e9e25c0fb74642e5e5b3a64b6a -->
+Unit tests for `OrganizationIdResolver`, verifying organization ID resolution logic including fallback-to-default and error handling behaviors.
+
+## Key Components
+
+| Element | Description |
+|---------|-------------|
+| `resolve_WithExistingRequestedOrg_ReturnsIt` | Confirms a valid, known org ID is returned directly without querying the default |
+| `resolve_WithUnknownRequestedOrg_FallsBackToDefault` | Ensures an unrecognized org ID falls back to the default organization |
+| `resolve_WithBlank_ReturnsDefaultWithoutLookup` | Validates that blank/whitespace input skips the org lookup and returns the default |
+| `resolve_WhenNoDefaultOrganization_Throws` | Asserts an `IllegalStateException` is thrown when no default organization exists |
+| `organization()` | Helper method that constructs a minimal `Organization` document for test fixtures |
+
+## Usage Example
+
+```java
+// Scenario: requested org exists → returned directly
+when(organizationService.getOrganizationByOrganizationId("org-1"))
+        .thenReturn(Optional.of(organization("org-1")));
+
+String result = resolver.resolve("org-1"); // → "org-1"
+verify(organizationService, never()).getDefaultOrganization();
+
+// Scenario: blank input → default org returned, no ID lookup performed
+when(organizationService.getDefaultOrganization())
+        .thenReturn(Optional.of(organization("default-uuid")));
+
+String result = resolver.resolve("   "); // → "default-uuid"
+verify(organizationService, never()).getOrganizationByOrganizationId(any());
+
+// Scenario: no default configured → throws
+when(organizationService.getDefaultOrganization()).thenReturn(Optional.empty());
+assertThrows(IllegalStateException.class, () -> resolver.resolve(null));
+```
+
+## Coverage Summary
+
+```text
+Input                  | Org Found? | Default Found? | Outcome
+-----------------------|------------|----------------|-------------------------
+Valid org ID           | ✅ Yes     | Not queried    | Returns requested org ID
+Unknown org ID         | ❌ No      | ✅ Yes         | Returns default org ID
+Blank / whitespace     | Not queried| ✅ Yes         | Returns default org ID
+Null / blank           | Not queried| ❌ No          | Throws IllegalStateException
+```
\ No newline at end of file
diff --git a/openframe-client-core/src/test/java/com/openframe/client/service/validator/.ClientSecretValidatorTest.md b/openframe-client-core/src/test/java/com/openframe/client/service/validator/.ClientSecretValidatorTest.md
new file mode 100644
index 000000000..f6866090d
--- /dev/null
+++ b/openframe-client-core/src/test/java/com/openframe/client/service/validator/.ClientSecretValidatorTest.md
@@ -0,0 +1,43 @@
+<!-- source-hash: c2a11db7e488e2a2bc103c65c4d6d5d3 -->
+Unit tests for `ClientSecretValidator`, verifying secret validation logic including blank input rejection and BCrypt-based secret matching against an `OAuthClient`.
+
+## Key Components
+
+| Component | Role |
+|-----------|------|
+| `ClientSecretValidator` | Class under test — validates raw client secrets against stored encoded values |
+| `PasswordEncoder` | Mocked Spring Security component used to compare raw vs. encoded secrets |
+| `InvalidClientSecretException` | Expected exception carrying an `ErrorCode` on validation failure |
+| `ErrorCode.CLIENT_SECRET_EMPTY` | Error code asserted when the provided secret is blank/whitespace |
+| `ErrorCode.CLIENT_SECRET_INVALID` | Error code asserted when the secret does not match the stored hash |
+
+## Test Cases
+
+| Test | Scenario | Expected Outcome |
+|------|----------|-----------------|
+| `validate_WithMatchingSecret_Passes` | Raw secret matches encoded secret via `PasswordEncoder` | No exception thrown |
+| `validate_WithBlankSecret_ThrowsEmpty` | Secret is blank/whitespace | `InvalidClientSecretException` with `CLIENT_SECRET_EMPTY`; `PasswordEncoder` never invoked |
+| `validate_WithWrongSecret_ThrowsInvalid` | Raw secret does not match encoded secret | `InvalidClientSecretException` with `CLIENT_SECRET_INVALID` |
+
+## Usage Example
+
+```java
+// Arrange
+OAuthClient client = new OAuthClient();
+client.setClientSecret("$2a$10$encodedHash...");
+
+// Blank secret — fast-fail before encoder is called
+assertThrows(InvalidClientSecretException.class,
+    () -> validator.validate(client, "   "));
+
+// Wrong secret — encoder consulted, mismatch detected
+when(passwordEncoder.matches("wrong", "$2a$10$encodedHash...")).thenReturn(false);
+assertThrows(InvalidClientSecretException.class,
+    () -> validator.validate(client, "wrong"));
+
+// Correct secret — passes silently
+when(passwordEncoder.matches("correct", "$2a$10$encodedHash...")).thenReturn(true);
+assertDoesNotThrow(() -> validator.validate(client, "correct"));
+```
+
+> **Note:** Blank secret validation short-circuits before `PasswordEncoder.matches()` is called — verified explicitly with `verify(passwordEncoder, never()).matches(any(), any())` — preventing unnecessary crypto operations on empty input.
\ No newline at end of file
diff --git a/openframe-data-device-aspect/src/main/java/com/openframe/data/service/impl/.MachineTagEventServiceImpl.md b/openframe-data-device-aspect/src/main/java/com/openframe/data/service/impl/.MachineTagEventServiceImpl.md
index 9c3540bb2..813b0ae7f 100644
--- a/openframe-data-device-aspect/src/main/java/com/openframe/data/service/impl/.MachineTagEventServiceImpl.md
+++ b/openframe-data-device-aspect/src/main/java/com/openframe/data/service/impl/.MachineTagEventServiceImpl.md
@@ -1,18 +1,30 @@
-<!-- source-hash: 0d8f8c78614ef4aa3218545c27d17c7f -->
-Handles machine tag lifecycle events by processing save and delete operations for machines, tag assignments, and tags, then publishing enriched `MachinePinotMessage` payloads to a Kafka topic for downstream analytics.
+<!-- source-hash: c0e2f52cd3f9dfe26aa4f026a49b7b89 -->
+Handles machine tag event processing by listening for save/delete events on `Machine`, `Tag`, and `TagAssignment` entities, then publishing enriched `MachinePinotMessage` payloads to a Kafka topic for downstream Pinot ingestion.
 
 ## Key Components
 
 | Method | Description |
-|---|---|
-| `processMachineSave` | Publishes a single machine event to Kafka with its current tag state |
+|--------|-------------|
+| `processMachineSave` | Processes a single machine save event and publishes to Kafka |
 | `processMachineSaveAll` | Iterates and publishes Kafka events for a batch of machines |
-| `processTagAssignmentSave` | Handles a single `DEVICE`-type tag assignment, publishing the updated machine state |
-| `processTagAssignmentSaveAll` | Batch processes tag assignments, deduplicating by `entityId` to avoid redundant messages |
-| `processTagSave` | Propagates a tag update to all machines that carry that tag |
-| `processTagSaveAll` | Batch processes tag updates across all affected machines |
-| `processTagAssignmentDelete` | Rebuilds and publishes a machine's tag state after a specific tag assignment is removed |
-| `processTagAssignmentDeleteByTagId` | Bulk recomputes and publishes updated state for all machines affected by a tag deletion |
+| `processTagAssignmentSave` | Handles a single tag assignment save; skips non-`DEVICE` entity types |
+| `processTagAssignmentSaveAll` | Batch processes tag assignments, deduplicating by `entityId` |
+| `processTagSave` | Propagates a tag update to all machines that carry the tag |
+| `processTagSaveAll` | Batch version of `processTagSave` |
+| `processTagAssignmentDelete` | Rebuilds and publishes a machine message excluding the deleted tag assignment |
+| `processTagAssignmentDeleteByTagId` | Bulk delete handler — finds all affected machines and republishes each |
+
+## Conditional Activation
+
+The service is only registered when the property `openframe.device.aspect.enabled=true` (defaults to `true` if missing):
+
+```java
+@ConditionalOnProperty(
+    name = "openframe.device.aspect.enabled",
+    havingValue = "true",
+    matchIfMissing = true
+)
+```
 
 ## Usage Example
 
@@ -21,15 +33,28 @@ Handles machine tag lifecycle events by processing save and delete operations fo
 @Autowired
 private MachineTagEventService machineTagEventService;
 
-// Publish a machine event after save
-Machine machine = machineRepository.save(newMachine);
+// On machine upsert
 machineTagEventService.processMachineSave(machine);
 
-// Publish updated state after removing a tag from a machine
+// On tag assignment removal
 machineTagEventService.processTagAssignmentDelete(machineId, tagId);
 
-// Propagate tag metadata changes to all machines using that tag
-machineTagEventService.processTagSave(updatedTag);
+// On tag entity deletion (cascades to all assigned machines)
+machineTagEventService.processTagAssignmentDeleteByTagId(tagId);
+```
+
+## Configuration
+
+```yaml
+openframe:
+  device:
+    aspect:
+      enabled: true
+  oss-tenant:
+    kafka:
+      topics:
+        outbound:
+          devices-topic: machines-events
 ```
 
-> **Note:** This service is conditionally enabled via `openframe.device.aspect.enabled=true` (defaults to `true`). It is typically invoked from AOP aspects or repository event listeners rather than called directly.
\ No newline at end of file
+> All public methods are wrapped in try/catch blocks — errors are logged but do not propagate, ensuring Kafka publishing failures do not interrupt the caller's transaction.
\ No newline at end of file
diff --git a/openframe-data-kafka/src/main/java/com/openframe/kafka/producer/.GenericKafkaProducer.md b/openframe-data-kafka/src/main/java/com/openframe/kafka/producer/.GenericKafkaProducer.md
index ae0551fdc..9e26e9f49 100644
--- a/openframe-data-kafka/src/main/java/com/openframe/kafka/producer/.GenericKafkaProducer.md
+++ b/openframe-data-kafka/src/main/java/com/openframe/kafka/producer/.GenericKafkaProducer.md
@@ -1,16 +1,28 @@
-<!-- source-hash: 28dde8bc41eded52ac3422d284e8dabf -->
-Abstract base class for Kafka message producers, providing both async (fire-and-forget) and synchronous (blocking) send operations with structured error classification, logging, and exception handling.
+<!-- source-hash: 18161e2ac8ea3a0a8beec3250b5af48e -->
+Abstract base class providing async and synchronous Kafka message production with structured error classification, payload logging, and exception routing for retryable vs. non-retryable failures.
 
 ## Key Components
 
-| Member | Description |
-|---|---|
-| `sendAsync()` | Non-blocking send that returns a `CompletableFuture`; logs success/failure via `whenComplete` without altering the future's state |
-| `sendAndAwait()` | Blocking send that joins the async future and classifies exceptions into `NonRetryableKafkaException` (fatal) or `TransientKafkaSendException` (retryable) |
-| `handleSendFailure()` | Pattern-matched switch that logs authorization errors, oversized records, timeouts, retriable failures, and generic errors with appropriate log levels |
-| `validateTopic()` | Guards against null/blank topic names, throwing `NonRetryableKafkaException` immediately |
-| `redact()` | Masks message keys in logs, exposing only the first 3 characters to avoid leaking sensitive data |
-| `abbreviate()` | Truncates payload strings to 500 characters in log output |
+| Member | Type | Description |
+|--------|------|-------------|
+| `sendAsync()` | `public` | Fire-and-forget send returning a `CompletableFuture`; logs success/failure via `whenComplete` without altering future state |
+| `sendAndAwait()` | `public` | Blocking send that joins the future and classifies `CompletionException` causes into `NonRetryableKafkaException` or `TransientKafkaSendException` |
+| `validateTopic()` | `private` | Guards against null/blank topic names, throwing `NonRetryableKafkaException` immediately |
+| `handleSendFailure()` | `private` | Pattern-matches exception types (`TopicAuthorizationException`, `RecordTooLargeException`, `TimeoutException`, `RetriableException`) for structured log output |
+| `redact()` | `private static` | Masks message keys in logs — keys ≤ 6 chars become `***`, longer keys show first 3 chars + ellipsis |
+| `abbreviate()` | `private static` | Truncates payload strings to 500 chars for safe log output |
+
+## Error Classification
+
+```text
+CompletionException cause
+├── RecordTooLargeException       → NonRetryableKafkaException (fail fast)
+├── AuthorizationException        → NonRetryableKafkaException (fail fast)
+├── SerializationException        → NonRetryableKafkaException (fail fast)
+├── InvalidTopicException         → NonRetryableKafkaException (fail fast)
+├── UnknownTopicOrPartitionException → TransientKafkaSendException (auto-create pending)
+└── All others                    → TransientKafkaSendException (retryable)
+```
 
 ## Usage Example
 
@@ -25,26 +37,16 @@ public class OrderEventProducer extends GenericKafkaProducer {
     }
 
     // Fire-and-forget
-    public CompletableFuture<SendResult<String, Object>> publishAsync(OrderEvent event) {
-        return sendAsync(TOPIC, event.getOrderId(), event);
+    public void publishAsync(OrderCreatedEvent event) {
+        sendAsync(TOPIC, event.getOrderId(), event);
     }
 
-    // Blocking — suitable for use with @Retryable
+    // Blocking — pair with @Retryable(TransientKafkaSendException.class)
     @Retryable(retryFor = TransientKafkaSendException.class, maxAttempts = 3)
-    public void publishAndAwait(OrderEvent event) {
+    public void publishSync(OrderCreatedEvent event) {
         sendAndAwait(TOPIC, event.getOrderId(), event);
     }
 }
 ```
 
-## Exception Classification
-
-```text
-CompletionException cause
-├── RecordTooLargeException       → NonRetryableKafkaException  (fatal, do not retry)
-├── AuthorizationException        → NonRetryableKafkaException  (fatal, do not retry)
-├── SerializationException        → NonRetryableKafkaException  (fatal, do not retry)
-├── InvalidTopicException         → NonRetryableKafkaException  (fatal, do not retry)
-├── UnknownTopicOrPartitionException → TransientKafkaSendException (topic may be auto-creating)
-└── Everything else               → TransientKafkaSendException  (retryable)
-```
\ No newline at end of file
+> **Note:** `sendAsync()` callbacks are logging-only — never throw inside `whenComplete` as it cannot change the returned future's state. Use `sendAndAwait()` with Spring Retry for controlled retry semantics.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/.TenantScoped.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/.TenantScoped.md
new file mode 100644
index 000000000..f9a631077
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/.TenantScoped.md
@@ -0,0 +1,34 @@
+<!-- source-hash: 62196cc1180a5299018ee6edf33ce96d -->
+Marker interface that enforces tenant isolation on domain objects within the OpenFrame multi-tenant data layer. Any document requiring tenant-scoped access control should implement this interface.
+
+## Key Components
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `getTenantId()` | `String` | Returns the tenant identifier associated with the document |
+| `setTenantId(String)` | `void` | Assigns a tenant identifier to the document |
+
+## Usage Example
+
+```java
+@Document(collection = "devices")
+public class Device implements TenantScoped {
+
+    @Id
+    private String id;
+
+    private String tenantId;
+
+    @Override
+    public String getTenantId() {
+        return tenantId;
+    }
+
+    @Override
+    public void setTenantId(String tenantId) {
+        this.tenantId = tenantId;
+    }
+}
+```
+
+Repositories and query filters can then rely on `TenantScoped` to automatically scope queries to the current tenant context, preventing cross-tenant data leakage across the OpenFrame platform.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/agent/.AgentRegistrationSecret.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/agent/.AgentRegistrationSecret.md
index 72f96fed2..ac98fdcff 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/agent/.AgentRegistrationSecret.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/agent/.AgentRegistrationSecret.md
@@ -1,33 +1,27 @@
-<!-- source-hash: fcf3982c5cb9da5df9e25e5404493d4e -->
-A MongoDB document entity representing a registration secret used to authenticate and register agents within the OpenFrame platform.
+<!-- source-hash: d54b94593c8586372e29fae4cf271369 -->
+MongoDB document entity representing a secret key used for agent registration, scoped to a specific tenant.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | Primary identifier (`@Id`) for the document |
-| `secretKey` | `String` | Unique indexed secret key used for agent registration |
-| `createdAt` | `Instant` | Timestamp recording when the secret was created |
-| `active` | `boolean` | Flag indicating whether the registration secret is currently valid |
-
-- **Collection:** `agent_registration_secrets`
-- **Annotations:** Lombok `@Data` auto-generates getters, setters, `equals`, `hashCode`, and `toString`
+| Element | Description |
+|---|---|
+| `@Document` | Maps to the `agent_registration_secrets` MongoDB collection |
+| `@CompoundIndex` | Unique index on `(tenantId, secretKey)` to prevent duplicate secrets per tenant |
+| `TenantScoped` | Interface ensuring all queries are tenant-isolated |
+| `secretKey` | The registration secret value used to authenticate agent enrollment |
+| `active` | Flag to enable/disable a secret without deletion |
+| `createdAt` | Timestamp (`Instant`) recording when the secret was issued |
 
 ## Usage Example
 
 ```java
-// Creating a new agent registration secret
 AgentRegistrationSecret secret = new AgentRegistrationSecret();
+secret.setTenantId("tenant-abc");
 secret.setSecretKey(UUID.randomUUID().toString());
 secret.setCreatedAt(Instant.now());
 secret.setActive(true);
 
-// Persisting via a Spring Data MongoDB repository
-AgentRegistrationSecret saved = agentRegistrationSecretRepository.save(secret);
-
-// Deactivating an existing secret
-saved.setActive(false);
-agentRegistrationSecretRepository.save(saved);
+agentRegistrationSecretRepository.save(secret);
 ```
 
-> **Note:** The `secretKey` field is enforced as unique at the database index level, preventing duplicate registration secrets across agents in the OpenFrame platform.
\ No newline at end of file
+> Compound uniqueness on `(tenantId, secretKey)` ensures no two active secrets share the same key within a tenant, preventing cross-tenant collisions.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKey.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKey.md
index d1bd1d4a8..da3951eeb 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKey.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKey.md
@@ -1,42 +1,45 @@
-<!-- source-hash: 50b8c5874d01659ca0ce4834709f2ad0 -->
-MongoDB document entity representing an API key stored in the `api_keys` collection, including metadata, permission scopes, and expiry logic.
+<!-- source-hash: c02a5843f276e38f2521a42e03eddb91 -->
+MongoDB document model representing an API key entity within the OpenFrame platform, scoped to a specific tenant and user.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `keyId` | `String` | MongoDB `@Id` — primary identifier for the key |
-| `hashedKey` | `String` | Bcrypt/hashed representation of the raw API key |
-| `name` / `description` | `String` | Human-readable label and description |
-| `userId` | `String` | Indexed owner reference linking the key to a user |
-| `scopes` | `List<String>` | Fine-grained permission scopes *(TODO: enforced)* |
-| `roles` | `List<String>` | Role assignments *(TODO: enforced)* |
+| `keyId` | `String` (`@Id`) | Primary identifier for the API key document |
+| `tenantId` | `String` (`@Indexed`) | Tenant scope reference — implements `TenantScoped` |
+| `hashedKey` | `String` | Stored hash of the raw API key secret |
+| `userId` | `String` (`@Indexed`) | Owning user reference |
+| `scopes` / `roles` | `List<String>` | Permission model (⚠️ TODO — not yet enforced) |
 | `enabled` | `boolean` | Soft-disable flag, defaults to `true` |
-| `createdAt` / `updatedAt` / `expiresAt` | `Instant` | Lifecycle timestamps |
+| `expiresAt` | `Instant` | Optional expiry timestamp |
 | `isExpired()` | `boolean` | Returns `true` if `expiresAt` is set and in the past |
-| `isActive()` | `boolean` | Returns `true` if `enabled && !isExpired()` |
+| `isActive()` | `boolean` | Returns `true` if `enabled == true` AND `!isExpired()` |
 
 ## Usage Example
 
 ```java
-// Build a new API key document
+// Create a new API key document
 ApiKey apiKey = ApiKey.builder()
-    .keyId(UUID.randomUUID().toString())
-    .hashedKey(hashService.hash(rawKey))
+    .tenantId("tenant-001")
+    .userId("user-abc")
     .name("CI Integration Key")
-    .description("Used by the CI pipeline")
-    .userId("user_abc123")
-    .scopes(List.of("read:tickets", "write:tickets"))
-    .roles(List.of("technician"))
+    .description("Used by GitHub Actions pipeline")
+    .hashedKey(hashService.hash(rawKey))
+    .scopes(List.of("read:devices", "write:tickets"))
     .enabled(true)
     .createdAt(Instant.now())
-    .expiresAt(Instant.now().plus(Duration.ofDays(90)))
+    .expiresAt(Instant.now().plus(90, ChronoUnit.DAYS))
     .build();
 
-// Check validity before processing a request
+// Validate before processing a request
 if (!apiKey.isActive()) {
     throw new UnauthorizedException("API key is disabled or expired");
 }
 ```
 
-> **Note:** `scopes` and `roles` fields are defined but not yet enforced — permission checks are marked as TODO and will be wired into the authorization layer in a future release.
\ No newline at end of file
+## Notes
+
+- Stored in the `api_keys` MongoDB collection
+- Raw key secrets are **never persisted** — only the `hashedKey` is stored
+- `scopes` and `roles` fields are present but not yet enforced (marked TODO)
+- `tenantId` and `userId` are both indexed for efficient lookup
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKeyStats.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKeyStats.md
index bea8c95e2..17b77c45d 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKeyStats.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/apikey/.ApiKeyStats.md
@@ -1,35 +1,38 @@
-<!-- source-hash: e5ccd1f60d4e3bd99c7444684bf8ae56 -->
-MongoDB document entity for tracking API key usage statistics, storing request counts and last activity timestamp in the `api_key_stats` collection.
+<!-- source-hash: 7d5f6c5fc9513295972b5295aee6a6f5 -->
+MongoDB document entity for tracking API key usage statistics per tenant, including request counts and last usage timestamp.
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `totalRequests` | `Long` | Cumulative count of all requests made with the API key |
-| `successfulRequests` | `Long` | Count of requests that completed successfully |
-| `failedRequests` | `Long` | Count of requests that resulted in errors |
+| `id` | `String` | MongoDB document ID (`@Id`) |
+| `tenantId` | `String` | Indexed tenant identifier (implements `TenantScoped`) |
+| `totalRequests` | `Long` | Total number of API requests made |
+| `successfulRequests` | `Long` | Count of successful requests |
+| `failedRequests` | `Long` | Count of failed requests |
 | `lastUsed` | `LocalDateTime` | Timestamp of the most recent API key usage |
 
+**Collection:** `api_key_stats`
+
 ## Usage Example
 
 ```java
-// Build a new stats document
+// Build a new stats document for a tenant's API key
 ApiKeyStats stats = ApiKeyStats.builder()
-    .totalRequests(150L)
-    .successfulRequests(142L)
-    .failedRequests(8L)
+    .tenantId("tenant-abc-123")
+    .totalRequests(1500L)
+    .successfulRequests(1480L)
+    .failedRequests(20L)
     .lastUsed(LocalDateTime.now())
     .build();
 
-// Update on each API call
+// Access tenant-scoped query support via TenantScoped
+String tenantId = stats.getTenantId(); // "tenant-abc-123"
+
+// Update request counters
 stats.setTotalRequests(stats.getTotalRequests() + 1);
-stats.setSuccessfulRequests(stats.getSuccessfulRequests() + 1);
+stats.setFailedRequests(stats.getFailedRequests() + 1);
 stats.setLastUsed(LocalDateTime.now());
 ```
 
-## Notes
-
-- Lombok annotations (`@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`) auto-generate boilerplate (getters, setters, builder pattern, constructors).
-- Persisted via Spring Data MongoDB; the `@Document` annotation maps this class to the `api_key_stats` collection.
-- Designed to complement an API key entity, providing a dedicated stats document to avoid bloating the primary key record.
\ No newline at end of file
+> **Note:** The `tenantId` field is indexed (`@Indexed`) for efficient per-tenant queries across the `api_key_stats` collection. Implements `TenantScoped` to ensure consistent multi-tenancy enforcement across the OpenFrame platform.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/assignment/.ItemAssignment.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/assignment/.ItemAssignment.md
index 7db0e2778..47e05fc68 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/assignment/.ItemAssignment.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/assignment/.ItemAssignment.md
@@ -1,42 +1,42 @@
-<!-- source-hash: c8930eabeb1b31d9eaf3aa2bbece2863 -->
-MongoDB document model representing the assignment relationship between items (e.g., scripts, templates) and their targets (e.g., users, devices), stored in the `item_assignments` collection.
+<!-- source-hash: e9d6be7f1823fdb90e6a47732f7a050f -->
+MongoDB document entity representing the assignment of an item (e.g., a configuration or resource) to a specific target within a tenant-scoped context.
 
 ## Key Components
 
-| Member | Type | Description |
-|---|---|---|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `itemId` | `String` | Reference to the assigned item |
-| `itemType` | `AssignmentItemType` | Enum classifying the item (e.g., script, template) |
-| `targetType` | `AssignmentTargetType` | Enum classifying the assignment target (e.g., user, device) |
-| `targetId` | `String` | Reference to the target entity (indexed) |
-| `displayName` | `String` | Human-readable label for the assignment |
-| `createdAt` | `Instant` | Auto-populated creation timestamp via `@CreatedDate` |
+| Element | Description |
+|---|---|
+| `ItemAssignment` | Main document class mapped to the `item_assignments` MongoDB collection |
+| `TenantScoped` | Interface implemented to enforce multi-tenancy isolation via `tenantId` |
+| `AssignmentItemType` | Enum defining the type of item being assigned |
+| `AssignmentTargetType` | Enum defining the target receiving the assignment |
+| `createdAt` | Auto-populated timestamp via Spring's `@CreatedDate` |
 
 ### Indexes
 
-| Index Name | Fields | Unique |
+| Index | Fields | Purpose |
 |---|---|---|
-| `item_target_unique` | `itemId`, `targetType`, `targetId` | ✅ Yes — prevents duplicate assignments |
-| `target_lookup` | `targetType`, `targetId` | ❌ No — optimizes queries by target |
-| *(single field)* | `targetId` | ❌ No — supports direct target lookups |
+| `item_target_unique` | `itemId`, `targetType`, `targetId` | Prevents duplicate assignments |
+| `target_lookup` | `targetType`, `targetId` | Optimizes lookups by target |
+| Single field | `tenantId`, `targetId` | Fast tenant and target queries |
 
 ## Usage Example
 
 ```java
-// Building a new item assignment
+// Build and persist a new item assignment
 ItemAssignment assignment = ItemAssignment.builder()
-    .itemId("script-abc123")
+    .tenantId("tenant-abc")
+    .itemId("script-001")
     .itemType(AssignmentItemType.SCRIPT)
     .targetType(AssignmentTargetType.DEVICE)
-    .targetId("device-xyz789")
-    .displayName("Patch Tuesday Script → Workstation 42")
+    .targetId("device-xyz")
+    .displayName("Startup Script")
     .build();
 
-// Querying assignments for a specific target
-List<ItemAssignment> assignments = mongoTemplate.find(
-    Query.query(Criteria.where("targetType").is(AssignmentTargetType.DEVICE)
-        .and("targetId").is("device-xyz789")),
-    ItemAssignment.class
-);
-```
\ No newline at end of file
+itemAssignmentRepository.save(assignment);
+
+// Query assignments by target
+List<ItemAssignment> assignments = itemAssignmentRepository
+    .findByTargetTypeAndTargetId(AssignmentTargetType.DEVICE, "device-xyz");
+```
+
+> **Note:** The compound unique index on `itemId + targetType + targetId` ensures an item cannot be assigned to the same target more than once. Duplicate save attempts will throw a `DuplicateKeyException`.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthInvitation.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthInvitation.md
index d624d9f79..d0332d90f 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthInvitation.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthInvitation.md
@@ -1,30 +1,25 @@
-<!-- source-hash: f126a4480bc384add061fd55d680206b -->
-Represents a MongoDB document for authentication-based invitations, extending the base `Invitation` class with tenant-scoped uniqueness enforcement.
+<!-- source-hash: 4f8b778caf8b273d97a856190a85b0df -->
+MongoDB document entity representing an authentication invitation scoped to a tenant, combining tenant-based indexing with user invitation data.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `AuthInvitation` | MongoDB document class extending `Invitation` for auth-specific invite records |
-| `tenantId` | Indexed field scoping invitations to a specific tenant |
-| `@CompoundIndex` | Enforces unique `tenantId + email` combinations where `tenantId` exists |
+- **`AuthInvitation`** — Extends `Invitation` and `TenantScoped`, inheriting invitation fields alongside tenant context
+- **Compound Index** — `{'tenantId': 1, 'email': 1}` ensures efficient tenant-scoped lookups by email
+- **Lombok Annotations** — `@Data`, `@SuperBuilder`, `@NoArgsConstructor`, and `@EqualsAndHashCode(callSuper = true)` handle boilerplate generation while preserving parent class equality logic
 
 ## Usage Example
 
 ```java
-// Build a new auth invitation for a specific tenant
-AuthInvitation invitation = AuthInvitation.builder()
-        .tenantId("tenant-abc-123")
-        .email("user@example.com")
-        .build();
+AuthInvitation invite = AuthInvitation.builder()
+    .tenantId("tenant-123")
+    .email("user@example.com")
+    .build();
 
-// Compound index ensures no duplicate email per tenant
-// { tenantId: "tenant-abc-123", email: "user@example.com" } → unique
-```
+authInvitationRepository.save(invite);
 
-## Notes
+// Lookup by tenant + email (uses compound index)
+Optional<AuthInvitation> found = authInvitationRepository
+    .findByTenantIdAndEmail("tenant-123", "user@example.com");
+```
 
-- Inherits base fields (e.g., `email`, invite metadata) from `Invitation`
-- The `@CompoundIndex` uses a **partial filter** (`tenantId: { $exists: true }`), meaning global invitations without a `tenantId` are excluded from the uniqueness constraint
-- `@Indexed` on `tenantId` enables efficient tenant-scoped queries
-- Uses Lombok `@SuperBuilder` to support builder inheritance from the parent `Invitation` class
\ No newline at end of file
+> **Note:** The compound index on `tenantId` + `email` enforces fast scoped queries and should align with your repository query patterns to avoid full collection scans.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthUser.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthUser.md
index 8c5c82c6b..bc21a9ee2 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthUser.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/auth/.AuthUser.md
@@ -1,47 +1,41 @@
-<!-- source-hash: 38f606085128ae4efaa0eb19fe2ff7b9 -->
-MongoDB document model representing an authenticated user in OpenFrame's multi-tenant Authorization Server, extending the base `User` document with auth-specific fields and tenant isolation.
+<!-- source-hash: d7950b73d9246bd06dc2ab97e65522df -->
+Represents an authenticated user in OpenFrame's multi-tenant Authorization Server, extending the base `User` document with authentication-specific fields such as password credentials, OAuth provider info, and login metadata.
 
 ## Key Components
 
-| Member | Type | Description |
-|--------|------|-------------|
-| `tenantId` | `String` | Indexed tenant identifier; combined with `email` as a unique compound index |
-| `passwordHash` | `String` | Hashed password for `LOCAL` authentication |
-| `loginProvider` | `String` | Authentication provider (e.g., `LOCAL`, `GOOGLE`) |
-| `externalUserId` | `String` | User ID from the external OAuth/SSO provider |
-| `lastLogin` | `Instant` | Timestamp of the user's most recent login |
-| `imageUrl` | `String` | Cached profile picture URL synced from tenant cluster via `USER_UPDATED` events |
-| `getFullName()` | `String` | Derives display name from first/last name, falling back to email |
+| Field / Method | Description |
+|---|---|
+| `passwordHash` | Hashed password for local authentication |
+| `loginProvider` | Auth strategy identifier (e.g., `LOCAL`, `GOOGLE`) |
+| `externalUserId` | User ID from an external OAuth provider |
+| `lastLogin` | Timestamp of the most recent login |
+| `imageUrl` | Cached profile picture URL synced via `USER_UPDATED` events for SSO `picture` claim propagation |
+| `getFullName()` | Resolves display name from first/last name, falling back to email |
+
+**Compound Index:** Enforces uniqueness on `{tenantId, email}`, supporting domain-based multi-tenancy.
 
 ## Usage Example
 
 ```java
-// Build a new local AuthUser for a specific tenant
 AuthUser authUser = AuthUser.builder()
-        .email("jane@acme.com")
-        .firstName("Jane")
-        .lastName("Doe")
-        .tenantId("acme-corp")
-        .passwordHash(hashService.hash("s3cur3P@ss"))
-        .loginProvider("LOCAL")
-        .build();
-
-// Build an SSO user (e.g., Google)
-AuthUser ssoUser = AuthUser.builder()
-        .email("john@acme.com")
-        .tenantId("acme-corp")
-        .loginProvider("GOOGLE")
-        .externalUserId("google-uid-9876")
-        .imageUrl("https://lh3.googleusercontent.com/photo.jpg")
-        .build();
-
-// Resolve display name with fallback chain
+    .email("jane@acme.com")
+    .firstName("Jane")
+    .lastName("Doe")
+    .tenantId("acme-corp")
+    .loginProvider("GOOGLE")
+    .externalUserId("google-uid-12345")
+    .lastLogin(Instant.now())
+    .imageUrl("https://cdn.example.com/avatar.png")
+    .build();
+
+// Resolves to "Jane Doe"
 String displayName = authUser.getFullName();
-// → "Jane Doe"
-```
 
-## Notes
+// Falls back to email if no name is set
+AuthUser noName = AuthUser.builder()
+    .email("unknown@acme.com")
+    .build();
+String fallback = noName.getFullName(); // returns "unknown@acme.com"
+```
 
-- The compound index on `{tenantId, email}` enforces per-tenant email uniqueness with a partial filter (`$exists: true`), allowing global users without a `tenantId`.
-- `imageUrl` is a cache — a `null` value indicates no picture has been synced yet, not that the tenant cluster lacks one.
-- Inherits base fields (`email`, `firstName`, `lastName`, etc.) from the `User` superclass via `@SuperBuilder`.
\ No newline at end of file
+> **Note:** `imageUrl` is a cache synced from the tenant cluster — a `null` value means the picture is unknown to the auth server, not that the user has no profile image.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/clientconfiguration/.OpenFrameClientConfiguration.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/clientconfiguration/.OpenFrameClientConfiguration.md
index f133e40f4..a2d39a145 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/clientconfiguration/.OpenFrameClientConfiguration.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/clientconfiguration/.OpenFrameClientConfiguration.md
@@ -1,39 +1,33 @@
-<!-- source-hash: dda59b6bf89269879669961e3cce781d -->
-MongoDB document entity representing a versioned OpenFrame client configuration record, stored in the `openframe_client_configuration` collection.
+<!-- source-hash: fdd0650e1055933ae2b28c1082dee61c -->
+Represents a MongoDB document storing per-tenant OpenFrame client configuration, including versioning, download settings, and publish state lifecycle metadata.
 
 ## Key Components
 
 | Field | Type | Description |
-|---|---|---|
+|-------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
+| `tenantId` | `String` | Unique tenant identifier (`@Indexed(unique = true)`) |
 | `documentVersion` | `Long` | Optimistic locking version (`@Version`) |
-| `version` | `String` | Client configuration version label |
-| `downloadConfiguration` | `List<DownloadConfiguration>` | List of download configuration entries |
-| `createdAt` | `LocalDateTime` | Auto-populated creation timestamp (`@CreatedDate`) |
-| `updatedAt` | `LocalDateTime` | Auto-populated last modified timestamp (`@LastModifiedDate`) |
-| `publishState` | `PublishState` | Current publish state of the configuration |
+| `version` | `String` | Client configuration version string |
+| `downloadConfiguration` | `List<DownloadConfiguration>` | List of download configuration entries for the client |
+| `publishState` | `PublishState` | Current publish lifecycle state of the configuration |
+| `createdAt` / `updatedAt` | `LocalDateTime` | Auto-managed audit timestamps |
+
+Implements `TenantScoped` to enforce tenant isolation across the platform.
 
 ## Usage Example
 
 ```java
-// Build and save a new client configuration
 OpenFrameClientConfiguration config = OpenFrameClientConfiguration.builder()
+    .tenantId("tenant-abc-123")
     .version("1.0.0")
-    .publishState(PublishState.DRAFT)
     .downloadConfiguration(List.of(
-        DownloadConfiguration.builder()
-            .platform("windows")
-            .url("https://downloads.openframe.ai/client/1.0.0/win")
-            .build()
+        new DownloadConfiguration(/* ... */)
     ))
+    .publishState(PublishState.DRAFT)
     .build();
 
-mongoTemplate.save(config);
-
-// Retrieve and inspect state
-OpenFrameClientConfiguration saved = mongoTemplate.findById(id, OpenFrameClientConfiguration.class);
-System.out.println(saved.getPublishState()); // DRAFT
-System.out.println(saved.getDocumentVersion()); // 1 (auto-incremented)
+openFrameClientConfigurationRepository.save(config);
 ```
 
-> **Note:** This entity relies on Spring Data MongoDB auditing (`@CreatedDate`, `@LastModifiedDate`) being enabled via `@EnableMongoAuditing` in the application context. Optimistic concurrency control is enforced through the `@Version` field.
\ No newline at end of file
+> **Note:** `tenantId` has a unique index — only one active configuration document is permitted per tenant. Optimistic locking via `documentVersion` prevents concurrent write conflicts.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/connector/.ConnectorAlert.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/connector/.ConnectorAlert.md
index f7d7d4ace..a018a2468 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/connector/.ConnectorAlert.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/connector/.ConnectorAlert.md
@@ -1,38 +1,41 @@
-<!-- source-hash: 158ea3fcb14487f82c78a91ff05418f1 -->
-A MongoDB document model representing an alert generated by a connector, tracking error state, retry attempts, and resolution status within the OpenFrame platform.
+<!-- source-hash: 44283f1dbd6b2980c79fbacdd9031550 -->
+MongoDB document entity representing an alert generated by a connector, tracking error state, retry attempts, and resolution status within a tenant-scoped context.
 
 ## Key Components
 
+| Element | Description |
+|---|---|
+| `ConnectorAlert` | Main document class mapped to the `connector_alerts` MongoDB collection |
+| `TenantScoped` | Interface implemented to enforce multi-tenant data isolation |
+| `ConnectorAlertType` | Enum (external) categorizing the type of connector error |
+| `tenantId` | Indexed field for efficient tenant-based querying |
+
+## Fields
+
 | Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
+|---|---|---|
+| `id` | `String` | MongoDB document identifier |
+| `tenantId` | `String` | Tenant owner (indexed) |
 | `connectorName` | `String` | Name of the connector that triggered the alert |
-| `errorType` | `ConnectorAlertType` | Enum categorizing the alert type |
-| `errorMessage` | `String` | Human-readable error description |
+| `errorType` | `ConnectorAlertType` | Categorized error type |
+| `errorMessage` | `String` | Human-readable error detail |
 | `attempts` | `int` | Number of retry attempts made |
-| `createdAt` | `Instant` | Timestamp when the alert was first raised |
+| `createdAt` | `Instant` | Timestamp when the alert was created |
 | `resolved` | `boolean` | Whether the alert has been resolved |
-| `resolvedAt` | `Instant` | Timestamp when the alert was resolved |
-
-Stored in the `connector_alerts` MongoDB collection. Lombok annotations (`@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`) handle boilerplate generation.
+| `resolvedAt` | `Instant` | Timestamp of resolution |
 
 ## Usage Example
 
 ```java
-// Creating a new unresolved connector alert
 ConnectorAlert alert = ConnectorAlert.builder()
-    .connectorName("psa-autotask")
-    .errorType(ConnectorAlertType.AUTH_FAILURE)
-    .errorMessage("Invalid API credentials provided")
+    .tenantId("tenant-abc")
+    .connectorName("zabbix-primary")
+    .errorType(ConnectorAlertType.CONNECTION_FAILURE)
+    .errorMessage("Unable to reach Zabbix host at 10.0.0.5")
     .attempts(3)
     .createdAt(Instant.now())
     .resolved(false)
     .build();
 
-// Marking an existing alert as resolved
-alert.setResolved(true);
-alert.setResolvedAt(Instant.now());
-
-// Saving via Spring Data MongoDB repository
 connectorAlertRepository.save(alert);
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Device.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Device.md
index 4b5795118..139d8ff65 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Device.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Device.md
@@ -1,36 +1,37 @@
-<!-- source-hash: 20dec1a2aa7a34481afc1a3c817a5fbb -->
-Represents a managed device entity stored in the MongoDB `devices` collection, serving as the core data model for tracking physical and virtual machines across the OpenFrame platform.
+<!-- source-hash: 90469dc6098b9c706ea0ac868ab32b26 -->
+MongoDB document entity representing a managed device within a tenant's infrastructure, storing hardware identity, operational status, and health metadata for the OpenFrame platform.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `machineId` | `String` | Foreign reference linking to the Machine entity |
-| `serialNumber` | `String` | Unique hardware serial identifier |
-| `model` | `String` | Device model name/number |
-| `osVersion` | `String` | Operating system version string |
-| `status` | `String` | Lifecycle state: `ACTIVE`, `OFFLINE`, or `MAINTENANCE` |
-| `type` | `DeviceType` | Enum classifying device category (e.g., `DESKTOP`, `LAPTOP`, `SERVER`) |
-| `lastCheckin` | `Instant` | UTC timestamp of the most recent agent heartbeat |
-| `configuration` | `DeviceConfiguration` | Embedded configuration details |
-| `health` | `DeviceHealth` | Embedded health metrics and diagnostics |
+| Element | Type | Description |
+|---|---|---|
+| `Device` | `@Document` class | Root MongoDB entity mapped to the `devices` collection |
+| `TenantScoped` | Interface | Enforces multi-tenancy isolation via `tenantId` |
+| `DeviceType` | Enum | Classifies devices — `DESKTOP`, `LAPTOP`, `SERVER`, etc. |
+| `DeviceConfiguration` | Embedded | Stores device-level configuration settings |
+| `DeviceHealth` | Embedded | Tracks health metrics and diagnostics |
+| `lastCheckin` | `Instant` | Timestamp of the most recent device check-in |
+| `status` | `String` | Lifecycle state — `ACTIVE`, `OFFLINE`, `MAINTENANCE` |
 
 ## Usage Example
 
 ```java
+// Create and persist a new managed device
 Device device = new Device();
-device.setMachineId("machine-abc123");
-device.setSerialNumber("SN-987654");
+device.setTenantId("tenant-abc");
+device.setMachineId("machine-xyz-001");
+device.setSerialNumber("SN-20240101-001");
 device.setModel("Dell OptiPlex 7090");
-device.setOsVersion("Windows 11 22H2");
-device.setStatus("ACTIVE");
+device.setOsVersion("Windows 11 Pro 23H2");
 device.setType(DeviceType.DESKTOP);
+device.setStatus("ACTIVE");
 device.setLastCheckin(Instant.now());
-device.setConfiguration(new DeviceConfiguration());
-device.setHealth(new DeviceHealth());
 
 deviceRepository.save(device);
+
+// Query all active devices for a tenant
+List<Device> activeDevices = deviceRepository
+    .findByTenantIdAndStatus("tenant-abc", "ACTIVE");
 ```
 
-> **Note:** Lombok's `@Data` auto-generates getters, setters, `equals()`, `hashCode()`, and `toString()`. The `lastCheckin` field should be updated on every agent heartbeat to accurately reflect device availability within the Flamingo monitoring stack.
\ No newline at end of file
+> **Note:** `tenantId` is indexed (`@Indexed`) to optimize multi-tenant query performance across large device fleets. Always filter by `tenantId` first in repository queries to leverage this index.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Machine.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Machine.md
index 899082efa..04f24b3ea 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Machine.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/device/.Machine.md
@@ -1,34 +1,35 @@
-<!-- source-hash: e1b49c17605d5bacefb9b21472bbd8c0 -->
-Represents a managed device (machine) in the OpenFrame platform, stored in the MongoDB `machines` collection with full lifecycle, security, and compliance tracking.
+<!-- source-hash: 264d31c4e0a3893d107bd365d3f374ed -->
+MongoDB document entity representing a managed device (machine) within a tenant's infrastructure, storing hardware identity, agent status, OS details, and security/compliance state.
 
 ## Key Components
 
 | Field | Type | Description |
-|---|---|---|
-| `id` | `String` | MongoDB document ID (`@Id`) |
-| `machineId` | `String` | Primary auth identifier, mirrors `OAuthClient` |
-| `status` | `DeviceStatus` | Current device status (indexed) |
-| `organizationId` | `String` | Tenant scoping key (indexed) |
+|-------|------|-------------|
+| `machineId` | `String` | Primary device identifier, shared with `OAuthClient` for authentication |
+| `tenantId` | `String` | Tenant scope (indexed) — implements `TenantScoped` |
+| `organizationId` | `String` | Organizational grouping within a tenant (indexed) |
+| `status` | `DeviceStatus` | Current device connectivity/operational status (indexed) |
 | `type` | `DeviceType` | Device category — workstation, server, etc. (indexed) |
-| `osType` / `osVersion` | `String` | OS platform and version details |
-| `securityState` | `SecurityState` | Current security posture |
-| `complianceState` | `ComplianceState` | Compliance evaluation result |
-| `securityAlerts` | `List<SecurityAlert>` | Active security alerts on the device |
-| `complianceRequirements` | `List<ComplianceRequirement>` | Evaluated compliance rules |
-| `registeredAt` | `Instant` | Auto-set on first registration (`@CreatedDate`) |
-| `updatedAt` | `Instant` | Auto-updated on every save (`@LastModifiedDate`) |
-| `stuckNotifiedAt` | `Instant` | Tracks if a `DEVICE_STUCK` event has been dispatched |
+| `osType` | `String` | Operating system family (indexed) |
+| `securityState` | `SecurityState` | Aggregated security posture |
+| `complianceState` | `ComplianceState` | Current compliance evaluation result |
+| `securityAlerts` | `List<SecurityAlert>` | Active security findings on the device |
+| `complianceRequirements` | `List<ComplianceRequirement>` | Policy requirements evaluated against the device |
+| `registeredAt` | `Instant` | First registration timestamp (`@CreatedDate`) |
+| `stuckNotifiedAt` | `Instant` | Tracks whether a `DEVICE_STUCK` event has been dispatched |
 
 ## Usage Example
 
 ```java
 Machine machine = new Machine();
-machine.setMachineId("mch-abc123");
-machine.setOrganizationId("org-xyz");
-machine.setHostname("workstation-01");
+machine.setMachineId("machine-abc123");
+machine.setTenantId("tenant-001");
+machine.setOrganizationId("org-42");
+machine.setHostname("workstation-nyc-01");
+machine.setDisplayName("Alice's MacBook");
 machine.setType(DeviceType.WORKSTATION);
-machine.setOsType("WINDOWS");
-machine.setOsVersion("11");
+machine.setOsType("macOS");
+machine.setOsVersion("14.4.1");
 machine.setStatus(DeviceStatus.ONLINE);
 machine.setLastSeen(Instant.now());
 machine.setSecurityState(SecurityState.SECURE);
@@ -37,4 +38,4 @@ machine.setComplianceState(ComplianceState.COMPLIANT);
 machineRepository.save(machine);
 ```
 
-> **Note:** `machineId` is shared with the `OAuthClient` record and serves as the primary authentication identity for agent-to-platform communication. The `stuckNotifiedAt` field remains `null` until a stuck-device event is triggered, preventing duplicate alerts.
\ No newline at end of file
+> `machineId` doubles as the OAuth client identifier — always ensure it matches the corresponding `OAuthClient` record to maintain consistent device authentication.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.CoreEvent.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.CoreEvent.md
index 3f44653a0..a337c3c10 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.CoreEvent.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.CoreEvent.md
@@ -1,38 +1,41 @@
-<!-- source-hash: a223c9eae74a4f9a292555d72ddf11a5 -->
-MongoDB document model representing a system event within the OpenFrame core service, used to track and persist event lifecycle states.
+<!-- source-hash: 1c72be2e970810a6958715a99212ce48 -->
+MongoDB document model representing a tenant-scoped event record in the OpenFrame core event system.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `type` | `String` | Categorizes the event (e.g., ticket created, alert triggered) |
+| `tenantId` | `String` | Indexed tenant reference (implements `TenantScoped`) |
+| `type` | `String` | Event category/name identifier |
 | `payload` | `String` | Serialized event data (typically JSON) |
 | `timestamp` | `Instant` | UTC time the event was recorded |
-| `userId` | `String` | Reference to the user who triggered the event |
-| `status` | `EventStatus` | Current lifecycle state of the event |
+| `userId` | `String` | User who triggered the event |
+| `status` | `EventStatus` | Current processing state |
 | `EventStatus` | `enum` | `CREATED` → `PROCESSING` → `COMPLETED` / `FAILED` |
 
 ## Usage Example
 
 ```java
+// Creating and persisting a new event
 CoreEvent event = new CoreEvent();
+event.setTenantId("tenant-abc");
 event.setType("TICKET_CREATED");
-event.setPayload("{\"ticketId\": \"T-1042\", \"priority\": \"HIGH\"}");
+event.setPayload("{\"ticketId\": \"T-1001\", \"priority\": \"HIGH\"}");
 event.setTimestamp(Instant.now());
-event.setUserId("user-abc123");
+event.setUserId("user-xyz");
 event.setStatus(CoreEvent.EventStatus.CREATED);
 
-// Persist via Spring Data MongoDB repository
-eventRepository.save(event);
+mongoTemplate.save(event); // persisted to "events" collection
 
-// Query events by status
-List<CoreEvent> pending = eventRepository.findByStatus(CoreEvent.EventStatus.PROCESSING);
+// Checking terminal states
+boolean isDone = event.getStatus() == CoreEvent.EventStatus.COMPLETED
+              || event.getStatus() == CoreEvent.EventStatus.FAILED;
 ```
 
 ## Notes
 
-- Stored in the `events` MongoDB collection via `@Document(collection = "events")`
-- Uses Lombok `@Data` for auto-generated getters, setters, `equals`, `hashCode`, and `toString`
-- `payload` is stored as a raw `String`; callers are responsible for serialization/deserialization
-- Lifecycle flows: `CREATED` → `PROCESSING` → `COMPLETED` or `FAILED`
\ No newline at end of file
+- Stored in the `events` MongoDB collection via `@Document`
+- `tenantId` is indexed for efficient per-tenant queries, enforcing data isolation across MSP clients
+- `payload` is untyped (`String`) — callers are responsible for serialization/deserialization
+- Lombok `@Data` generates getters, setters, `equals`, `hashCode`, and `toString`
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.Event.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.Event.md
index ac9b28aa0..0d846e129 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.Event.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.Event.md
@@ -1,37 +1,41 @@
-<!-- source-hash: 758d56d9600d19e7409e3a63789f111b -->
-MongoDB document entity representing a system event with metadata including type, payload, timestamp, and user association.
+<!-- source-hash: a15fe5580727c345b6c9bb048a74ecf2 -->
+Represents a tenant-scoped event document persisted in the MongoDB `events` collection, capturing audit/activity records with a typed payload and timestamp.
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `type` | `String` | Event category or action name |
-| `payload` | `String` | Serialized event data |
+| `tenantId` | `String` | Indexed tenant reference for multi-tenancy scoping |
+| `type` | `String` | Event category/name (e.g., `TICKET_CREATED`) |
+| `payload` | `String` | Serialized event data (typically JSON) |
 | `timestamp` | `Instant` | UTC time the event occurred |
-| `userId` | `String` | ID of the user who triggered the event |
+| `userId` | `String` | Originating user reference |
+
+Implements `TenantScoped` to enforce multi-tenant data isolation across the platform.
 
 ## Usage Example
 
 ```java
-// Create a new Event using the Lombok builder
 Event event = Event.builder()
+    .tenantId("tenant-123")
     .type("TICKET_CREATED")
-    .payload("{\"ticketId\": \"T-1042\", \"priority\": \"high\"}")
+    .payload("{\"ticketId\":\"t-456\",\"priority\":\"HIGH\"}")
     .timestamp(Instant.now())
-    .userId("user-abc123")
+    .userId("user-789")
     .build();
 
-// Save to MongoDB via a repository
-eventRepository.save(event);
-
-// Retrieve events by type
-List<Event> ticketEvents = eventRepository.findByType("TICKET_CREATED");
+mongoTemplate.save(event);
 ```
 
-## Notes
+Querying by tenant:
+
+```java
+Query query = new Query(
+    Criteria.where("tenantId").is("tenant-123")
+             .and("type").is("TICKET_CREATED")
+);
+List<Event> events = mongoTemplate.find(query, Event.class);
+```
 
-- Stored in the `events` MongoDB collection via `@Document(collection = "events")`
-- `@Data` generates getters, setters, `equals`, `hashCode`, and `toString`
-- `@Builder` enables the fluent builder pattern for construction
-- `payload` is stored as a raw `String`; consider JSON serialization for structured data
\ No newline at end of file
+> The `tenantId` index ensures efficient per-tenant event queries at scale, critical for Flamingo's multi-tenant MSP architecture.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.ExternalApplicationEvent.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.ExternalApplicationEvent.md
index 661578b11..d23622ac5 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.ExternalApplicationEvent.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/event/.ExternalApplicationEvent.md
@@ -1,41 +1,40 @@
-<!-- source-hash: e4cdba7e477edf9097aa5b028beeedbe -->
-A MongoDB document model representing events received from external applications, stored in the `external_application_events` collection.
+<!-- source-hash: dde02baa77a7b2e5ef7f97083a4fca0d -->
+Represents a MongoDB document for storing external application events scoped to a specific tenant, capturing event type, payload, metadata, and user context.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `type` | `String` | Event type classifier |
-| `payload` | `String` | Raw event payload content |
-| `timestamp` | `Instant` | UTC timestamp of the event |
-| `userId` | `String` | Associated user identifier |
-| `metadata` | `EventMetadata` | Nested metadata object |
-
-### `EventMetadata` (nested class)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `source` | `String` | Origin system or application name |
-| `version` | `String` | Event schema or API version |
-| `tags` | `Map<String, String>` | Arbitrary key-value tags for filtering/routing |
+| Element | Type | Description |
+|---------|------|-------------|
+| `ExternalApplicationEvent` | `@Document` class | Root MongoDB document mapped to `external_application_events` collection |
+| `TenantScoped` | Interface | Enforces multi-tenancy by requiring a `tenantId` field |
+| `EventMetadata` | Nested `@Data` class | Holds auxiliary event info: `source`, `version`, and `tags` |
+| `tenantId` | `@Indexed` field | Indexed for efficient per-tenant queries |
+| `timestamp` | `Instant` | UTC-based event occurrence time |
+| `payload` | `String` | Raw event payload (typically serialized JSON) |
 
 ## Usage Example
 
 ```java
+// Build and persist an external application event
+ExternalApplicationEvent.EventMetadata metadata = new ExternalApplicationEvent.EventMetadata();
+metadata.setSource("zendesk");
+metadata.setVersion("v2");
+metadata.setTags(Map.of("env", "production", "region", "us-east-1"));
+
 ExternalApplicationEvent event = new ExternalApplicationEvent();
+event.setTenantId("tenant-abc");
 event.setType("ticket.created");
-event.setPayload("{\"ticketId\": \"T-123\", \"priority\": \"high\"}");
+event.setPayload("{\"ticketId\":\"12345\",\"priority\":\"high\"}");
+event.setUserId("user-xyz");
 event.setTimestamp(Instant.now());
-event.setUserId("user-456");
-
-ExternalApplicationEvent.EventMetadata metadata = new ExternalApplicationEvent.EventMetadata();
-metadata.setSource("connectwise");
-metadata.setVersion("1.0");
-metadata.setTags(Map.of("env", "production", "region", "us-east"));
-
 event.setMetadata(metadata);
+
 mongoTemplate.save(event);
+
+// Query events by tenant
+Query query = new Query(Criteria.where("tenantId").is("tenant-abc")
+    .and("type").is("ticket.created"));
+List<ExternalApplicationEvent> events = mongoTemplate.find(query, ExternalApplicationEvent.class);
 ```
 
-> **Note:** Uses Lombok `@Data` for automatic generation of getters, setters, `equals`, `hashCode`, and `toString` on both the parent and nested `EventMetadata` class.
\ No newline at end of file
+> The `tenantId` index ensures queries are isolated per tenant, which is critical for MSP multi-tenant environments where event streams from tools like Zendesk, ConnectWise, or Autotask must remain segregated.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/installedagents/.InstalledAgent.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/installedagents/.InstalledAgent.md
index 5423924f6..9fb041808 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/installedagents/.InstalledAgent.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/installedagents/.InstalledAgent.md
@@ -1,36 +1,30 @@
-<!-- source-hash: 1e081b8ad635626102fb78b288134013 -->
-Represents a MongoDB document model for tracking agents installed on managed machines within the OpenFrame platform.
+<!-- source-hash: 9920149a6d734093f3989495f5e6160d -->
+Represents a MongoDB document entity for tracking agents installed on managed machines within a tenant's environment.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
+| Member | Type | Description |
+|--------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `machineId` | `String` | Reference to the managed machine |
-| `agentType` | `String` | Type/category of the installed agent |
+| `tenantId` | `String` | Indexed tenant reference (implements `TenantScoped`) |
+| `machineId` | `String` | Reference to the machine hosting the agent |
+| `agentType` | `String` | Classification/type of the installed agent |
 | `version` | `String` | Installed agent version string |
-| `createdAt` | `String` | Timestamp of agent installation record creation |
-| `updatedAt` | `String` | Timestamp of last record update |
-
-**Annotations:**
-- `@Data` — Lombok-generated getters, setters, `equals`, `hashCode`, and `toString`
-- `@Document(collection = "installed_agents")` — Maps to the `installed_agents` MongoDB collection
+| `createdAt` | `String` | Record creation timestamp |
+| `updatedAt` | `String` | Record last-update timestamp |
 
 ## Usage Example
 
 ```java
-// Create and persist a new InstalledAgent record
 InstalledAgent agent = new InstalledAgent();
-agent.setMachineId("machine-abc-123");
+agent.setTenantId("tenant-abc");
+agent.setMachineId("machine-001");
 agent.setAgentType("monitoring");
 agent.setVersion("2.1.0");
 agent.setCreatedAt(Instant.now().toString());
 agent.setUpdatedAt(Instant.now().toString());
 
 installedAgentRepository.save(agent);
-
-// Retrieve agents by machine
-List<InstalledAgent> agents = installedAgentRepository.findByMachineId("machine-abc-123");
 ```
 
-> **Note:** `createdAt` and `updatedAt` are stored as `String` types. Consider using `Instant` or `LocalDateTime` with a MongoDB converter for timezone-safe timestamp handling in production.
\ No newline at end of file
+> **Note:** `tenantId` is indexed for efficient multi-tenant queries. All queries against the `installed_agents` collection should scope by `tenantId` to enforce tenant isolation per the `TenantScoped` contract.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.GenericContext.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.GenericContext.md
index 062db8168..efd82ecdb 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.GenericContext.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.GenericContext.md
@@ -1,37 +1,30 @@
-<!-- source-hash: a3297719cfb2e8bf8aa7630ec6465f06 -->
-A generic notification context implementation that extends `NotificationContext`, carrying an arbitrary string payload for flexible notification data transport.
+<!-- source-hash: 7c03ffbacc256c4a6849c48801cb74db -->
+A flexible, generic implementation of `NotificationContext` that carries an arbitrary string payload and type identifier for notifications that don't require a specialized context structure.
 
 ## Key Components
 
-| Element | Type | Description |
-|---|---|---|
-| `GenericContext` | Class | Concrete subclass of `NotificationContext` |
-| `payload` | `String` | Arbitrary string data attached to the notification |
+| Member | Type | Description |
+|--------|------|-------------|
+| `type` | `String` | Identifies the category or kind of the generic notification |
+| `payload` | `String` | Arbitrary string content (e.g., JSON, plain text) associated with the notification |
 
-Lombok annotations handle boilerplate automatically:
-
-- `@Data` — generates getters, setters, `equals`, `hashCode`, and `toString`
-- `@SuperBuilder` — enables builder pattern with parent class field inclusion
-- `@NoArgsConstructor` / `@AllArgsConstructor` — generates both constructors
-- `@EqualsAndHashCode(callSuper = true)` — includes parent fields in equality checks
-- `@ToString(callSuper = true)` — includes parent fields in string representation
+Inherits all fields and behavior from `NotificationContext` via Lombok's `@SuperBuilder`, `@EqualsAndHashCode(callSuper = true)`, and `@ToString(callSuper = true)`.
 
 ## Usage Example
 
 ```java
-// Builder pattern (includes parent NotificationContext fields)
+// Build a generic notification context with a JSON payload
 GenericContext context = GenericContext.builder()
-    .payload("{\"event\":\"ticket.created\",\"ticketId\":\"123\"}")
+    .type("ALERT")
+    .payload("{\"message\": \"Disk usage exceeded 90%\"}")
     .build();
 
-// All-args constructor
-GenericContext context = new GenericContext("{\"event\":\"ticket.updated\"}");
-
-// Accessing the payload
-String payload = context.getPayload();
+// Access fields
+String notificationType = context.getType();   // "ALERT"
+String notificationData = context.getPayload(); // "{\"message\": ...}"
 
-// Updating the payload
-context.setPayload("{\"event\":\"ticket.closed\"}");
+// Use with a notification service
+notificationService.send(context);
 ```
 
-> **Tip:** Use `GenericContext` when no strongly-typed context subclass exists for your notification type — simply serialize your data to JSON and pass it as the `payload` string.
\ No newline at end of file
+> **Note:** `payload` is intentionally untyped — callers are responsible for serializing/deserializing the content. For strongly typed notifications, consider extending `NotificationContext` directly with dedicated fields instead.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.NotificationContext.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.NotificationContext.md
index 2d8c599e1..8dacfa668 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.NotificationContext.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/notification/.NotificationContext.md
@@ -1,47 +1,46 @@
-<!-- source-hash: fbdadaea761e0916d7d59cb25d7214f3 -->
-Abstract base class for notification context payloads, enabling polymorphic JSON deserialization based on a `type` discriminator field.
+<!-- source-hash: 7d3878a3b74cc1c612b2276a7c2471b0 -->
+Abstract base class for polymorphic notification context objects, enabling Jackson to deserialize notification payloads into their correct subtype based on a `type` discriminator field.
 
 ## Key Components
 
 | Element | Description |
 |---|---|
-| `type` | String discriminator field used by Jackson to resolve the concrete subclass at deserialization time |
-| `@JsonTypeInfo` | Configures polymorphic type handling using `Id.NAME`, reading from the existing `type` property |
-| `defaultImpl = GenericContext.class` | Falls back to `GenericContext` when no matching type name is registered |
-| `@SuperBuilder` | Enables builder inheritance across subclasses |
+| `NotificationContext` | Abstract base class all notification context types must extend |
+| `getType()` | Abstract method subclasses must implement to declare their discriminator value |
+| `@JsonTypeInfo` | Configures polymorphic deserialization using the `type` property on the JSON object |
+| `defaultImpl = GenericContext.class` | Falls back to `GenericContext` when no matching subtype is found |
+| `@SuperBuilder` | Enables Lombok builder inheritance across subclass hierarchies |
+| `@NoArgsConstructor` | Provides a no-arg constructor required for Jackson deserialization |
 
 ## Usage Example
 
 ```java
-// Define a concrete subclass
-@JsonTypeName("ticket")
-@Data
+// Define a concrete subtype
+@JsonTypeName("ticket_created")
 @SuperBuilder
 @NoArgsConstructor
-@AllArgsConstructor
-public class TicketContext extends NotificationContext {
+public class TicketCreatedContext extends NotificationContext {
+
     private String ticketId;
     private String summary;
+
+    @Override
+    public String getType() {
+        return "ticket_created";
+    }
 }
 
-// JSON deserialization — Jackson resolves to TicketContext
+// Jackson will deserialize to the correct subtype automatically
 String json = """
     {
-      "type": "ticket",
+      "type": "ticket_created",
       "ticketId": "TKT-001",
       "summary": "Server is down"
     }
     """;
 
 NotificationContext ctx = objectMapper.readValue(json, NotificationContext.class);
-// ctx instanceof TicketContext → true
-
-// Builder usage
-TicketContext context = TicketContext.builder()
-    .type("ticket")
-    .ticketId("TKT-001")
-    .summary("Server is down")
-    .build();
+// ctx is a TicketCreatedContext instance
 ```
 
-> Subclasses must register their type name (e.g. via `@JsonTypeName`) and extend `NotificationContext` to participate in polymorphic deserialization. Unknown types fall back to `GenericContext`.
\ No newline at end of file
+> **Note:** Subclasses must register themselves with `@JsonTypeName` and be discoverable by Jackson (via `@JsonSubTypes` on this class or classpath scanning) for polymorphic resolution to work correctly.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoOAuth2Authorization.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoOAuth2Authorization.md
index a9681de42..84ab045aa 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoOAuth2Authorization.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoOAuth2Authorization.md
@@ -1,40 +1,40 @@
-<!-- source-hash: c3eac3c1fc5f7dad83f7704974c43c65 -->
-MongoDB document entity for persisting OAuth2 authorization state, including authorization codes, access tokens, and refresh tokens, with automatic TTL-based expiry cleanup.
+<!-- source-hash: 275f0871f1996ccb08eafa150f5c96eb -->
+MongoDB document entity representing an OAuth2 authorization record within the OpenFrame platform, storing all token state (authorization code, access token, refresh token) alongside PKCE reconstruction data and automatic TTL-based expiry.
 
 ## Key Components
 
-| Field / Method | Description |
-|---|---|
-| `id` | Primary key (`@Id`) for the authorization document |
-| `registeredClientId` | Indexed reference to the OAuth2 registered client |
-| `principalName` | Indexed name of the authenticated principal |
-| `authorizationGrantType` | Grant type used (e.g., `authorization_code`) |
-| `ar*` fields | Minimal PKCE snapshot fields (client ID, redirect URI, scopes, state, code challenge) stored as flat strings to avoid MongoDB dotted-key issues |
-| `state` | Indexed OAuth2 state parameter |
-| `authorizationCode*` | Authorization code value, issuance/expiry timestamps, and metadata |
-| `accessToken*` | Access token value, timestamps, type, scopes, and metadata |
-| `refreshToken*` | Refresh token value, timestamps, and metadata |
-| `expiresAt` | TTL index field (`expireAfterSeconds = 0`) — MongoDB auto-deletes the document when this timestamp passes |
-| `updateExpiresAt()` | Derives `expiresAt` as the maximum non-null expiry across all token types |
+| Field Group | Fields | Purpose |
+|---|---|---|
+| Identity | `id`, `tenantId`, `registeredClientId`, `principalName` | Multi-tenant authorization ownership |
+| PKCE Snapshot | `arClientId`, `arRedirectUri`, `arScopes`, `arState`, `arAdditional` | Minimal flat fields for PKCE flow reconstruction (avoids dotted-key issues) |
+| Authorization Code | `authorizationCodeValue`, `*IssuedAt`, `*ExpiresAt`, `*Metadata` | Authorization code grant state |
+| Access Token | `accessTokenValue`, `*IssuedAt`, `*ExpiresAt`, `accessTokenType`, `accessTokenScopes` | Issued access token lifecycle |
+| Refresh Token | `refreshTokenValue`, `*IssuedAt`, `*ExpiresAt`, `*Metadata` | Refresh token lifecycle |
+| TTL | `expiresAt` | MongoDB TTL index — auto-deletes expired documents |
 
-## Usage Example
-
-```java
-MongoOAuth2Authorization authorization = new MongoOAuth2Authorization();
-authorization.setId(UUID.randomUUID().toString());
-authorization.setRegisteredClientId("my-client");
-authorization.setPrincipalName("user@example.com");
-authorization.setAuthorizationGrantType("authorization_code");
+**`updateExpiresAt()`** — Computes the latest expiration across all three token types and sets `expiresAt`, driving the MongoDB TTL index for automatic cleanup.
 
-// Set token details
-authorization.setAccessTokenValue(tokenValue);
-authorization.setAccessTokenIssuedAt(Instant.now());
-authorization.setAccessTokenExpiresAt(Instant.now().plusSeconds(3600));
+**Indexes:**
+- Compound: `registeredClientId + principalName`
+- Single: `tenantId`, `state`, `accessTokenValue`, `refreshTokenValue`
+- TTL: `expiresAt` (`expireAfterSeconds = 0`)
 
-// Compute TTL — must be called after any token expiry field is updated
-authorization.updateExpiresAt();
+## Usage Example
 
-mongoOAuth2AuthorizationRepository.save(authorization);
+```java
+MongoOAuth2Authorization auth = new MongoOAuth2Authorization();
+auth.setId(UUID.randomUUID().toString());
+auth.setTenantId("tenant-abc");
+auth.setRegisteredClientId("client-123");
+auth.setPrincipalName("user@example.com");
+auth.setAuthorizationGrantType("authorization_code");
+
+// Set token expiry fields, then compute TTL
+auth.setAccessTokenExpiresAt(Instant.now().plusSeconds(3600));
+auth.setRefreshTokenExpiresAt(Instant.now().plusSeconds(86400));
+auth.updateExpiresAt(); // expiresAt = refreshTokenExpiresAt (latest)
+
+mongoTemplate.save(auth);
 ```
 
-> **Note:** Always call `updateExpiresAt()` after modifying any token expiry field to ensure the MongoDB TTL index remains accurate and stale documents are cleaned up automatically.
\ No newline at end of file
+> **Note:** Always call `updateExpiresAt()` after modifying any token expiration field to ensure the MongoDB TTL index reflects the correct document lifetime.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoRegisteredClient.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoRegisteredClient.md
index 8c8fb4717..191e40274 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoRegisteredClient.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.MongoRegisteredClient.md
@@ -1,34 +1,35 @@
-<!-- source-hash: a3e22405c7001efa714a5d284ef4fcd4 -->
-MongoDB document entity representing an OAuth 2.0 registered client, mapped to the `oauth_registered_clients` collection for persisting client credentials and authorization configuration.
+<!-- source-hash: bfb5dfef883833dc1c7c3c0a87300bc1 -->
+MongoDB document entity representing an OAuth 2.0 registered client, stored in the `oauth_registered_clients` collection with multi-tenant isolation via a compound unique index on `tenantId` and `clientId`.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | Primary document identifier (`@Id`) |
-| `clientId` | `String` | Unique OAuth client identifier (`@Indexed(unique = true)`) |
+| Member | Type | Description |
+|--------|------|-------------|
+| `id` | `String` | MongoDB document `_id` |
+| `tenantId` | `String` | Tenant identifier (enforces `TenantScoped`) |
+| `clientId` | `String` | OAuth 2.0 client identifier |
 | `clientSecret` | `String` | Hashed client secret |
-| `authenticationMethods` | `Set<String>` | Supported authentication methods (e.g., `client_secret_basic`) |
-| `grantTypes` | `Set<String>` | Allowed grant types (e.g., `authorization_code`, `refresh_token`) |
-| `redirectUris` | `Set<String>` | Permitted redirect URIs post-authorization |
-| `scopes` | `Set<String>` | OAuth scopes the client may request |
+| `authenticationMethods` | `Set<String>` | Allowed auth methods (e.g. `client_secret_basic`) |
+| `grantTypes` | `Set<String>` | Allowed grant types (e.g. `authorization_code`, `refresh_token`) |
+| `redirectUris` | `Set<String>` | Whitelisted redirect URIs |
+| `scopes` | `Set<String>` | Permitted OAuth scopes |
 | `requireProofKey` | `boolean` | Enforces PKCE (Proof Key for Code Exchange) |
-| `requireAuthorizationConsent` | `boolean` | Requires explicit user consent screen |
-| `accessTokenTtlSeconds` | `long` | Access token time-to-live in seconds |
-| `refreshTokenTtlSeconds` | `long` | Refresh token time-to-live in seconds |
-| `reuseRefreshTokens` | `boolean` | Whether refresh tokens are reused on rotation |
+| `requireAuthorizationConsent` | `boolean` | Prompts user consent screen |
+| `accessTokenTtlSeconds` | `long` | Access token lifetime |
+| `refreshTokenTtlSeconds` | `long` | Refresh token lifetime |
+| `reuseRefreshTokens` | `boolean` | Controls refresh token rotation |
 
 ## Usage Example
 
 ```java
 MongoRegisteredClient client = MongoRegisteredClient.builder()
-    .id(UUID.randomUUID().toString())
-    .clientId("openframe-web")
+    .tenantId("tenant-abc")
+    .clientId("my-app")
     .clientSecret("{bcrypt}$2a$10$...")
     .authenticationMethods(Set.of("client_secret_basic"))
     .grantTypes(Set.of("authorization_code", "refresh_token"))
-    .redirectUris(Set.of("https://app.openframe.ai/callback"))
-    .scopes(Set.of("openid", "profile", "email"))
+    .redirectUris(Set.of("https://app.example.com/callback"))
+    .scopes(Set.of("openid", "profile", "read:tickets"))
     .requireProofKey(true)
     .requireAuthorizationConsent(false)
     .accessTokenTtlSeconds(3600)
@@ -36,7 +37,7 @@ MongoRegisteredClient client = MongoRegisteredClient.builder()
     .reuseRefreshTokens(false)
     .build();
 
-mongoRegisteredClientRepository.save(client);
+mongoTemplate.save(client);
 ```
 
-> **Note:** `clientId` is enforced as unique at the database index level, preventing duplicate client registrations across the OpenFrame OAuth authorization server.
\ No newline at end of file
+> **Note:** The compound index `tenant_clientId_idx` guarantees `clientId` uniqueness is scoped per tenant, preventing cross-tenant `clientId` collisions.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthClient.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthClient.md
index 418fc38c6..93691b35a 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthClient.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthClient.md
@@ -1,38 +1,36 @@
-<!-- source-hash: 66e5364571ae518abe1ff22f75c4f977 -->
-MongoDB document entity representing an OAuth 2.0 client registration, mapped to the `oauth_clients` collection.
+<!-- source-hash: da6cbc740dc9dc7a8514675e67d30067 -->
+MongoDB document entity representing an OAuth 2.0 client registration, scoped to a specific tenant within the OpenFrame platform.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `clientId` | `String` | Public OAuth client identifier |
-| `clientSecret` | `String` | Confidential client secret |
-| `machineId` | `String` | Associated machine/tenant reference |
+| Member | Type | Description |
+|--------|------|-------------|
+| `id` | `String` | MongoDB document primary key (`@Id`) |
+| `tenantId` | `String` | Indexed tenant identifier for multi-tenancy isolation |
+| `clientId` | `String` | OAuth 2.0 client identifier |
+| `clientSecret` | `String` | OAuth 2.0 client secret |
+| `machineId` | `String` | Optional machine/device association |
 | `redirectUris` | `String[]` | Allowed redirect URIs for authorization flows |
-| `grantTypes` | `String[]` | Permitted OAuth grant types |
-| `scopes` | `String[]` | Access scopes the client may request |
+| `grantTypes` | `String[]` | Permitted OAuth grant types (`authorization_code`, `password`, `client_credentials`, `refresh_token`) |
+| `scopes` | `String[]` | Permitted OAuth scopes |
 | `roles` | `String[]` | Assigned roles (defaults to empty array) |
 | `enabled` | `boolean` | Whether the client is active (defaults to `true`) |
 
-**Supported Grant Types:** `authorization_code`, `password`, `client_credentials`, `refresh_token`
-
 ## Usage Example
 
 ```java
-// Creating a new machine-to-machine OAuth client
 OAuthClient client = new OAuthClient();
-client.setClientId("openframe-service");
+client.setTenantId("tenant-abc");
+client.setClientId("my-service-client");
 client.setClientSecret("s3cr3t");
-client.setMachineId("machine-abc123");
-client.setGrantTypes(new String[]{"client_credentials"});
+client.setGrantTypes(new String[]{"client_credentials", "refresh_token"});
 client.setScopes(new String[]{"read", "write"});
-client.setRoles(new String[]{"ROLE_SERVICE"});
-client.setRedirectUris(new String[]{});
+client.setRedirectUris(new String[]{"https://app.example.com/callback"});
+client.setRoles(new String[]{"ROLE_API"});
 client.setEnabled(true);
 
-// Persisted via Spring Data MongoDB repository
-oAuthClientRepository.save(client);
+// Persisted to MongoDB collection: oauth_clients
+mongoTemplate.save(client);
 ```
 
-> **Note:** `clientSecret` should always be stored hashed. The `machineId` field links this client to a specific OpenFrame machine context, enabling per-tenant OAuth isolation.
\ No newline at end of file
+> **Note:** Implements `TenantScoped` to enforce tenant isolation across all queries. The `tenantId` field is indexed for efficient per-tenant lookups across the `oauth_clients` collection.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthToken.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthToken.md
index 5fb46df11..fed77578d 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthToken.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/oauth/.OAuthToken.md
@@ -1,39 +1,36 @@
-<!-- source-hash: 7b6a55083a77a3feaf46f697c87064b4 -->
-A MongoDB document entity representing an OAuth 2.0 token record, storing access and refresh tokens alongside their expiry timestamps, client identity, and granted scopes.
+<!-- source-hash: 9a37fab9f7afa9f4ce60a0e74202506b -->
+MongoDB document entity representing an OAuth token stored in the `oauth_tokens` collection, scoped to a specific tenant.
 
 ## Key Components
 
 | Field | Type | Description |
-|---|---|---|
+|-------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `userId` | `String` | Reference to the owning user |
+| `tenantId` | `String` | Indexed tenant reference for multi-tenancy scoping |
+| `userId` | `String` | Associated user identifier |
 | `accessToken` | `String` | OAuth access token value |
 | `refreshToken` | `String` | OAuth refresh token value |
-| `accessTokenExpiry` | `Instant` | UTC expiry timestamp for the access token |
-| `refreshTokenExpiry` | `Instant` | UTC expiry timestamp for the refresh token |
+| `accessTokenExpiry` | `Instant` | Access token expiration timestamp |
+| `refreshTokenExpiry` | `Instant` | Refresh token expiration timestamp |
 | `clientId` | `String` | OAuth client application identifier |
-| `scopes` | `String[]` | Granted permission scopes for this token |
+| `scopes` | `String[]` | Granted permission scopes |
 
-- **Collection:** `oauth_tokens`
-- **Annotations:** `@Data` (Lombok) generates getters, setters, `equals`, `hashCode`, and `toString`
+Implements `TenantScoped` to enforce multi-tenant data isolation across the platform.
 
 ## Usage Example
 
 ```java
-// Persisting a new OAuth token
 OAuthToken token = new OAuthToken();
+token.setTenantId("tenant-abc");
 token.setUserId("user-123");
 token.setClientId("openframe-client");
 token.setAccessToken("eyJhbGciOiJSUzI1NiJ9...");
 token.setRefreshToken("dGhpcyBpcyBhIHJlZnJlc2g...");
 token.setAccessTokenExpiry(Instant.now().plusSeconds(3600));
 token.setRefreshTokenExpiry(Instant.now().plusSeconds(86400));
-token.setScopes(new String[]{"read", "write", "admin"});
+token.setScopes(new String[]{"read:tickets", "write:tickets"});
 
 mongoTemplate.save(token);
-
-// Checking token expiry
-boolean isExpired = token.getAccessTokenExpiry().isBefore(Instant.now());
 ```
 
-> **Note:** Token values should be encrypted at rest. Expiry checks should always use `Instant.now()` to ensure timezone-safe comparisons.
\ No newline at end of file
+> **Note:** The `tenantId` field is indexed for efficient per-tenant token lookups. Always ensure `tenantId` is populated before persisting to maintain proper multi-tenant isolation.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/organization/.Organization.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/organization/.Organization.md
index 2c8694154..37f419aa3 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/organization/.Organization.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/organization/.Organization.md
@@ -1,49 +1,51 @@
-<!-- source-hash: 52475e424b4fdae1c21a116da07618de -->
-MongoDB document entity representing a company or client organization within the OpenFrame platform, storing business metadata, contract details, and lifecycle status.
+<!-- source-hash: 44870293dd3202d34eff00a4adde2c28 -->
+MongoDB document entity representing a company or client organization within a tenant's scope, storing business details, contract information, and lifecycle status.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `organizationId` | `String` | Immutable UUID-based unique identifier (indexed, unique) |
-| `isDefault` | `Boolean` | Flags the tenant's default organization |
+| `id` | `String` | MongoDB document ID |
+| `tenantId` | `String` | Tenant scope identifier (indexed) |
+| `organizationId` | `String` | Immutable UUID-based unique identifier |
+| `isDefault` | `Boolean` | Marks the default organization for a tenant |
 | `status` | `OrganizationStatus` | Lifecycle state: `ACTIVE`, `ARCHIVED`, or `DELETED` |
-| `contactInformation` | `ContactInformation` | Nested contacts and address data |
-| `monthlyRevenue` | `BigDecimal` | Revenue figure in the organization's currency |
+| `contactInformation` | `ContactInformation` | Embedded contacts and addresses |
+| `monthlyRevenue` | `BigDecimal` | Revenue figure in organization's currency |
 | `contractStartDate` / `contractEndDate` | `LocalDate` | Contract validity window |
-| `createdAt` / `updatedAt` | `Instant` | Auto-managed audit timestamps via Spring Data |
 | `isContractActive()` | `boolean` | Returns `true` if today falls within the contract window |
-| `isDeleted()` | `boolean` | Soft-delete check against `OrganizationStatus.DELETED` |
-| `isArchived()` | `boolean` | Checks against `OrganizationStatus.ARCHIVED` |
+| `isDeleted()` | `boolean` | Soft-delete check |
+| `isArchived()` | `boolean` | Archive state check |
 
 ## Usage Example
 
 ```java
-// Build a new organization
 Organization org = Organization.builder()
+    .tenantId("tenant-abc")
     .organizationId(UUID.randomUUID().toString())
     .name("Acme Corp")
-    .category("IT Services")
-    .numberOfEmployees(150)
+    .category("Technology")
+    .numberOfEmployees(250)
     .websiteUrl("https://acme.example.com")
-    .monthlyRevenue(new BigDecimal("25000.00"))
+    .monthlyRevenue(new BigDecimal("15000.00"))
     .contractStartDate(LocalDate.of(2024, 1, 1))
-    .contractEndDate(LocalDate.of(2025, 1, 1))
+    .contractEndDate(LocalDate.of(2025, 12, 31))
     .isDefault(true)
     .build();
 
 // Lifecycle checks
 if (org.isContractActive()) {
-    System.out.println("Contract is currently active");
+    // Contract is currently valid
 }
 
-if (org.isArchived()) {
-    System.out.println("Organization is hidden but retained for device references");
+if (!org.isDeleted() && !org.isArchived()) {
+    // Organization is visible and active
 }
 ```
 
 ## Notes
 
-- **Soft deletes only** — `DELETED` status is preferred over physical removal to preserve references from devices that may reconnect after going offline.
-- `ARCHIVED` hides the organization from normal queries while keeping the document intact.
-- `organizationId` is treated as immutable; only `id` (MongoDB `_id`) is managed by the database engine.
\ No newline at end of file
+- Implements `TenantScoped` — all queries should be filtered by `tenantId`
+- Uses **soft deletion** (`ARCHIVED`/`DELETED`) instead of hard deletes to preserve references from devices that may come back online
+- `organizationId` is unique and **immutable** after creation; `id` is the internal MongoDB `_id`
+- Auditing fields (`createdAt`, `updatedAt`) are managed automatically via Spring Data annotations
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.Script.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.Script.md
new file mode 100644
index 000000000..3dbc4a876
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.Script.md
@@ -0,0 +1,38 @@
+<!-- source-hash: 6023f2f2eb66ae89d32679f4ce6bb863 -->
+MongoDB document entity for RMM scripts within the OpenFrame platform, representing reusable scripts executable on managed agents via ad-hoc dispatch, scheduling, or check integration.
+
+## Key Components
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tenantId` | `String` | Multi-tenant isolation key (compound-indexed with `name`) |
+| `shell` | `ScriptShell` | Interpreter type (PowerShell, CMD, Bash, Python) |
+| `scriptBody` | `String` | Raw script source stored inline |
+| `supportedPlatforms` | `List<ScriptPlatform>` | OS targets to prevent cross-platform dispatch errors |
+| `defaultTimeoutSeconds` | `Integer` | Agent-enforced execution timeout |
+| `defaultArgs` | `List<String>` | Default positional CLI arguments (`argv`) |
+| `envVars` | `List<ScriptEnvVar>` | Pre-execution environment variables (secret encryption pipeline pending) |
+| `status` | `ScriptStatus` | Lifecycle state; defaults to `ACTIVE`, uses `DELETED` for soft-delete |
+
+**Indexes:**
+- Compound unique index on `(tenantId, name)` — enforces per-tenant name uniqueness
+- Single-field index on `status` — supports filtered queries by lifecycle state
+
+## Usage Example
+
+```java
+Script script = Script.builder()
+    .tenantId("tenant-abc")
+    .name("Disk Cleanup")
+    .description("Removes temp files older than 30 days")
+    .shell(ScriptShell.POWERSHELL)
+    .scriptBody("Get-ChildItem $env:TEMP | Remove-Item -Recurse -Force")
+    .tag("maintenance")
+    .supportedPlatforms(List.of(ScriptPlatform.WINDOWS))
+    .defaultTimeoutSeconds(120)
+    .defaultArgs(List.of("--silent"))
+    .envVars(List.of(new ScriptEnvVar("LOG_LEVEL", "info", false)))
+    .build();
+```
+
+> **Note:** `description`, `tag`, `defaultArgs`, and `envVars` are optional. Category normalization (trim/lowercase) is enforced at the service layer. Large `scriptBody` values are stored inline — object storage offload is planned for a future iteration.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptEnvVar.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptEnvVar.md
new file mode 100644
index 000000000..6b6c252a0
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptEnvVar.md
@@ -0,0 +1,30 @@
+<!-- source-hash: f09f28c7ddee3b77dabd9f5ab273befc -->
+Represents a single environment variable to be exported on an RMM agent prior to script execution. This class is embedded within the `Script` document and is not stored as a standalone MongoDB collection.
+
+## Key Components
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `String` | The environment variable name as exported on the agent |
+| `value` | `String` | The variable's value; intended to hold ciphertext when `secret` is `true`, but currently stored in plaintext |
+| `secret` | `boolean` | Marks the variable as sensitive; the service layer rejects `secret = true` on write until the secret-management pipeline is implemented |
+
+## Usage Example
+
+```java
+// Plain environment variable
+ScriptEnvVar plain = ScriptEnvVar.builder()
+    .name("API_BASE_URL")
+    .value("https://api.example.com")
+    .secret(false)
+    .build();
+
+// Secret variable — currently rejected at the service layer
+ScriptEnvVar secret = ScriptEnvVar.builder()
+    .name("API_KEY")
+    .value("supersecret")
+    .secret(true)  // ⚠️ write will be rejected until secret-management lands
+    .build();
+```
+
+> **⚠️ Known Limitation:** Secret management (encryption at rest + secure agent delivery) is not yet implemented. The service layer currently rejects any `ScriptEnvVar` with `secret = true` on write, and all values are persisted to MongoDB in plaintext regardless of the `secret` flag.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptPlatform.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptPlatform.md
new file mode 100644
index 000000000..6f23394be
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptPlatform.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 83ad69c1f742c99f4d3ab7782a1b2ee9 -->
+Enum representing the supported operating-system platforms for RMM script execution targeting.
+
+## Key Components
+
+| Value | Description |
+|-------|-------------|
+| `WINDOWS` | Microsoft Windows environments |
+| `LINUX` | Linux-based operating systems |
+| `MACOS` | Apple macOS environments |
+
+## Usage Example
+
+```java
+Script script = new Script();
+script.setPlatform(ScriptPlatform.LINUX);
+
+if (script.getPlatform() == ScriptPlatform.WINDOWS) {
+    // Windows-specific execution logic
+}
+
+// Switch-based dispatch
+switch (script.getPlatform()) {
+    case WINDOWS -> executeOnWindows(script);
+    case LINUX   -> executeOnLinux(script);
+    case MACOS   -> executeOnMacOS(script);
+}
+```
+
+> **Note:** Platform granularity is intentionally coarse. Version-specific behavior (e.g. Ubuntu vs. Debian, Windows 10 vs. Server 2022) should be handled within the script body or via runtime arguments rather than by adding new enum values.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptShell.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptShell.md
new file mode 100644
index 000000000..ddeaae58d
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptShell.md
@@ -0,0 +1,25 @@
+<!-- source-hash: 453b34955c60211d24ff452d1f89358c -->
+Enum defining the supported shell interpreters available for executing scripts via the RMM agent.
+
+## Key Components
+
+| Value | Description |
+|-------|-------------|
+| `POWERSHELL` | Windows PowerShell interpreter |
+| `CMD` | Windows Command Prompt |
+| `BASH` | Unix/Linux Bash shell |
+| `PYTHON` | Python interpreter |
+| `NUSHELL` | Nu shell interpreter |
+| `SHELL` | Generic POSIX shell |
+
+## Usage Example
+
+```java
+Script script = new Script();
+script.setShell(ScriptShell.POWERSHELL);
+script.setContent("Get-Process | Select-Object Name, CPU");
+```
+
+## Notes
+
+The enum values intentionally mirror the shell options exposed by Tactical RMM, allowing existing scripts to be migrated to OpenFrame without modifying their shebangs or interpreter declarations. Additional interpreters may be added as agent-side support expands.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptStatus.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptStatus.md
new file mode 100644
index 000000000..c13b35224
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/.ScriptStatus.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 6be201ca7af77c7ccc198f562f3bee53 -->
+Enum defining the three lifecycle states for a `Script` document in the RMM (Remote Monitoring & Management) data model, supporting soft-delete semantics.
+
+## Key Components
+
+| Value | Description |
+|-------|-------------|
+| `ACTIVE` | Script is live and accessible via standard API surfaces |
+| `ARCHIVED` | Script is inactive but retained for reference |
+| `DELETED` | Soft-deleted; hidden from API but retained in MongoDB for historical execution record integrity |
+
+## Usage Example
+
+```java
+Script script = scriptRepository.findById(id);
+
+if (script.getStatus() == ScriptStatus.DELETED) {
+    throw new ResourceNotFoundException("Script not found");
+}
+
+// Soft-delete a script
+script.setStatus(ScriptStatus.DELETED);
+scriptRepository.save(script);
+```
+
+## Important Notes
+
+- **Soft-delete behavior:** `DELETED` documents remain in MongoDB so historic execution records continue to reference a valid parent script.
+- **Name reservation:** The compound unique index on `(tenantId, name)` includes `DELETED` documents — a soft-deleted script name stays **occupied**. Hard-deletion via admin tooling is required to free the name for reuse.
+- **Pattern consistency:** Mirrors the `OrganizationStatus` enum pattern used elsewhere in the OpenFrame data model.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/filter/.ScriptQueryFilter.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/filter/.ScriptQueryFilter.md
new file mode 100644
index 000000000..f0755a237
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/rmm/filter/.ScriptQueryFilter.md
@@ -0,0 +1,27 @@
+<!-- source-hash: d15f3eef0ab78e8c0dac271eec56d6ed -->
+Data-layer filter criteria for querying `Script` entities, providing a repository-friendly alternative to the API-layer `ScriptFilterInput` to maintain module independence.
+
+## Key Components
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `shells` | `List<ScriptShell>` | Filter by one or more script shell types |
+| `statuses` | `List<ScriptStatus>` | Filter by one or more script statuses |
+| `supportedPlatforms` | `List<ScriptPlatform>` | Filter by supported platforms |
+| `tag` | `String` | Filter by a specific tag |
+
+## Usage Example
+
+```java
+// Build a filter for active PowerShell scripts targeting Windows
+ScriptQueryFilter filter = ScriptQueryFilter.builder()
+        .shells(List.of(ScriptShell.POWERSHELL))
+        .statuses(List.of(ScriptStatus.ACTIVE))
+        .supportedPlatforms(List.of(ScriptPlatform.WINDOWS))
+        .tag("patch-management")
+        .build();
+
+List<Script> scripts = scriptRepository.findAll(filter);
+```
+
+> **Note:** The service layer is responsible for mapping between `ScriptFilterInput` (API module) and `ScriptQueryFilter` (data module), following the `OrganizationQueryFilter` pattern.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/sso/.SSOConfig.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/sso/.SSOConfig.md
index 05724321f..1d047a39b 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/sso/.SSOConfig.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/sso/.SSOConfig.md
@@ -1,38 +1,33 @@
-<!-- source-hash: e57e86bcc7be70e2aa940746f02cf123 -->
-MongoDB document model for storing Single Sign-On (SSO) provider configurations, mapped to the `sso_configs` collection.
+<!-- source-hash: 202e5fac447c214b8068a07f4d13f142 -->
+MongoDB document entity representing a tenant-scoped SSO (Single Sign-On) configuration, storing provider credentials and provisioning rules for a given tenant.
 
 ## Key Components
 
 | Field | Type | Description |
-|-------|------|-------------|
+|---|---|---|
 | `id` | `String` | MongoDB document ID (`@Id`) |
-| `provider` | `String` | SSO provider identifier (e.g., `google`, `microsoft`) |
-| `clientId` | `String` | OAuth2/OIDC client ID |
-| `clientSecret` | `String` | OAuth2/OIDC client secret |
-| `enabled` | `boolean` | Toggles this SSO configuration on/off |
-| `autoProvisionUsers` | `boolean` | Whether new users are auto-created on first SSO login |
-| `msTenantId` | `String` | Microsoft Entra tenant ID for Office 365 OIDC (optional) |
-| `allowedDomains` | `List<String>` | Email domain whitelist for auto-provisioning; allows all domains if empty or null |
+| `tenantId` | `String` | Indexed tenant identifier (implements `TenantScoped`) |
+| `provider` | `String` | SSO provider name (e.g., `microsoft`, `google`) |
+| `clientId` / `clientSecret` | `String` | OAuth2/OIDC application credentials |
+| `enabled` | `boolean` | Toggles SSO provider for the tenant |
+| `autoProvisionUsers` | `boolean` | Allows auto-creation of new users on first SSO login |
+| `msTenantId` | `String` | Microsoft Entra tenant ID for Office 365 OIDC |
+| `allowedDomains` | `List<String>` | Email domain whitelist for auto-provisioning; unrestricted if empty/null |
 
 ## Usage Example
 
 ```java
-// Create and persist a Microsoft SSO configuration
 SSOConfig config = new SSOConfig();
+config.setTenantId("tenant-abc");
 config.setProvider("microsoft");
-config.setClientId("your-client-id");
-config.setClientSecret("your-client-secret");
+config.setClientId("app-client-id");
+config.setClientSecret("app-client-secret");
+config.setMsTenantId("ms-entra-tenant-id");
 config.setEnabled(true);
 config.setAutoProvisionUsers(true);
-config.setMsTenantId("your-tenant-id");
-config.setAllowedDomains(List.of("flamingo.run", "openframe.ai"));
+config.setAllowedDomains(List.of("acmecorp.com", "acmecorp.io"));
 
-mongoTemplate.save(config); // persists to "sso_configs" collection
+ssoConfigRepository.save(config);
 ```
 
-## Notes
-
-- `autoProvisionUsers: false` restricts SSO login to pre-existing users only — useful for tightly controlled environments.
-- `allowedDomains` acts as a guard for auto-provisioning; leave empty to allow any verified email domain.
-- `msTenantId` is optional — omit to use Microsoft's common (`/common`) endpoint, which supports multi-tenant scenarios.
-- Uses Lombok `@Data` for automatic generation of getters, setters, `equals`, `hashCode`, and `toString`.
\ No newline at end of file
+> **Note:** When `autoProvisionUsers` is `false`, only users already present in the system can authenticate via the configured provider. The `allowedDomains` restriction only applies when auto-provisioning is enabled.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.Tag.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.Tag.md
index ee0c6f495..66826863d 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.Tag.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.Tag.md
@@ -1,41 +1,38 @@
-<!-- source-hash: 1ead17ae9b2254551b37930f153211be -->
-MongoDB document entity representing a tag definition used to categorize and label entities within a tenant's OpenFrame environment.
+<!-- source-hash: 85952e76486579d5e9ce93853eb824e3 -->
+MongoDB document entity representing a tenant-scoped tag definition, used to categorize and label entities within the OpenFrame platform.
 
 ## Key Components
 
-| Component | Type | Description |
-|---|---|---|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `key` | `String` | Unique tag identifier per entity type (e.g., `"site"`, `"org_type"`) |
-| `description` | `String` | Human-readable description of the tag |
-| `color` | `String` | Optional display color for UI rendering |
+| Member | Type | Description |
+|--------|------|-------------|
+| `id` | `String` | MongoDB document `_id` |
+| `tenantId` | `String` | Tenant isolation identifier (from `TenantScoped`) |
+| `key` | `String` | Tag key identifier (e.g., `"site"`, `"org_type"`) |
+| `description` | `String` | Human-readable tag description |
+| `color` | `String` | Optional display color |
 | `values` | `List<String>` | Predefined allowed values; `null` = free-text, non-empty = dropdown |
 | `entityType` | `TagEntityType` | The entity type this tag applies to |
-| `createdAt` | `Instant` | Timestamp of tag creation |
-| `createdBy` | `String` | Identifier of the user who created the tag |
+| `createdAt` | `Instant` | Creation timestamp |
+| `createdBy` | `String` | Creator reference |
 
-### Compound Index
+**Compound Index:** `tenant_key_entity_idx` enforces uniqueness of `(tenantId, key, entityType)` — a tag key is unique per entity type within a tenant.
 
-A unique compound index (`key_entity_idx`) is enforced on `key` + `entityType`, ensuring tag keys are unique per entity type across the tenant.
-
-### `values` Field Behavior
-
-| State | UI Behavior |
-|---|---|
-| `null` | Free-text input or simple label |
-| Empty `List` | Values explicitly cleared |
-| Non-empty `List` | Renders as dropdown or checkbox selection |
+**`values` field behavior:**
+- `null` → simple label or free-text input
+- `[]` (empty list) → values explicitly cleared
+- `["A", "B"]` → renders as dropdown/checkbox selector in UI
 
 ## Usage Example
 
 ```java
 Tag siteTag = Tag.builder()
+    .tenantId("tenant-123")
     .key("site")
     .description("Physical site location")
     .color("#FFC008")
-    .values(List.of("CHICAGO", "DALLAS", "SCHOOL1"))
+    .values(List.of("CHICAGO", "NEW_YORK", "DALLAS"))
     .entityType(TagEntityType.DEVICE)
     .createdAt(Instant.now())
-    .createdBy("user-123")
+    .createdBy("user-456")
     .build();
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.TagAssignment.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.TagAssignment.md
index 134c82383..9246c2ee7 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.TagAssignment.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/.TagAssignment.md
@@ -1,42 +1,35 @@
-<!-- source-hash: f80b9fdf2b2608a0d8d85f3e585709d2 -->
-MongoDB document entity representing the assignment of a tag to a specific entity (device, ticket, etc.), stored in the `tag_assignments` collection with a unique compound index enforcing one assignment per entity-tag-type combination.
+<!-- source-hash: 246f20ce4ee0d603283ed5f007aca848 -->
+MongoDB document entity representing the assignment of a tag to a specific entity within a tenant, stored in the `tag_assignments` collection.
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | `String` | MongoDB document `_id` |
-| `entityId` | `String` | ID of the tagged entity |
-| `tagId` | `String` | Reference to the associated `Tag` document |
-| `entityType` | `TagEntityType` | Enum discriminating the entity kind (e.g., device, ticket) |
+| `id` | `String` | MongoDB document identifier (`@Id`) |
+| `tenantId` | `String` | Tenant scope identifier (via `TenantScoped`) |
+| `entityId` | `String` | ID of the entity receiving the tag |
+| `tagId` | `String` | Reference to the assigned tag |
+| `entityType` | `TagEntityType` | Enum classifying the entity (e.g., device, site) |
 | `values` | `List<String>` | Per-entity values for key-value tags; empty for label-only tags |
-| `taggedAt` | `Instant` | Timestamp of when the tag was assigned |
+| `taggedAt` | `Instant` | Timestamp of assignment |
 | `taggedBy` | `String` | User or system that performed the assignment |
 
-**Compound Index:** `entity_tag_idx` on `(entityId, tagId, entityType)` — enforces uniqueness so the same tag cannot be assigned twice to the same entity.
+A **unique compound index** (`tenant_entity_tag_idx`) enforces that the combination of `tenantId`, `entityId`, `tagId`, and `entityType` is unique, preventing duplicate tag assignments.
 
 ## Usage Example
 
 ```java
-// Assign a key-value tag to a device
 TagAssignment assignment = TagAssignment.builder()
-        .entityId("device-abc-123")
-        .tagId("tag-site-456")
-        .entityType(TagEntityType.DEVICE)
-        .values(List.of("site1", "site2"))
-        .taggedAt(Instant.now())
-        .taggedBy("technician-user-id")
-        .build();
+    .tenantId("tenant-001")
+    .entityId("device-abc")
+    .tagId("tag-site")
+    .entityType(TagEntityType.DEVICE)
+    .values(List.of("site1", "site2"))
+    .taggedAt(Instant.now())
+    .taggedBy("admin-user")
+    .build();
 
-mongoTemplate.save(assignment);
+tagAssignmentRepository.save(assignment);
+```
 
-// Assign a simple label tag (no values)
-TagAssignment labelAssignment = TagAssignment.builder()
-        .entityId("ticket-789")
-        .tagId("tag-urgent-001")
-        .entityType(TagEntityType.TICKET)
-        .values(List.of())
-        .taggedAt(Instant.now())
-        .taggedBy("mingo-ai")
-        .build();
-```
\ No newline at end of file
+> For simple label tags (no associated values), set `values` to an empty list or omit it via the builder — the field defaults to an empty `List<String>`.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.SSOPerTenantConfig.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.SSOPerTenantConfig.md
index c8e8696cf..3d59d4a91 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.SSOPerTenantConfig.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.SSOPerTenantConfig.md
@@ -1,33 +1,29 @@
-<!-- source-hash: 38218a062546cada63d8806dee92faf3 -->
-Tenant-specific SSO configuration document that extends `SSOConfig` with tenant linkage and audit timestamps for MongoDB persistence.
+<!-- source-hash: 2b245484e86918681d48151e026a2996 -->
+Extends `SSOConfig` to provide a tenant-scoped SSO configuration document with automatic audit timestamps managed by Spring Data.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `tenantId` | `String` | Uniquely indexed tenant identifier (sparse index) |
 | `createdAt` | `LocalDateTime` | Auto-populated on document creation via `@CreatedDate` |
 | `updatedAt` | `LocalDateTime` | Auto-updated on every save via `@LastModifiedDate` |
 
-Inherits from `SSOConfig`: provider type, client credentials, and enabled flag.
+Inherits from `SSOConfig`: provider, client credentials, and enabled flag.
 
 ## Usage Example
 
 ```java
-// Create a new SSO config for a tenant
+// Build a tenant SSO config (inherits SSOConfig fields)
 SSOPerTenantConfig config = new SSOPerTenantConfig();
-config.setTenantId("tenant-abc-123");
-config.setProvider("OKTA");
-config.setClientId("okta-client-id");
-config.setClientSecret("okta-client-secret");
+config.setProvider("okta");
+config.setClientId("tenant-client-id");
+config.setClientSecret("tenant-client-secret");
 config.setEnabled(true);
+// createdAt / updatedAt are managed automatically by Spring Data auditing
 
-// Persist via repository — createdAt/updatedAt are managed automatically
-ssoPerTenantConfigRepository.save(config);
-
-// Lookup by tenant
-Optional<SSOPerTenantConfig> found = ssoPerTenantConfigRepository
-    .findByTenantId("tenant-abc-123");
+// Embed within a Tenant document
+tenant.setSsoConfig(config);
+tenantRepository.save(tenant);
 ```
 
-> **Note:** The `tenantId` field uses a sparse unique index, meaning only documents where `tenantId` is present are indexed — allowing multiple documents without a `tenantId` to coexist in MongoDB without constraint violations.
\ No newline at end of file
+> Spring Data auditing must be enabled (e.g. `@EnableMongoAuditing`) for `createdAt` and `updatedAt` to populate automatically.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.TenantKey.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.TenantKey.md
index bba80656a..4f3817f83 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.TenantKey.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tenant/.TenantKey.md
@@ -1,40 +1,37 @@
-<!-- source-hash: 51c542cec190e6942d9244fcbed9ec3d -->
-MongoDB document entity representing a cryptographic key pair associated with a specific tenant, stored in the `tenant_keys` collection.
+<!-- source-hash: ee34812074e3055834e54024030700a3 -->
+A MongoDB document entity representing a cryptographic key pair scoped to a specific tenant, stored in the `tenant_keys` collection.
 
 ## Key Components
 
 | Field | Type | Description |
-|-------|------|-------------|
+|---|---|---|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `tenantId` | `String` | Reference to the owning tenant |
-| `keyId` | `String` | Unique identifier for this key pair |
+| `tenantId` | `String` | Indexed reference to the owning tenant |
+| `keyId` | `String` | Logical identifier for the key pair |
 | `publicPem` | `String` | PEM-encoded public key |
-| `privateEncrypted` | `String` | Encrypted private key (stored securely) |
-| `active` | `boolean` | Whether this key is currently in use |
-| `createdAt` | `Instant` | Auto-populated timestamp on creation |
-| `rotatedAt` | `Instant` | Auto-updated timestamp on modification (tracks key rotation) |
+| `privateEncrypted` | `String` | Encrypted private key material |
+| `active` | `boolean` | Indicates if this key is currently in use |
+| `createdAt` | `Instant` | Auto-populated creation timestamp |
+| `rotatedAt` | `Instant` | Auto-updated timestamp on key rotation |
+
+Implements `TenantScoped` to enforce multi-tenancy isolation across the platform.
 
 ## Usage Example
 
 ```java
-// Creating a new tenant key
-TenantKey tenantKey = new TenantKey();
-tenantKey.setTenantId("tenant-abc123");
-tenantKey.setKeyId("key-xyz789");
-tenantKey.setPublicPem("-----BEGIN PUBLIC KEY-----\n...");
-tenantKey.setPrivateEncrypted("enc:base64encodedEncryptedPrivateKey==");
-tenantKey.setActive(true);
+// Creating and persisting a new tenant key
+TenantKey key = new TenantKey();
+key.setTenantId("tenant-abc123");
+key.setKeyId("signing-key-v1");
+key.setPublicPem("-----BEGIN PUBLIC KEY-----\n...");
+key.setPrivateEncrypted("enc::AES256:...");
+key.setActive(true);
 
-// Persisting via Spring Data MongoDB repository
-tenantKeyRepository.save(tenantKey);
+tenantKeyRepository.save(key);
 
 // Querying active keys for a tenant
 List<TenantKey> activeKeys = tenantKeyRepository
     .findByTenantIdAndActiveTrue("tenant-abc123");
 ```
 
-## Notes
-
-- Private keys are **never stored in plaintext** — `privateEncrypted` should always contain an encrypted payload.
-- `rotatedAt` serves as a key rotation audit trail, automatically updated by Spring Data's `@LastModifiedDate`.
-- Only one key should typically be `active = true` per tenant at a time to avoid authentication conflicts.
\ No newline at end of file
+> **Security Note:** The `privateEncrypted` field should never be stored or transmitted in plaintext. Always apply tenant-specific encryption before persisting and decrypt only in trusted service boundaries.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TempAttachment.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TempAttachment.md
index 6aa5cac52..7e9d26092 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TempAttachment.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TempAttachment.md
@@ -1,48 +1,48 @@
-<!-- source-hash: 6bfd562f47ac16597e260202f5d4ef6c -->
-MongoDB document entity representing a temporary file attachment uploaded before ticket creation, implementing the "Temp Upload Pattern" used by platforms like Gmail and Slack.
+<!-- source-hash: 264a1d8e2d5dadffd20074e411e5bc40 -->
+Represents a temporary file attachment uploaded before a ticket is created, following the "Temp Upload Pattern" used by platforms like Gmail, Slack, and GitHub.
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
+| `id` | `String` | MongoDB document ID |
+| `tenantId` | `String` | Tenant identifier (indexed, implements `TenantScoped`) |
 | `fileName` | `String` | Original name of the uploaded file |
 | `contentType` | `String` | MIME type of the file |
 | `fileSize` | `Long` | Size of the file in bytes |
 | `storagePath` | `String` | S3 key in format `temp/{tempId}/{fileName}` |
 | `uploadedBy` | `String` | ID of the user who initiated the upload |
-| `createdAt` | `Instant` | Auto-populated timestamp, indexed for cleanup queries |
+| `createdAt` | `Instant` | Auto-set creation timestamp used for orphan cleanup |
 
-## Lifecycle Flow
+## Upload Lifecycle
 
 ```mermaid
 graph TD
-    A["User Uploads File"] --> B["createTempAttachmentUploadUrl"]
-    B --> C["TempAttachment Created\nstored in temp_attachments"]
-    C --> D{"Ticket Saved?"}
-    D -->|Yes| E["Move S3 file\ntemp/ → attachments/ticketId/"]
-    E --> F["Delete TempAttachment\nCreate TicketAttachment"]
-    D -->|No - older than 24h| G["Cleanup Job\nruns every 6 hours"]
-    G --> H["Delete Orphaned Files\nfrom S3 + MongoDB"]
+    A["User uploads file"] --> B["createTempAttachmentUploadUrl"]
+    B --> C["TempAttachment created in temp/"]
+    C --> D{"Ticket saved?"}
+    D -->|"Yes"| E["File moved to attachments/{ticketId}/"]
+    E --> F["TempAttachment deleted"]
+    F --> G["TicketAttachment created"]
+    D -->|"No - older than 24h"| H["Cleanup job removes orphaned file"]
 ```
 
 ## Usage Example
 
 ```java
-// Step 1: Create temp attachment on upload initiation
-TempAttachment tempAttachment = TempAttachment.builder()
-    .fileName("network-diagram.png")
+TempAttachment temp = TempAttachment.builder()
+    .tenantId("tenant-123")
+    .fileName("screenshot.png")
     .contentType("image/png")
     .fileSize(204800L)
-    .storagePath("temp/abc123/network-diagram.png")
+    .storagePath("temp/abc-uuid/screenshot.png")
     .uploadedBy("user-456")
     .build();
 
-tempAttachmentRepository.save(tempAttachment);
-
-// Step 2: Query orphaned attachments for cleanup
-Instant cutoff = Instant.now().minus(24, ChronoUnit.HOURS);
-List<TempAttachment> orphaned = repository.findByCreatedAtBefore(cutoff);
+tempAttachmentRepository.save(temp);
 ```
 
-> **Note:** The `createdAt` field is indexed to optimize the cleanup job query that runs every 6 hours, identifying orphaned uploads older than 24 hours.
\ No newline at end of file
+## Notes
+
+- Stored in MongoDB collection `temp_attachments`
+- A scheduled cleanup job runs every **6 hours**, deleting any `TempAttachment` with a `createdAt` older than **24 hours**, preventing orphaned S3 objects from accumulating
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.Ticket.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.Ticket.md
index 6234f1780..58896107d 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.Ticket.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.Ticket.md
@@ -1,49 +1,41 @@
-<!-- source-hash: 167467afd971cddd0dd42a7d825f3be8 -->
-MongoDB document entity representing a PSA/ticketing system ticket, storing all ticket metadata including status, ownership, device association, and organizational context.
+<!-- source-hash: 824f699cbd80f4aeab0c9ae5e02c926e -->
+MongoDB document entity representing a support ticket in the OpenFrame PSA/ticketing system. It stores all ticket metadata including status lifecycle, ownership, device/organization associations, and timestamps.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | MongoDB document ID (`@Id`) |
-| `ticketNumber` | `Integer` | Auto-incremented, tenant-unique human-readable number |
-| `title` / `description` | `String` | Ticket summary and rich-text HTML body |
-| `status` | `TicketStatus` | Indexed ticket lifecycle state |
-| `creationSource` | `TicketCreationSource` | Origin of ticket (e.g., manual, AI, email) |
+| Element | Type | Description |
+|---|---|---|
+| `Ticket` | `@Document` | Root entity mapped to the `tickets` MongoDB collection |
+| `tenantId` / `ticketNumber` | Fields | Compound unique index ensures ticket numbers are scoped per tenant |
+| `status` | `TicketStatus` | **Legacy** — being replaced by `statusId` + `statusKind` |
+| `statusKind` | `TicketStatusKind` | New lifecycle-aware status classification |
+| `statusId` | `String` | Reference to a named status definition |
 | `owner` | `TicketOwner` | Embedded ownership metadata |
-| `deviceId` / `deviceHostname` | `String` | Associated machine |
-| `organizationId` / `organizationName` | `String` | Client organization context |
-| `assignedTo` / `assignedName` | `String` | Assigned technician reference |
-| `order` | `String` | Indexed sort/ordering field |
-| `createdAt` / `updatedAt` / `resolvedAt` | `Instant` | Lifecycle timestamps |
+| `creationSource` | `TicketCreationSource` | Origin of the ticket (e.g., manual, AI, client portal) |
+| `isAiDisabled()` | Method | Returns `true` when the ticket status does not permit AI assistance |
+| `TenantScoped` | Interface | Enforces multi-tenant data isolation |
 
-**Compound Indexes:**
-
-```text
-status_created       → { status: 1, createdAt: -1 }
-assignee_status      → { assignedTo: 1, status: 1 }
-organization_status  → { organizationId: 1, status: 1 }
-device_status        → { deviceId: 1, status: 1 }
-```
-
-> Tags are managed via a shared `TagAssignment` collection. Attachments live in the `TicketAttachment` collection — not embedded here.
+> **Migration note:** The legacy `status` field and its compound indexes (`status_order`, `status_kind`) are pending removal once all reads/writes migrate to `statusKind`/`statusId`.
 
 ## Usage Example
 
 ```java
 Ticket ticket = Ticket.builder()
+    .tenantId("tenant-abc")
     .ticketNumber(1042)
-    .title("VPN not connecting after Windows update")
-    .description("<p>User reports VPN fails post-KB5034441 patch.</p>")
-    .status(TicketStatus.OPEN)
-    .creationSource(TicketCreationSource.MANUAL)
-    .deviceId("dev-abc123")
-    .deviceHostname("ws-john-doe")
+    .title("Printer offline - Floor 3")
+    .description("HP LaserJet not responding since 09:00.")
+    .statusKind(TicketStatusKind.AI_ASSISTANCE)
+    .statusId("status-open-id")
     .organizationId("org-xyz")
     .organizationName("Acme Corp")
-    .assignedTo("user-789")
+    .assignedTo("tech-user-id")
     .assignedName("Jane Smith")
+    .creationSource(TicketCreationSource.CLIENT_PORTAL)
     .build();
 
-ticketRepository.save(ticket);
+// Check if Mingo AI can assist on this ticket
+if (!ticket.isAiDisabled()) {
+    mingoService.triggerAssistance(ticket);
+}
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketAttachment.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketAttachment.md
index c4e61a78e..e3d3568c6 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketAttachment.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketAttachment.md
@@ -1,37 +1,36 @@
-<!-- source-hash: ca54f30fbf0e1ee02543ebf7a2705d13 -->
-MongoDB document entity representing file attachment metadata linked to a support ticket. Files are stored externally (S3/MinIO) while this document captures storage references and upload details in the `ticket_attachments` collection.
+<!-- source-hash: a641da47ac7ce4812bd02c82a5d7e42c -->
+MongoDB document entity that stores file attachment metadata for tickets, with the actual file content held in external object storage (S3/MinIO).
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
+| `tenantId` | `String` | Tenant scope index for multi-tenancy isolation |
 | `ticketId` | `String` | Indexed reference to the parent ticket |
 | `fileName` | `String` | Original file name |
-| `contentType` | `String` | MIME type of the file |
+| `contentType` | `String` | MIME type of the uploaded file |
 | `fileSize` | `Long` | File size in bytes |
-| `storagePath` | `String` | External storage key (S3/MinIO path) |
-| `uploadedAt` | `Instant` | Auto-populated creation timestamp (`@CreatedDate`) |
+| `storagePath` | `String` | S3 key or MinIO path to retrieve the actual file |
+| `uploadedAt` | `Instant` | Auto-populated timestamp via `@CreatedDate` |
 | `uploadedBy` | `String` | Identifier of the user who uploaded the file |
 
+Implements `TenantScoped` to enforce tenant isolation across all queries.
+
 ## Usage Example
 
 ```java
-// Build and persist a new attachment record after uploading to MinIO
 TicketAttachment attachment = TicketAttachment.builder()
-    .ticketId("ticket-abc123")
+    .tenantId("tenant-abc")
+    .ticketId("ticket-001")
     .fileName("network-diagram.png")
     .contentType("image/png")
     .fileSize(204800L)
-    .storagePath("attachments/2024/01/ticket-abc123/network-diagram.png")
-    .uploadedBy("tech-user-42")
+    .storagePath("tenants/tenant-abc/tickets/ticket-001/network-diagram.png")
+    .uploadedBy("user-xyz")
     .build();
 
 ticketAttachmentRepository.save(attachment);
-
-// Query all attachments for a ticket
-List<TicketAttachment> attachments = ticketAttachmentRepository
-    .findByTicketId("ticket-abc123");
 ```
 
-> **Note:** This entity stores only metadata. The actual file retrieval requires a presigned URL or direct access to the external storage using `storagePath` as the object key.
\ No newline at end of file
+> **Note:** `storagePath` is a reference key only — file retrieval requires a separate call to your configured S3/MinIO client using this path.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketNote.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketNote.md
index d3f679566..ceaf11258 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketNote.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketNote.md
@@ -1,35 +1,37 @@
-<!-- source-hash: 296c0361b24cb936171011dc1fa8fba0 -->
-Represents an internal technician note attached to a support ticket, stored as a MongoDB document separate from client-facing messages or dialog threads.
+<!-- source-hash: 58bd1a45f16827101b70112e0bf669d5 -->
+Represents a MongoDB document for internal technician notes on a support ticket, stored in the `ticket_notes` collection. Notes are separate from ticket dialog/messages and support plain text or markdown content.
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
+| `id` | `String` | MongoDB document identifier |
+| `tenantId` | `String` | Tenant scope identifier (indexed) |
 | `ticketId` | `String` | Reference to the parent ticket (indexed) |
-| `content` | `String` | Note body — plain text or Markdown |
-| `authorId` | `String` | User ID of the technician who wrote the note; display name resolved via DataLoader |
-| `createdAt` | `Instant` | Auto-populated creation timestamp (`@CreatedDate`) |
-| `updatedAt` | `Instant` | Auto-populated last-modified timestamp (`@LastModifiedDate`) |
+| `content` | `String` | Note body — plain text or markdown |
+| `authorId` | `String` | User ID of the technician; name resolved via DataLoader |
+| `createdAt` | `Instant` | Auto-set on creation (`@CreatedDate`) |
+| `updatedAt` | `Instant` | Auto-set on modification (`@LastModifiedDate`) |
 
-**Collection:** `ticket_notes`
-**Index:** Compound index on `{ ticketId: 1, createdAt: -1 }` for efficient chronological retrieval per ticket.
+**Indexes:**
+- Compound index on `(ticketId ASC, createdAt DESC)` for efficient chronological note retrieval per ticket
+- Single-field indexes on `tenantId` and `ticketId`
 
 ## Usage Example
 
 ```java
-// Create a new internal note for a ticket
 TicketNote note = TicketNote.builder()
-    .ticketId("ticket-abc123")
-    .authorId("tech-user-456")
-    .content("Checked device logs — confirmed network adapter failure. Ordered replacement part.")
+    .tenantId("tenant-123")
+    .ticketId("ticket-456")
+    .authorId("user-789")
+    .content("Checked device logs — issue stems from a misconfigured DNS entry.")
     .build();
 
 ticketNoteRepository.save(note);
 
-// Fetch all notes for a ticket ordered by creation date (descending)
+// Fetch notes for a ticket (resolved via compound index)
 List<TicketNote> notes = ticketNoteRepository
-    .findByTicketIdOrderByCreatedAtDesc("ticket-abc123");
+    .findByTicketIdOrderByCreatedAtDesc("ticket-456");
 ```
 
-> **Note:** `authorId` stores only the technician's User ID. The display name and avatar shown in the UI are resolved at query time using a DataLoader to avoid denormalized data. Notes support edit and delete operations via `updatedAt` tracking.
\ No newline at end of file
+> Notes support edit and delete operations. The author's display name and avatar are not stored directly — they are resolved at query time via a DataLoader using `authorId`.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatus.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatus.md
index 09f51ed7f..401ec970f 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatus.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatus.md
@@ -1,33 +1,33 @@
-<!-- source-hash: b7ecc3da01fee9e7da9ee11d5950930f -->
-Enum defining the lifecycle states of a support ticket in the OpenFrame platform, with enforced transition rules that mirror the Figma-designed ticket flow.
+<!-- source-hash: 048e7373f78829118b57d3244ca9ea82 -->
+Enum representing the lifecycle states of a ticket in the OpenFrame platform, modeling valid status transitions aligned with the Figma flow design. Kept separate from `DialogStatus` for feature flag isolation.
 
 ## Key Components
 
-| Member | Type | Description |
-|--------|------|-------------|
-| `ACTIVE` | State | Ticket is open and being handled |
-| `TECH_REQUIRED` | State | Ticket requires technician intervention |
-| `ON_HOLD` | State | Ticket is paused pending action |
-| `RESOLVED` | State | Ticket has been closed/resolved |
-| `ARCHIVED` | State | Ticket is permanently archived |
-| `canTransitionTo(TicketStatus)` | Method | Returns `true` if transitioning to the target state is permitted |
-| `getAllowedTransitions()` | Method | Returns the set of valid next states from the current state |
+| Member | Description |
+|--------|-------------|
+| `ACTIVE` | Ticket is open and being worked on |
+| `TECH_REQUIRED` | Ticket needs technician assignment |
+| `ON_HOLD` | Ticket is paused |
+| `RESOLVED` | Ticket has been closed/resolved |
+| `ARCHIVED` | Ticket is archived after resolution |
+| `canTransitionTo(TicketStatus)` | Returns `true` if the transition from current to target state is permitted |
+| `getAllowedTransitions()` | Returns the `Set` of valid next states for each status |
 
-## Transition Map
+## Transition Graph
 
 ```mermaid
 graph TD
-    ACTIVE["ACTIVE"] --> TECH_REQUIRED["TECH_REQUIRED"]
-    ACTIVE --> ON_HOLD["ON_HOLD"]
-    ACTIVE --> RESOLVED["RESOLVED"]
-    TECH_REQUIRED --> ACTIVE
-    TECH_REQUIRED --> ON_HOLD
-    TECH_REQUIRED --> RESOLVED
-    ON_HOLD --> ACTIVE
-    ON_HOLD --> TECH_REQUIRED
-    ON_HOLD --> RESOLVED
-    RESOLVED --> ARCHIVED["ARCHIVED"]
-    ARCHIVED --> RESOLVED
+    ACTIVE["ACTIVE"] -->|"allowed"| TECH_REQUIRED["TECH_REQUIRED"]
+    ACTIVE -->|"allowed"| ON_HOLD["ON_HOLD"]
+    ACTIVE -->|"allowed"| RESOLVED["RESOLVED"]
+    TECH_REQUIRED -->|"allowed"| ACTIVE
+    TECH_REQUIRED -->|"allowed"| ON_HOLD
+    TECH_REQUIRED -->|"allowed"| RESOLVED
+    ON_HOLD -->|"allowed"| ACTIVE
+    ON_HOLD -->|"allowed"| TECH_REQUIRED
+    ON_HOLD -->|"allowed"| RESOLVED
+    RESOLVED -->|"allowed"| ARCHIVED["ARCHIVED"]
+    ARCHIVED -->|"allowed"| RESOLVED
 ```
 
 ## Usage Example
@@ -35,19 +35,14 @@ graph TD
 ```java
 TicketStatus current = TicketStatus.ACTIVE;
 
-// Check if a transition is valid before applying it
-if (current.canTransitionTo(TicketStatus.RESOLVED)) {
-    ticket.setStatus(TicketStatus.RESOLVED);
+// Check if a specific transition is valid
+if (current.canTransitionTo(TicketStatus.ON_HOLD)) {
+    ticket.setStatus(TicketStatus.ON_HOLD);
 }
 
 // Inspect all valid next states
 Set<TicketStatus> next = current.getAllowedTransitions();
 // → [TECH_REQUIRED, ON_HOLD, RESOLVED]
-
-// Guard against invalid transitions
-if (!current.canTransitionTo(TicketStatus.ARCHIVED)) {
-    throw new IllegalStateException("Cannot archive an active ticket directly.");
-}
 ```
 
-> **Note:** `TicketStatus` is intentionally separate from `DialogStatus` to allow independent feature flag control over ticket lifecycle behavior.
\ No newline at end of file
+> **Note:** This enum is marked for removal (`TODO: lifecycle-rollout`) once the legacy `status` field is dropped from the `Ticket` document model.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusDefinition.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusDefinition.md
new file mode 100644
index 000000000..1aacaf1cd
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusDefinition.md
@@ -0,0 +1,37 @@
+<!-- source-hash: 281ffd8f252398b4b6a8a4be81f6540d -->
+MongoDB document entity representing a tenant-scoped ticket status definition, stored in the `ticket_statuses` collection with a compound unique index enforcing one entry per tenant per status kind.
+
+## Key Components
+
+| Member | Type | Description |
+|---|---|---|
+| `id` | `String` | MongoDB document identifier (`@Id`) |
+| `tenantId` | `String` | Tenant isolation field (via `TenantScoped`) |
+| `kind` | `TicketStatusKind` | Enum classifying the status (e.g., `AI_ASSISTANCE`, `TECH_REQUIRED`, `RESOLVED`, `ARCHIVED`) |
+| `name` | `String` | Display label for the status |
+| `color` | `String` | UI color value associated with the status |
+| `position` | `String` | Ordering/sort position in the status list |
+| `createdAt` / `updatedAt` | `Instant` | Auto-managed audit timestamps |
+
+**Compound Index:** `tenant_kind_unique` enforces uniqueness on `(tenantId, kind)`, but only for the four built-in system kinds via a `partialFilter`. Custom statuses are excluded from this constraint.
+
+## Usage Example
+
+```java
+TicketStatusDefinition status = TicketStatusDefinition.builder()
+    .tenantId("tenant-abc")
+    .kind(TicketStatusKind.RESOLVED)
+    .name("Resolved")
+    .color("#4ECDC4")
+    .position("4")
+    .build();
+
+// Persist via Spring Data MongoDB repository
+ticketStatusRepository.save(status);
+
+// Lookup all statuses for a tenant
+List<TicketStatusDefinition> statuses = ticketStatusRepository
+    .findAllByTenantId("tenant-abc");
+```
+
+> The partial filter on the compound index means only system-defined `TicketStatusKind` values are uniqueness-constrained per tenant — allowing multiple custom statuses to coexist freely.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusKind.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusKind.md
new file mode 100644
index 000000000..0024233c9
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/.TicketStatusKind.md
@@ -0,0 +1,34 @@
+<!-- source-hash: f6c8e5d01f3c13813a870dc5a02fb6b3 -->
+Enum representing the possible lifecycle states of a support ticket, distinguishing between system-managed statuses and custom user-defined ones.
+
+## Key Components
+
+| Member | Description |
+|--------|-------------|
+| `AI_ASSISTANCE` | Ticket is currently being handled by AI automation |
+| `TECH_REQUIRED` | Ticket requires human technician intervention |
+| `RESOLVED` | Ticket has been successfully resolved |
+| `ARCHIVED` | Ticket has been archived |
+| `CUSTOM` | User-defined status outside the standard workflow |
+| `isSystem()` | Returns `true` for all statuses except `CUSTOM` |
+
+## Usage Example
+
+```java
+TicketStatusKind status = ticket.getStatusKind();
+
+if (status.isSystem()) {
+    // Handle AI_ASSISTANCE, TECH_REQUIRED, RESOLVED, or ARCHIVED
+    applySystemWorkflow(status);
+} else {
+    // Handle custom org-defined status
+    applyCustomWorkflow(ticket);
+}
+
+// Direct comparison
+if (status == TicketStatusKind.TECH_REQUIRED) {
+    notifyOnCallTechnician(ticket);
+}
+```
+
+> **Note:** Only `CUSTOM` returns `false` from `isSystem()`, making it straightforward to branch logic between platform-managed and organization-defined ticket states.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/filter/.TicketQueryFilter.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/filter/.TicketQueryFilter.md
index 048a5d928..5326f9dd0 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/filter/.TicketQueryFilter.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/ticket/filter/.TicketQueryFilter.md
@@ -1,32 +1,36 @@
-<!-- source-hash: 4c80ab774116de5b13c8ade5da7b95f1 -->
-A filter object for querying tickets, supporting multi-value filtering across statuses, organizations, assignees, labels, devices, creation sources, and date ranges.
+<!-- source-hash: 03c30f4f7737ef7da26133e07b5b5a00 -->
+A filter object used to construct scoped ticket queries, supporting both legacy status-based filtering and the newer lifecycle-aware status model.
 
 ## Key Components
 
 | Field | Type | Description |
-|---|---|---|
-| `statuses` | `List<TicketStatus>` | Filter by one or more ticket statuses |
-| `organizationIds` | `List<String>` | Filter by organization IDs |
-| `assigneeIds` | `List<String>` | Filter by assignee IDs |
+|-------|------|-------------|
+| `statuses` | `List<TicketStatus>` | **Legacy** — filter by enum statuses (pre-lifecycle rollout) |
+| `statusIds` | `List<String>` | **Lifecycle** — filter by status document IDs |
+| `statusKinds` | `List<TicketStatusKind>` | **Lifecycle** — filter by status kind categories |
+| `organizationIds` | `List<String>` | Scope tickets to specific organizations |
+| `assigneeIds` | `List<String>` | Filter by assigned technician IDs |
 | `labelIds` | `List<String>` | Filter by label IDs |
 | `deviceIds` | `List<String>` | Filter by associated device IDs |
-| `creationSources` | `List<TicketCreationSource>` | Filter by how tickets were created |
-| `createdAtFrom` | `Instant` | Start of creation date range |
-| `createdAtTo` | `Instant` | End of creation date range |
+| `creationSources` | `List<TicketCreationSource>` | Filter by how the ticket was created |
+| `createdAtFrom` / `createdAtTo` | `Instant` | Date range filter on creation timestamp |
 
-Built with Lombok (`@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`) following the same pattern as `MachineQueryFilter`.
+> **Note:** `statuses` is marked for removal after the lifecycle feature flag rollout is complete. New code should prefer `statusIds` and `statusKinds`.
 
 ## Usage Example
 
 ```java
-TicketQueryFilter filter = TicketQueryFilter.builder()
+// Legacy usage (lifecycle flag OFF)
+TicketQueryFilter legacyFilter = TicketQueryFilter.builder()
     .statuses(List.of(TicketStatus.OPEN, TicketStatus.IN_PROGRESS))
-    .organizationIds(List.of("org-123", "org-456"))
-    .assigneeIds(List.of("user-789"))
-    .creationSources(List.of(TicketCreationSource.EMAIL))
-    .createdAtFrom(Instant.parse("2024-01-01T00:00:00Z"))
-    .createdAtTo(Instant.parse("2024-12-31T23:59:59Z"))
+    .organizationIds(List.of("org-123"))
     .build();
 
-List<Ticket> tickets = ticketRepository.findAll(filter);
+// Lifecycle usage (lifecycle flag ON)
+TicketQueryFilter lifecycleFilter = TicketQueryFilter.builder()
+    .statusKinds(List.of(TicketStatusKind.ACTIVE))
+    .assigneeIds(List.of("tech-456"))
+    .createdAtFrom(Instant.parse("2024-01-01T00:00:00Z"))
+    .createdAtTo(Instant.now())
+    .build();
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.IntegratedTool.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.IntegratedTool.md
index 41f372c44..b6e432bb6 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.IntegratedTool.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.IntegratedTool.md
@@ -1,45 +1,41 @@
-<!-- source-hash: fb2fa2245ca7a66c033708469b26624a -->
-MongoDB document entity representing an integrated third-party tool in the OpenFrame platform, storing configuration, connectivity, and monitoring metadata for MSP tool integrations.
+<!-- source-hash: 3f2b484b8605c3b626c0eaafe620fdd3 -->
+MongoDB document entity representing an integrated third-party tool within a tenant's OpenFrame environment, mapping tool metadata, credentials, layer configuration, and monitoring settings to the `integrated_tools` collection.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
+| Member | Type | Description |
+|--------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `name` / `description` / `icon` | `String` | Display metadata for the tool |
+| `tenantId` | `String` | Tenant scope identifier (implements `TenantScoped`) |
+| `key` | `String` | Unique tool key per tenant (compound index with `tenantId`) |
+| `name` / `description` / `icon` | `String` | Display metadata |
 | `toolUrls` | `List<ToolUrl>` | Endpoint URLs associated with the tool |
-| `type` / `toolType` / `category` / `platformCategory` | `String` | Classification fields for tool categorization |
-| `enabled` | `boolean` | Toggle for activating/deactivating the integration |
-| `credentials` | `ToolCredentials` | Authentication/credential configuration |
-| `layer` / `layerOrder` / `layerColor` | `String` / `Integer` | UI layer stack positioning and styling |
-| `metricsPath` / `healthCheckEndpoint` | `String` | Monitoring and observability configuration |
-| `healthCheckInterval` / `connectionTimeout` / `readTimeout` | `Integer` | Timing parameters for health checks and connections |
-| `allowedEndpoints` | `String[]` | Allowlisted endpoint paths for the tool |
-| `debeziumConnectors` | `Object[]` | CDC (Change Data Capture) connector configurations |
+| `type` / `toolType` / `category` / `platformCategory` | `String` | Classification fields |
+| `enabled` | `boolean` | Activation state of the integration |
+| `credentials` | `ToolCredentials` | Auth/credential configuration |
+| `layer` / `layerOrder` / `layerColor` | `String` / `Integer` | UI layer rendering metadata |
+| `metricsPath` / `healthCheckEndpoint` | `String` | Monitoring targets |
+| `healthCheckInterval` / `connectionTimeout` / `readTimeout` | `Integer` | Polling and timeout settings (ms) |
+| `allowedEndpoints` | `String[]` | Permitted proxy/routing endpoints |
+| `debeziumConnectors` | `Object[]` | CDC connector definitions |
 
 ## Usage Example
 
 ```java
 IntegratedTool tool = IntegratedTool.builder()
-    .name("Zabbix")
-    .description("Network monitoring platform")
-    .icon("zabbix-icon.svg")
+    .tenantId("tenant-abc")
+    .key("zabbix")
+    .name("Zabbix Monitoring")
     .type("monitoring")
-    .toolType("open-source")
+    .toolType("zabbix")
     .category("infrastructure")
-    .platformCategory("observability")
     .enabled(true)
-    .layer("network")
-    .layerOrder(2)
-    .layerColor("#FFC008")
     .healthCheckEndpoint("/api/v1/health")
     .healthCheckInterval(30)
     .connectionTimeout(5000)
-    .readTimeout(3000)
-    .metricsPath("/metrics")
-    .credentials(toolCredentials)
-    .toolUrls(List.of(new ToolUrl("primary", "https://zabbix.internal")))
+    .readTimeout(10000)
+    .credentials(new ToolCredentials("admin", "secret"))
     .build();
 ```
 
-> **Note:** This entity is persisted to the `integrated_tools` MongoDB collection and is managed by the OpenFrame platform layer. Lombok annotations (`@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`) auto-generate boilerplate code.
\ No newline at end of file
+> The compound index `tenant_key_idx` on `{tenantId, key}` enforces uniqueness of tool keys per tenant while `sparse = true` excludes documents where either field is null.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.ToolConnection.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.ToolConnection.md
index 69a40c79b..73e5fb2c4 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.ToolConnection.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tool/.ToolConnection.md
@@ -1,39 +1,37 @@
-<!-- source-hash: eb2da7a6dea12967789764eaca7914db -->
-Represents a persistent MongoDB document that tracks the connection state between a machine and a specific tool integration within the OpenFrame platform.
+<!-- source-hash: e34231b8c8f2862dd1c1848ed0fbc130 -->
+MongoDB document entity representing a connection between a machine and an external tool within a tenant's scope, persisted in the `tool_connections` collection.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `String` | MongoDB document identifier (`@Id`) |
-| `machineId` | `String` | References the machine this connection belongs to |
-| `toolType` | `ToolType` | Enum identifying the tool integration type |
-| `agentToolId` | `String` | External identifier for the tool on the agent side |
-| `status` | `ConnectionStatus` | Current lifecycle state of the connection |
-| `metadata` | `String` | JSON string for tool-specific configuration/data |
-| `connectedAt` | `Instant` | Timestamp when the connection was established |
-| `lastSyncAt` | `Instant` | Timestamp of the most recent synchronization |
-| `disconnectedAt` | `Instant` | Timestamp when the connection was terminated |
-
-**Index:** A unique compound index (`machine_tool_idx`) on `machineId` + `toolType` enforces that each machine can have only one active connection per tool type.
+| Member | Type | Description |
+|--------|------|-------------|
+| `id` | `String` | MongoDB document identifier |
+| `tenantId` | `String` | Tenant scope identifier (via `TenantScoped`) |
+| `machineId` | `String` | Target machine for the tool connection |
+| `toolType` | `ToolType` | Enum defining the type of tool (e.g., RMM, PSA) |
+| `agentToolId` | `String` | External reference ID from the connected tool |
+| `status` | `ConnectionStatus` | Current connection state |
+| `metadata` | `String` | JSON blob for tool-specific configuration data |
+| `connectedAt` | `Instant` | Timestamp when connection was established |
+| `lastSyncAt` | `Instant` | Timestamp of the most recent sync |
+| `disconnectedAt` | `Instant` | Timestamp when connection was terminated |
+
+A **unique compound index** (`tenant_machine_tool_idx`) enforces that each machine can have at most one connection per tool type within a tenant.
 
 ## Usage Example
 
 ```java
 ToolConnection connection = new ToolConnection();
-connection.setMachineId("machine-abc-123");
-connection.setToolType(ToolType.RMMAGENT);
-connection.setAgentToolId("agent-tool-xyz");
+connection.setTenantId("tenant-abc");
+connection.setMachineId("machine-xyz");
+connection.setToolType(ToolType.RMM);
+connection.setAgentToolId("ext-agent-001");
 connection.setStatus(ConnectionStatus.CONNECTED);
-connection.setMetadata("{\"endpoint\": \"https://rmm.example.com\"}");
+connection.setMetadata("{\"agentVersion\": \"5.2\", \"platform\": \"windows\"}");
 connection.setConnectedAt(Instant.now());
 
-// Persisted to the "tool_connections" collection
+// Persisted to 'tool_connections' collection
 toolConnectionRepository.save(connection);
 ```
 
-## Notes
-
-- The unique compound index prevents duplicate tool registrations per machine at the database level
-- `metadata` is stored as a raw JSON string, allowing flexible tool-specific payloads without schema changes
-- Lifecycle timestamps (`connectedAt`, `lastSyncAt`, `disconnectedAt`) enable connection auditing and health monitoring
\ No newline at end of file
+> The `metadata` field stores tool-specific data as a raw JSON string, allowing flexible schema per `ToolType` without requiring additional document types.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/toolagent/.IntegratedToolAgent.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/toolagent/.IntegratedToolAgent.md
index 298e06610..77db2936f 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/toolagent/.IntegratedToolAgent.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/toolagent/.IntegratedToolAgent.md
@@ -1,42 +1,43 @@
-<!-- source-hash: 7bd3419cefe11b7165ee14f220c993c3 -->
-Represents a MongoDB document entity for a versioned, integrated tool agent within the OpenFrame platform.
+<!-- source-hash: cc0121c3ebc6e0a3865e5060e0526539 -->
+MongoDB document entity representing a tenant-scoped integrated tool agent configuration, mapping agent lifecycle commands, assets, and deployment state within the OpenFrame platform.
 
 ## Key Components
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
+| `tenantId` | `String` | Tenant isolation key (part of compound unique index with `key`) |
+| `key` | `String` | Unique agent identifier per tenant |
 | `documentVersion` | `Long` | Optimistic locking version (`@Version`) |
-| `toolId` | `String` | Reference to the associated tool |
-| `releaseVersion` | `boolean` | Flags whether this is a release version |
-| `version` | `String` | Version string for the agent |
-| `sessionType` | `SessionType` | Defines the session behavior type |
-| `downloadConfigurations` | `List<DownloadConfiguration>` | Download settings for the agent |
-| `assets` | `List<ToolAgentAsset>` | Binary or resource assets bundled with the agent |
-| `installationCommandArgs` | `List<String>` | CLI args used during agent installation |
-| `runCommandArgs` | `List<String>` | CLI args used to run the agent |
-| `agentToolIdCommandArgs` | `List<String>` | CLI args for agent tool identification |
-| `uninstallationCommandArgs` | `List<String>` | CLI args used during agent removal |
-| `status` | `ToolAgentStatus` | Current lifecycle status of the agent |
-| `publishState` | `PublishState` | Publication state (e.g. draft, published) |
+| `toolId` | `String` | Reference to the parent tool |
+| `releaseVersion` | `boolean` | Flags whether this is a release-grade version |
+| `sessionType` | `SessionType` | Defines the agent session behavior |
+| `downloadConfigurations` | `List<DownloadConfiguration>` | Download sources and options for the agent |
+| `assets` | `List<ToolAgentAsset>` | Associated binary/resource assets |
+| `installationCommandArgs` | `List<String>` | CLI args for agent installation |
+| `runCommandArgs` | `List<String>` | CLI args to start the agent |
+| `agentToolIdCommandArgs` | `List<String>` | CLI args for tool identity injection |
+| `uninstallationCommandArgs` | `List<String>` | CLI args for agent removal |
+| `status` | `ToolAgentStatus` | Current runtime/deployment status |
+| `publishState` | `PublishState` | Publication lifecycle state |
 
 ## Usage Example
 
 ```java
 IntegratedToolAgent agent = new IntegratedToolAgent();
-agent.setToolId("tool-abc-123");
-agent.setVersion("1.2.0");
+agent.setTenantId("tenant-abc");
+agent.setKey("rmm-agent-v2");
+agent.setToolId("tool-001");
+agent.setVersion("2.1.0");
 agent.setReleaseVersion(true);
 agent.setSessionType(SessionType.PERSISTENT);
+agent.setInstallationCommandArgs(List.of("--silent", "--target=/opt/agent"));
+agent.setRunCommandArgs(List.of("--daemon", "--port=9090"));
+agent.setUninstallationCommandArgs(List.of("--purge"));
 agent.setStatus(ToolAgentStatus.ACTIVE);
 agent.setPublishState(PublishState.PUBLISHED);
 
-agent.setInstallationCommandArgs(List.of("--install", "--silent"));
-agent.setRunCommandArgs(List.of("--start", "--config=/etc/agent.conf"));
-agent.setUninstallationCommandArgs(List.of("--uninstall", "--purge"));
-
-// Persist via Spring Data MongoDB repository
-integratedToolAgentRepository.save(agent);
+mongoTemplate.save(agent);
 ```
 
-> Stored in the `integrated_tool_agents` MongoDB collection. Uses Spring Data's `@Version` for optimistic concurrency control, preventing conflicting concurrent updates to the same agent document.
\ No newline at end of file
+> The compound index on `tenantId` + `key` enforces uniqueness per tenant while `sparse = true` allows null keys without index conflicts.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.Invitation.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.Invitation.md
index fbcd941e6..f400f6186 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.Invitation.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.Invitation.md
@@ -1,35 +1,37 @@
-<!-- source-hash: ecd66b63fcb392444eda2c382e96efd8 -->
-MongoDB document entity representing a user invitation record, stored in the `invitations` collection. Handles email normalization and tracks invitation lifecycle state.
+<!-- source-hash: f1e94c87854c3fe1d6716974c8aa4b5f -->
+MongoDB document entity representing a user invitation within a tenant, tracking email, roles, expiration, and lifecycle status.
 
 ## Key Components
 
-| Field | Type | Description |
-|-------|------|-------------|
+| Member | Type | Description |
+|--------|------|-------------|
 | `id` | `String` | MongoDB document identifier (`@Id`) |
-| `email` | `String` | Indexed, normalized email address of the invitee |
-| `roles` | `List<UserRole>` | Roles to assign upon invitation acceptance (defaults to empty list) |
-| `expiresAt` | `Instant` | Invitation expiration timestamp |
-| `status` | `InvitationStatus` | Current state, defaults to `PENDING` |
-| `createdAt` | `Instant` | Auto-populated creation timestamp (`@CreatedDate`) |
-| `updatedAt` | `Instant` | Auto-populated last modified timestamp (`@LastModifiedDate`) |
-
-**`setEmail(String email)`** — Custom setter that trims whitespace and lowercases the email using `Locale.ROOT` before persistence, preventing duplicate entries from case or spacing variations.
+| `tenantId` | `String` | Indexed tenant reference (implements `TenantScoped`) |
+| `email` | `String` | Indexed invitee email, normalized on set |
+| `roles` | `List<UserRole>` | Roles to assign upon acceptance (defaults to empty list) |
+| `expiresAt` | `Instant` | Invitation expiry timestamp |
+| `status` | `InvitationStatus` | Lifecycle state, defaults to `PENDING` |
+| `createdAt` / `updatedAt` | `Instant` | Audit timestamps managed by Spring Data |
 
 ## Usage Example
 
 ```java
-// Build a new invitation
+// Create a new invitation
 Invitation invitation = Invitation.builder()
-    .email("  John.Doe@Example.com  ")  // will be normalized to "john.doe@example.com"
+    .tenantId("tenant-123")
+    .email("  User@Example.com  ") // normalized to "user@example.com"
     .roles(List.of(UserRole.TECHNICIAN))
     .expiresAt(Instant.now().plus(7, ChronoUnit.DAYS))
     .build();
 
-// Status defaults to PENDING
-assert invitation.getStatus() == InvitationStatus.PENDING;
+// Email is always stored trimmed and lowercased
+invitation.setEmail("  Admin@Company.COM  ");
+System.out.println(invitation.getEmail()); // "admin@company.com"
 
-// Update status after acceptance
-invitation.setStatus(InvitationStatus.ACCEPTED);
+// Check invitation state
+if (invitation.getStatus() == InvitationStatus.PENDING) {
+    // process acceptance
+}
 ```
 
-> **Note:** Email normalization is applied automatically via the custom `setEmail` setter — both direct assignment and builder usage will result in a trimmed, lowercase value stored in MongoDB.
\ No newline at end of file
+> **Note:** Email normalization (trim + lowercase) is enforced in the setter, ensuring consistent lookups regardless of how the address was submitted.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.User.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.User.md
index 422b86626..ebdd3b8f9 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.User.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/user/.User.md
@@ -1,39 +1,37 @@
-<!-- source-hash: 49f0a72a76a82b9b10f57883388e6e87 -->
-MongoDB document entity representing a user account, mapped to the `users` collection with auditing, role management, and normalized email handling.
+<!-- source-hash: 9cbd03489d685f05a59383ca9039393d -->
+MongoDB document entity representing a platform user within a tenant, mapped to the `users` collection with multi-tenant isolation via `TenantScoped`.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `id` | `String` | MongoDB `@Id` primary key |
-| `email` | `String` | Indexed, auto-normalized to lowercase on set |
-| `firstName` / `lastName` | `String` | User display name fields |
+| `id` | `String` | MongoDB document `_id` |
+| `tenantId` | `String` | Indexed tenant isolator (implements `TenantScoped`) |
+| `email` | `String` | Indexed, normalized to lowercase on set |
+| `firstName` / `lastName` | `String` | Display name fields |
 | `roles` | `List<UserRole>` | Assigned roles, defaults to empty list |
-| `emailVerified` | `boolean` | Email verification flag; `true` by default for SSO users |
-| `status` | `UserStatus` | Indexed account status, defaults to `ACTIVE` |
-| `createdAt` / `updatedAt` | `LocalDateTime` | Spring Data audit timestamps |
+| `emailVerified` | `boolean` | Email verification flag; auto-set `true` for SSO logins |
+| `status` | `UserStatus` | Indexed lifecycle status, defaults to `ACTIVE` |
+| `createdAt` / `updatedAt` | `LocalDateTime` | Audit timestamps via Spring Data `@CreatedDate` / `@LastModifiedDate` |
 
-## Key Behaviors
-
-- **Email normalization** — `setEmail()` trims whitespace and lowercases the value using `Locale.ROOT`, ensuring consistent storage and lookups.
-- **Lombok `@SuperBuilder`** — Supports builder inheritance for subclasses; `@Builder.Default` ensures `roles` and `status` have safe defaults even when using the builder pattern.
-- **Spring Data auditing** — `@CreatedDate` and `@LastModifiedDate` are populated automatically when auditing is enabled in the application context.
+**`setEmail(String)`** — Custom setter that trims and lowercases the email using `Locale.ROOT` before persisting, preventing case-sensitive duplicates.
 
 ## Usage Example
 
 ```java
-// Build a new user
+// Build a new user with the Lombok builder
 User user = User.builder()
-    .email("  Alice@Example.com  ")  // normalized to "alice@example.com"
+    .tenantId("tenant-abc")
+    .email("  Alice@Example.com  ")   // normalized to "alice@example.com"
     .firstName("Alice")
     .lastName("Smith")
-    .roles(List.of(UserRole.TECHNICIAN))
+    .roles(List.of(UserRole.ADMIN))
     .emailVerified(true)
+    .status(UserStatus.ACTIVE)
     .build();
 
-// Status defaults to ACTIVE
-assert user.getStatus() == UserStatus.ACTIVE;
+// Retrieve tenant-scoped users via repository
+List<User> tenantUsers = userRepository.findByTenantId("tenant-abc");
+```
 
-// Save via repository
-userRepository.save(user);
-```
\ No newline at end of file
+> **Note:** Always use `setEmail()` (or the builder's `.email()`) rather than direct field injection to guarantee email normalization before storage.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/version/.ReleaseVersion.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/version/.ReleaseVersion.md
index f54bf5f47..d1b4a8b3b 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/version/.ReleaseVersion.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/version/.ReleaseVersion.md
@@ -1,39 +1,35 @@
-<!-- source-hash: c2d6b54b5267e192ddd64093b01a6899 -->
-MongoDB document entity representing a release version record stored in the `release_versions` collection, with optimistic locking and automatic audit timestamps.
+<!-- source-hash: ca177b0e1df476be0826022818895b7f -->
+MongoDB document entity representing a versioned release record scoped to a specific tenant, stored in the `release_versions` collection.
 
 ## Key Components
 
-| Member | Type | Description |
-|--------|------|-------------|
-| `DEFAULT_ID` | `String` constant | Sentinel ID (`"default"`) for the primary/singleton version document |
-| `id` | `String` | MongoDB document `_id` field |
-| `documentVersion` | `Long` | `@Version` field enabling optimistic locking to prevent concurrent write conflicts |
-| `version` | `String` | Indexed release version string (e.g., `"1.2.3"`) |
-| `createdAt` | `Instant` | Auto-populated on document creation via `@CreatedDate` |
-| `updatedAt` | `Instant` | Auto-updated on every save via `@LastModifiedDate` |
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `String` | MongoDB document identifier (`@Id`) |
+| `tenantId` | `String` | Tenant scope identifier, indexed for query performance |
+| `documentVersion` | `Long` | Optimistic locking version via Spring's `@Version` |
+| `version` | `String` | Release version label (e.g. `1.0.0`), indexed |
+| `createdAt` | `Instant` | Auto-populated creation timestamp |
+| `updatedAt` | `Instant` | Auto-populated last modification timestamp |
 
-## Usage Example
-
-```java
-// Create and persist a new release version
-ReleaseVersion releaseVersion = new ReleaseVersion();
-releaseVersion.setId(ReleaseVersion.DEFAULT_ID);
-releaseVersion.setVersion("2.1.0");
-
-releaseVersionRepository.save(releaseVersion);
+## Key Behaviors
 
-// Fetch the singleton default version document
-Optional<ReleaseVersion> current = releaseVersionRepository
-    .findById(ReleaseVersion.DEFAULT_ID);
+- Implements `TenantScoped` to enforce multi-tenant data isolation
+- Uses Spring Data MongoDB's optimistic locking (`@Version`) to prevent concurrent write conflicts
+- Indexed fields (`tenantId`, `version`) optimize tenant-filtered version lookups
 
-current.ifPresent(rv -> {
-    System.out.println("Version: " + rv.getVersion());
-    System.out.println("Last updated: " + rv.getUpdatedAt());
-});
-```
-
-## Notes
+## Usage Example
 
-- Requires `@EnableMongoAuditing` on the Spring Boot application or a `MongoConfig` class for `@CreatedDate` / `@LastModifiedDate` to populate automatically.
-- The `@Version` field (`documentVersion`) protects against lost updates — Spring Data MongoDB will throw `OptimisticLockingFailureException` on stale writes.
-- The `DEFAULT_ID` constant is intended for a singleton pattern where a single canonical version document is maintained per deployment.
\ No newline at end of file
+```java
+// Create a new release version for a tenant
+ReleaseVersion release = new ReleaseVersion();
+release.setTenantId("tenant-abc");
+release.setVersion("2.1.0");
+
+// Persist via a Spring Data repository
+releaseVersionRepository.save(release);
+
+// Query by tenant and version
+Optional<ReleaseVersion> found = releaseVersionRepository
+    .findByTenantIdAndVersion("tenant-abc", "2.1.0");
+```
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/.TenantAwareRepository.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/.TenantAwareRepository.md
new file mode 100644
index 000000000..ab3e6f6ef
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/.TenantAwareRepository.md
@@ -0,0 +1,36 @@
+<!-- source-hash: 913e3402ba54d12910a10b535023fc19 -->
+Composed annotation that marks Spring Data repository interfaces as tenant-scoped, combining `@Repository` registration with a filter marker that enables shared-service exclusion.
+
+## Key Components
+
+- **`@TenantAwareRepository`** — Meta-annotation applied at the type level (`ElementType.TYPE`) with runtime retention. Inherits `@Repository` for Spring component registration and serves as a filter target to exclude tenant-scoped repositories from shared-service contexts.
+
+## Usage Example
+
+**Annotating a tenant-aware repository:**
+
+```java
+@TenantAwareRepository
+public interface DeviceRepository extends MongoRepository<Device, String> {
+    List<Device> findByTenantId(String tenantId);
+}
+```
+
+**Excluding tenant repositories in a shared service configuration:**
+
+```java
+@Configuration
+@EnableMongoRepositories(
+    excludeFilters = @ComponentScan.Filter(
+        type = FilterType.ANNOTATION,
+        classes = TenantAwareRepository.class
+    )
+)
+public class SharedServiceMongoConfig { }
+```
+
+## Notes
+
+- Only valid in contexts where `TenantAwareMongoTemplate` is available (`tenant-isolation.enabled=true`)
+- Repositories without this annotation are loaded in all contexts (shared + tenant)
+- Repositories **with** this annotation are silently excluded from shared-service bootstrap, preventing missing-bean errors at startup
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/tool/.BaseIntegratedToolRepository.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/tool/.BaseIntegratedToolRepository.md
index 286f22d4b..0acac716f 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/tool/.BaseIntegratedToolRepository.md
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/repository/tool/.BaseIntegratedToolRepository.md
@@ -1,51 +1,38 @@
-<!-- source-hash: 1a134c61ae6bf3b9da36854fc6d705b5 -->
-Generic base repository interface for integrated tool persistence operations, designed to support both reactive and blocking implementations through type parameters.
+<!-- source-hash: 4adfa47d47f8b1e41a41bfb334762d3a -->
+Generic repository interface for querying integrated tools across both blocking and reactive implementations, with built-in support for tenant-aware queries.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `BaseIntegratedToolRepository<T, B, ID>` | Generic interface parameterized for blocking or reactive return types |
+| Element | Description |
+|---------|-------------|
+| `BaseIntegratedToolRepository<T, B, ID>` | Generic base interface parameterized for blocking vs. reactive use |
 | `T` | Return type wrapper — `Optional<IntegratedTool>` (blocking) or `Mono<IntegratedTool>` (reactive) |
 | `B` | Boolean return type — `boolean` (blocking) or `Mono<Boolean>` (reactive) |
-| `ID` | Identifier type, typically `String` |
-| `findByType(String type)` | Locates an integrated tool record by its tool type string |
+| `ID` | ID type, typically `String` |
+| `findByType(String type)` | Looks up an integrated tool by its type identifier |
+| `findByKey(String key)` | Looks up a tool by its human-readable key (e.g., `"fleetmdm-server"`) with automatic tenant injection |
 
 ## Usage Example
 
-**Blocking implementation:**
-
 ```java
+// Blocking implementation (e.g., for background jobs)
 public interface IntegratedToolRepository
     extends BaseIntegratedToolRepository<Optional<IntegratedTool>, Boolean, String> {
-
-    @Override
-    Optional<IntegratedTool> findByType(String type);
+    // inherits findByType and findByKey
 }
-```
 
-**Reactive implementation:**
-
-```java
+// Reactive implementation (e.g., for API services)
 public interface ReactiveIntegratedToolRepository
     extends BaseIntegratedToolRepository<Mono<IntegratedTool>, Mono<Boolean>, String> {
-
-    @Override
-    Mono<IntegratedTool> findByType(String type);
+    // inherits findByType and findByKey
 }
-```
-
-**Usage in a service:**
-
-```java
-@Service
-public class ToolService {
-    private final IntegratedToolRepository repository;
 
-    public Optional<IntegratedTool> getByType(String type) {
-        return repository.findByType(type); // e.g., "connectwise", "halo"
-    }
-}
+// Usage in a service
+Mono<IntegratedTool> tool = reactiveRepo.findByKey("fleetmdm-server");
+Optional<IntegratedTool> toolBlocking = blockingRepo.findByType("MDM");
 ```
 
-> **Design note:** The `B` type parameter is reserved for future boolean-returning operations (e.g., `existsByType`), keeping the interface extensible without breaking existing implementations.
\ No newline at end of file
+## Notes
+
+- `findByKey` integrates with `TenantAwareMongoTemplate`, which automatically injects the `tenantId` scoping queries to the correct tenant — no manual tenant filtering required in service code.
+- The `B` type parameter is reserved for future boolean-returning operations (e.g., `existsByType`).
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/service/.DefaultTenantIdProvider.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/service/.DefaultTenantIdProvider.md
new file mode 100644
index 000000000..6f6625e21
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/service/.DefaultTenantIdProvider.md
@@ -0,0 +1,32 @@
+<!-- source-hash: 6889a46bf8bed32e73fa33edc83b2985 -->
+Fallback implementation of `TenantIdProvider` that resolves the tenant ID from the `TENANT_ID` environment variable, defaulting to `"oss"` when not set.
+
+## Key Components
+
+| Element | Description |
+|---------|-------------|
+| `DefaultTenantIdProvider` | Spring `@Service` implementing `TenantIdProvider`; active only when no other `TenantIdProvider` bean is registered |
+| `@ConditionalOnMissingBean` | Ensures this bean is skipped if a custom `TenantIdProvider` is already defined in the application context |
+| `tenantId` | Injected from `TENANT_ID` env var or Spring property; falls back to `"oss"` (open-source default) |
+| `getTenantId()` | Returns the resolved tenant identifier string |
+
+## Usage Example
+
+```java
+// Auto-registered by Spring Boot when no custom TenantIdProvider exists.
+// Override by defining your own bean:
+
+@Service
+public class MyTenantIdProvider implements TenantIdProvider {
+    @Override
+    public String getTenantId() {
+        return "acme-corp"; // custom tenant resolution logic
+    }
+}
+
+// If no override is present, the default resolves via:
+// TENANT_ID=my-tenant  ->  getTenantId() returns "my-tenant"
+// (unset)              ->  getTenantId() returns "oss"
+```
+
+> **Note:** Set the `TENANT_ID` environment variable at deployment time to configure the active tenant for the service. In multi-tenant or cloud-managed deployments, provide a custom `TenantIdProvider` bean to replace this default entirely.
\ No newline at end of file
diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/service/.TenantIdProvider.md b/openframe-data-mongo-common/src/main/java/com/openframe/data/service/.TenantIdProvider.md
new file mode 100644
index 000000000..969a3ec43
--- /dev/null
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/service/.TenantIdProvider.md
@@ -0,0 +1,47 @@
+<!-- source-hash: 21b789f02ca95bd18c0ae9c9258c6cc8 -->
+Defines the contract for resolving the current pod's tenant identity, supporting both OSS (environment variable) and SaaS (cluster-registration-based) deployment modes.
+
+## Key Components
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `getTenantId()` | `String` | Returns the tenant ID for the running pod |
+| `isTenantRegistered()` | `default boolean` | Checks if the tenant is registered and ready; defaults to `true` for OSS |
+
+## Deployment Behavior
+
+```mermaid
+graph TD
+    A["TenantIdProvider"] -->|"OSS default"| B["Read TENANT_ID env var"]
+    A -->|"SaaS @Primary override"| C["Resolve clusterName via tenant_cluster_registrations"]
+    B --> D["isTenantRegistered() → always true"]
+    C --> E["isTenantRegistered() → false until provisioned"]
+```
+
+## Usage Example
+
+```java
+@Service
+public class MyService {
+
+    private final TenantIdProvider tenantIdProvider;
+
+    public MyService(TenantIdProvider tenantIdProvider) {
+        this.tenantIdProvider = tenantIdProvider;
+    }
+
+    public void process() {
+        if (!tenantIdProvider.isTenantRegistered()) {
+            throw new IllegalStateException("Tenant not yet provisioned");
+        }
+        String tenantId = tenantIdProvider.getTenantId();
+        // use tenantId for scoped queries, logging, etc.
+    }
+}
+```
+
+## Notes
+
+- The OSS default implementation reads from the `TENANT_ID` environment variable — no registration lookup required.
+- SaaS deployments inject a `@Primary` bean that performs a database lookup in `tenant_cluster_registrations` to resolve `clusterName → tenantId`.
+- `isTenantRegistered()` is a `default` method, so OSS implementations need not override it.
\ No newline at end of file
diff --git a/openframe-data-mongo-reactive/src/main/java/com/openframe/data/reactive/repository/tool/.ReactiveIntegratedToolRepository.md b/openframe-data-mongo-reactive/src/main/java/com/openframe/data/reactive/repository/tool/.ReactiveIntegratedToolRepository.md
index a4047e2ba..9d512b491 100644
--- a/openframe-data-mongo-reactive/src/main/java/com/openframe/data/reactive/repository/tool/.ReactiveIntegratedToolRepository.md
+++ b/openframe-data-mongo-reactive/src/main/java/com/openframe/data/reactive/repository/tool/.ReactiveIntegratedToolRepository.md
@@ -1,16 +1,14 @@
-<!-- source-hash: bbae9290a77c0e999497c6ba4c3457d2 -->
-Reactive MongoDB repository interface for managing `IntegratedTool` documents, providing non-blocking database operations using Project Reactor types.
+<!-- source-hash: e174cdc526a6770b3cf975386a984912 -->
+Reactive MongoDB repository interface for managing `IntegratedTool` documents, combining Spring's `ReactiveMongoRepository` with the shared `BaseIntegratedToolRepository` contract to provide non-blocking data access.
 
 ## Key Components
 
-| Element | Type | Description |
-|---|---|---|
-| `ReactiveIntegratedToolRepository` | Interface | Spring Data reactive repository for `IntegratedTool` documents |
-| `findByType(String type)` | `Mono<IntegratedTool>` | Queries a single integrated tool by its type identifier |
-
-**Extends:**
-- `ReactiveMongoRepository<IntegratedTool, String>` — Full reactive CRUD support for MongoDB
-- `BaseIntegratedToolRepository<Mono<IntegratedTool>, Mono<Boolean>, String>` — Shared contract across reactive and blocking repository implementations
+| Element | Description |
+|---|---|
+| `ReactiveMongoRepository<IntegratedTool, String>` | Base Spring Data reactive MongoDB CRUD operations |
+| `BaseIntegratedToolRepository<Mono<...>>` | Shared repository contract using `Mono` as the reactive return type |
+| `findByType(String type)` | Looks up a single `IntegratedTool` by its integration type |
+| `findByKey(String key)` | Looks up a single `IntegratedTool` by its unique key |
 
 ## Usage Example
 
@@ -31,10 +29,11 @@ public class ToolService {
                 ));
     }
 
-    public Mono<IntegratedTool> saveTool(IntegratedTool tool) {
-        return toolRepository.save(tool);
+    public Mono<IntegratedTool> getToolByKey(String key) {
+        return toolRepository.findByKey(key)
+                .doOnNext(tool -> log.info("Found tool: {}", tool.getKey()));
     }
 }
 ```
 
-> **Note:** This repository is part of the OpenFrame reactive data layer. Use it in non-blocking, reactive pipelines (e.g., WebFlux controllers or reactive service chains) to avoid blocking the event loop. For blocking/imperative contexts, use the non-reactive counterpart that also implements `BaseIntegratedToolRepository`.
\ No newline at end of file
+> Both query methods return `Mono<IntegratedTool>`, meaning they emit at most one result and integrate cleanly into reactive pipelines using Project Reactor operators such as `flatMap`, `switchIfEmpty`, or `doOnNext`.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoInfraConfig.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoInfraConfig.md
new file mode 100644
index 000000000..cc4028706
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoInfraConfig.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 4a34a4c2de6fecdef767427d0faf519e -->
+Configures MongoDB infrastructure for the OpenFrame data layer, conditionally activated when `spring.data.mongodb.enabled=true` with MongoDB auditing enabled.
+
+## Key Components
+
+- **`MongoInfraConfig`** — Spring `@Configuration` class that bootstraps core MongoDB infrastructure beans
+- **`mappingMongoConverter`** — Custom `MappingMongoConverter` bean that wires together the `DbRefResolver`, mapping context, and custom conversions; replaces MongoDB's default converter
+- **Dot Replacement** — Substitutes `.` characters in map keys with `__dot__` to avoid conflicts with MongoDB's dot-notation field addressing
+
+## Annotations
+
+| Annotation | Purpose |
+|---|---|
+| `@ConditionalOnProperty` | Only loads if `spring.data.mongodb.enabled=true` |
+| `@EnableMongoAuditing` | Activates `@CreatedDate`, `@LastModifiedDate`, etc. on entities |
+
+## Usage Example
+
+```java
+# application.yml
+spring:
+  data:
+    mongodb:
+      enabled: true
+      uri: mongodb://localhost:27017/openframe
+```
+
+```java
+// Entity using auditing fields enabled by this config
+@Document
+public class Ticket {
+    @Id
+    private String id;
+
+    @CreatedDate
+    private Instant createdAt;
+
+    @LastModifiedDate
+    private Instant updatedAt;
+
+    // Map keys with dots are stored as __dot__ in MongoDB
+    private Map<String, Object> metadata;
+}
+```
+
+> **Note:** The `__dot__` key replacement prevents runtime errors when storing `Map<String, Object>` fields whose keys contain `.` characters — common in dynamic metadata payloads across the OpenFrame platform.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoSyncConfig.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoSyncConfig.md
index 0001f7c52..95f44645c 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoSyncConfig.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.MongoSyncConfig.md
@@ -1,48 +1,35 @@
-<!-- source-hash: 674cfe2dc6bdaa6ff867ee2efa6b4685 -->
-Configures Spring Data MongoDB for synchronous (blocking) access, activated only when `spring.data.mongodb.enabled=true` is set.
+<!-- source-hash: 5ba6810f076eafa3430aedffe0c390d8 -->
+Configures synchronous (non-reactive) MongoDB repositories for OpenFrame when tenant isolation is disabled, conditionally enabling standard Spring Data Mongo repositories while excluding tenant-aware ones.
 
 ## Key Components
 
-| Element | Description |
-|---|---|
-| `@ConditionalOnProperty` | Guards the entire configuration — MongoDB beans are only registered when the property is explicitly enabled |
-| `@EnableMongoRepositories` | Scans `com.openframe.data.repository` for Spring Data repository interfaces |
-| `@EnableMongoAuditing` | Enables automatic population of auditing fields (`@CreatedDate`, `@LastModifiedDate`, etc.) |
-| `mappingMongoConverter()` | Custom `MappingMongoConverter` bean that wires custom type conversions and replaces `.` in map keys with `__dot__` to avoid MongoDB key restriction errors |
+- **`@ConditionalOnExpression`** — Activates only when `spring.data.mongodb.enabled=true` **and** `openframe.tenant-isolation.enabled=false`
+- **`@EnableMongoRepositories`** — Scans `com.openframe.data.repository` for standard MongoDB repositories
+- **Exclusion Filter** — Skips any repository annotated with `@TenantAwareRepository` to prevent conflicts with multi-tenant configurations
 
 ## Usage Example
 
-Enable the configuration in your `application.yml`:
-
-```yaml
-spring:
-  data:
-    mongodb:
-      enabled: true
-      uri: mongodb://localhost:27017/openframe
-```
-
-Use a custom conversion or map field safely:
-
 ```java
-@Document(collection = "tickets")
-public class Ticket {
+# application.properties
 
-    @Id
-    private String id;
+# Enable standard (sync) Mongo config
+spring.data.mongodb.enabled=true
 
-    // Keys with dots (e.g. "meta.region") are stored as "meta__dot__region"
-    private Map<String, Object> metadata;
+# Must be false to activate MongoSyncConfig
+openframe.tenant-isolation.enabled=false
 
-    @CreatedDate
-    private Instant createdAt;
+spring.data.mongodb.uri=mongodb://localhost:27017/openframe
+```
 
-    @LastModifiedDate
-    private Instant updatedAt;
+```java
+// Standard repository — picked up by MongoSyncConfig
+public interface DeviceRepository extends MongoRepository<Device, String> {
+    List<Device> findByTenantId(String tenantId);
 }
-```
 
-## Notes
+// Annotated with @TenantAwareRepository — excluded from this config
+@TenantAwareRepository
+public interface TenantDeviceRepository extends MongoRepository<Device, String> { }
+```
 
-- The `__dot__` replacement is critical when storing `Map<String, Object>` fields whose keys may contain `.` — MongoDB rejects dotted key names natively.
-- Setting `matchIfMissing = false` means MongoDB is **opt-in**; services that don't need persistence won't load any Mongo beans, keeping startup fast and avoiding connection errors in non-database environments.
\ No newline at end of file
+> **Note:** When `openframe.tenant-isolation.enabled=true`, this configuration is skipped entirely and the tenant-aware MongoDB setup takes over, ensuring repositories are routed through the correct tenant database context.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.NotificationContextMongoConfig.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.NotificationContextMongoConfig.md
index fc6982214..32834c699 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.NotificationContextMongoConfig.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.NotificationContextMongoConfig.md
@@ -1,30 +1,34 @@
-<!-- source-hash: 71fa06a487e32d4e72d9b936f7ba03d2 -->
-Configures MongoDB integration for the notification context, registering custom read converters, conversion mappings, and a selective type mapper for `MappingMongoConverter`.
+<!-- source-hash: 0d1c17ee1f92b52b9645e02c1533dcc3 -->
+Spring `@Configuration` class that registers MongoDB custom converters and type mapping for `NotificationContext` persistence, enabling JSON-based serialization/deserialization of notification context objects stored in MongoDB.
 
 ## Key Components
 
-| Bean | Type | Purpose |
-|------|------|---------|
-| `notificationContextReadConverter` | `NotificationContextReadConverter` | Deserializes MongoDB documents into notification context objects using Jackson |
-| `notificationContextCustomConversions` | `MongoCustomConversions` | Registers the read converter with Spring Data MongoDB's conversion infrastructure |
-| `notificationContextTypeMapperPostProcessor` | `BeanPostProcessor` | Intercepts `MappingMongoConverter` initialization to inject a `NotificationContextSelectiveTypeMapper` |
+| Bean | Description |
+|------|-------------|
+| `notificationContextReadConverter` | Reads/deserializes `NotificationContext` documents from MongoDB using Jackson `ObjectMapper` |
+| `notificationContextWriteConverter` | Writes/serializes `NotificationContext` objects to MongoDB documents using Jackson `ObjectMapper` |
+| `notificationContextCustomConversions` | Registers both converters as `MongoCustomConversions` so Spring Data MongoDB uses them automatically |
+| `notificationContextTypeMapperPostProcessor` | `BeanPostProcessor` that injects a `NotificationContextSelectiveTypeMapper` into `MappingMongoConverter` to control `_class` type hint storage selectively |
 
-## Usage Example
+**Imports:** `NotificationContextJacksonConfig` via `@Import` to ensure the shared `ObjectMapper` bean is configured before converters are instantiated.
 
-This configuration is auto-applied via Spring's component scanning. It imports `NotificationContextJacksonConfig` to ensure the `ObjectMapper` is properly configured before wiring converters.
+## Usage Example
 
 ```java
-// Triggered automatically on application startup — no manual wiring needed.
-// The BeanPostProcessor intercepts MappingMongoConverter and applies
-// the selective type mapper to control _class field handling.
+// No manual wiring needed — Spring auto-detects the configuration.
+// Simply ensure the package is component-scanned or explicitly imported:
 
 @SpringBootApplication
 @Import(NotificationContextMongoConfig.class)
-public class Application {
+public class OpenFrameApplication {
     public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
+        SpringApplication.run(OpenFrameApplication.class, args);
     }
 }
+
+// At runtime, saving a NotificationContext entity routes through the registered converters:
+// Write path: NotificationContext → NotificationContextWriteConverter → MongoDB Document
+// Read path:  MongoDB Document   → NotificationContextReadConverter  → NotificationContext
 ```
 
-> **Note:** The `notificationContextTypeMapperPostProcessor` is declared `static` to ensure it is instantiated early in the Spring lifecycle, before other beans are processed — a requirement for `BeanPostProcessor` beans defined inside `@Configuration` classes.
\ No newline at end of file
+> The `BeanPostProcessor` runs statically after `MappingMongoConverter` initialization, replacing the default type mapper with `NotificationContextSelectiveTypeMapper` to avoid writing unnecessary `_class` fields on all MongoDB documents — keeping the schema clean for non-polymorphic notification context records.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.TenantAwareSyncConfig.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.TenantAwareSyncConfig.md
new file mode 100644
index 000000000..180597f09
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/config/.TenantAwareSyncConfig.md
@@ -0,0 +1,24 @@
+<!-- source-hash: 3c1ec381d5e7ec864b0627752cc4972d -->
+Conditionally enables MongoDB repository scanning when both MongoDB and tenant isolation are active in the OpenFrame platform.
+
+## Key Components
+
+- **`@ConditionalOnExpression`** — Activates this configuration only when both `spring.data.mongodb.enabled` and `openframe.tenant-isolation.enabled` resolve to `true`
+- **`@EnableMongoRepositories`** — Scans `com.openframe.data.repository` for MongoDB repository interfaces when the condition is met
+
+## Usage Example
+
+```java
+// application.yml — enable both flags to activate this config
+spring:
+  data:
+    mongodb:
+      enabled: true
+      uri: mongodb://localhost:27017/openframe
+
+openframe:
+  tenant-isolation:
+    enabled: true
+```
+
+When either flag is `false`, the MongoDB repositories under `com.openframe.data.repository` are not registered, preventing tenant-scoped data access from being wired into the application context.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/clientconfiguration/.OpenFrameClientConfigurationRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/clientconfiguration/.OpenFrameClientConfigurationRepository.md
index feb3868dc..edbef79bf 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/clientconfiguration/.OpenFrameClientConfigurationRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/clientconfiguration/.OpenFrameClientConfigurationRepository.md
@@ -1,38 +1,35 @@
-<!-- source-hash: a35f484ef2c1e8f6c91d65eb0166d5dc -->
-Spring Data MongoDB repository interface for managing `OpenFrameClientConfiguration` documents, providing CRUD operations and a custom query to retrieve the most recent configuration record.
+<!-- source-hash: 25b048b63554061cb063f1b3f6ce39fd -->
+Spring Data MongoDB repository interface for managing `OpenFrameClientConfiguration` documents, providing tenant-aware configuration lookup and retrieval of the most recent configuration entry.
 
 ## Key Components
 
-| Component | Type | Description |
-|-----------|------|-------------|
-| `OpenFrameClientConfigurationRepository` | Interface | Spring `@Repository` extending `MongoRepository` |
-| `findFirstByOrderByCreatedAtDesc()` | Method | Returns the latest configuration sorted by `createdAt` descending |
+| Member | Return Type | Description |
+|--------|-------------|-------------|
+| `findFirstByOrderByCreatedAtDesc()` | `Optional<OpenFrameClientConfiguration>` | Retrieves the most recently created client configuration document |
+| `findByTenantId(String tenantId)` | `Optional<OpenFrameClientConfiguration>` | Looks up a client configuration by its associated tenant ID |
+
+Extends `MongoRepository<OpenFrameClientConfiguration, String>`, inheriting standard CRUD operations with `String` as the document ID type.
 
 ## Usage Example
 
 ```java
 @Service
-public class ClientConfigurationService {
+public class ClientConfigService {
 
     private final OpenFrameClientConfigurationRepository repository;
 
-    public ClientConfigurationService(OpenFrameClientConfigurationRepository repository) {
+    public ClientConfigService(OpenFrameClientConfigurationRepository repository) {
         this.repository = repository;
     }
 
-    public OpenFrameClientConfiguration getLatestConfig() {
-        return repository.findFirstByOrderByCreatedAtDesc()
-                .orElseThrow(() -> new RuntimeException("No client configuration found"));
+    public OpenFrameClientConfiguration getConfigForTenant(String tenantId) {
+        return repository.findByTenantId(tenantId)
+            .orElseThrow(() -> new ConfigNotFoundException("No config found for tenant: " + tenantId));
     }
 
-    public OpenFrameClientConfiguration saveConfig(OpenFrameClientConfiguration config) {
-        return repository.save(config);
+    public OpenFrameClientConfiguration getLatestConfig() {
+        return repository.findFirstByOrderByCreatedAtDesc()
+            .orElseThrow(() -> new ConfigNotFoundException("No client configuration exists"));
     }
 }
-```
-
-## Notes
-
-- Inherits standard CRUD methods (`save`, `findById`, `findAll`, `delete`, etc.) from `MongoRepository`
-- `findFirstByOrderByCreatedAtDesc()` uses Spring Data's derived query mechanism — no manual query annotation required
-- Returns `Optional<OpenFrameClientConfiguration>` to safely handle the case where no configuration document exists in MongoDB
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.CustomNotificationRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.CustomNotificationRepository.md
index 9fbbc1cd6..580c3fc38 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.CustomNotificationRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.CustomNotificationRepository.md
@@ -1,29 +1,16 @@
-<!-- source-hash: f08619d53c809d763e4b3e3abef58522 -->
-Defines a custom MongoDB repository interface for paginated notification queries scoped to a specific recipient.
+<!-- source-hash: d1a8c12d7a1e1f9fff9b08410f0b1d32 -->
+Custom repository interface for cursor-based pagination of notifications filtered by recipient, read status, and search terms.
 
 ## Key Components
 
-| Element | Description |
-|---|---|
-| `CustomNotificationRepository` | Interface extending Spring Data's repository pattern with custom query logic |
-| `findPageForRecipient(...)` | Retrieves a paginated, filterable page of notifications for a given recipient |
-
-### `findPageForRecipient` Parameters
-
-| Parameter | Type | Description |
-|---|---|---|
-| `recipientId` | `String` | Unique identifier of the notification recipient |
-| `recipientType` | `RecipientType` | Enum distinguishing recipient kind (e.g., user, team) |
-| `readFilter` | `Boolean` | Optional filter for read/unread notifications; `null` returns all |
-| `search` | `String` | Optional text search term |
-| `cursor` | `String` | Cursor value for keyset pagination |
-| `backward` | `boolean` | Direction flag; `true` paginates backward |
-| `limit` | `int` | Maximum number of results per page |
+- **`findPageForRecipient(... Sort.Direction direction ...)`** — Full method for fetching a paginated `NotificationPage` with explicit sort direction, supporting forward/backward cursor navigation.
+- **`findPageForRecipient(... int limit)`** *(default)* — Convenience overload that defaults sort direction to `Sort.Direction.DESC`, delegating to the full method.
 
 ## Usage Example
 
 ```java
-NotificationPage page = customNotificationRepository.findPageForRecipient(
+// Forward pagination with default DESC sort
+NotificationPage page = notificationRepository.findPageForRecipient(
     "user-123",
     RecipientType.USER,
     false,       // unread only
@@ -32,6 +19,29 @@ NotificationPage page = customNotificationRepository.findPageForRecipient(
     false,       // forward direction
     20           // page size
 );
+
+// Backward pagination with explicit ASC sort
+NotificationPage prevPage = notificationRepository.findPageForRecipient(
+    "user-123",
+    RecipientType.USER,
+    null,                  // no read filter
+    null,                  // no search
+    "cursor-abc",          // cursor from previous page
+    true,                  // backward
+    Sort.Direction.ASC,
+    20
+);
 ```
 
-> This interface is typically implemented by a `CustomNotificationRepositoryImpl` class using `MongoTemplate` for fine-grained query control, and composed into the main `NotificationRepository` via Spring Data's multi-interface inheritance pattern.
\ No newline at end of file
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `recipientId` | ID of the target user or entity |
+| `recipientType` | Enum distinguishing recipient kinds (e.g., `USER`, `TEAM`) |
+| `readFilter` | `true`/`false` to filter by read status; `null` returns all |
+| `search` | Optional text search against notification content |
+| `cursor` | Opaque pagination cursor; `null` starts from the beginning |
+| `backward` | Traversal direction relative to the cursor |
+| `direction` | Sort order; defaults to `DESC` |
+| `limit` | Maximum number of results per page |
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationContextWriteConverter.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationContextWriteConverter.md
new file mode 100644
index 000000000..df0c2e0a0
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationContextWriteConverter.md
@@ -0,0 +1,45 @@
+<!-- source-hash: 21f5410019b37118a543b5fafcc318be -->
+A Spring Data `@WritingConverter` that serializes a `NotificationContext` object into a MongoDB `Document` for persistence, using Jackson's `ObjectMapper` for JSON conversion.
+
+## Key Components
+
+| Element | Description |
+|---|---|
+| `@WritingConverter` | Marks this as a write-side converter registered with Spring Data MongoDB |
+| `convert(NotificationContext)` | Serializes the source object to JSON, then parses it into a BSON `Document` |
+| `ObjectMapper` | Injected Jackson mapper used for JSON serialization |
+
+## Usage Example
+
+```java
+// Register the converter in your MongoDB configuration
+@Configuration
+public class MongoConfig extends AbstractMongoClientConfiguration {
+
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @Override
+    public MongoCustomConversions customConversions() {
+        return new MongoCustomConversions(List.of(
+            new NotificationContextWriteConverter(objectMapper)
+        ));
+    }
+}
+
+// The converter is then invoked automatically when persisting a document
+// containing a NotificationContext field — no manual invocation needed.
+NotificationContext ctx = new NotificationContext();
+ctx.setType("ALERT");
+notificationRepository.save(notification); // converter fires here
+```
+
+## Error Handling
+
+If Jackson fails to serialize the `NotificationContext`, an `IllegalStateException` is thrown including the context's `type` field to aid debugging — for example:
+
+```text
+IllegalStateException: Failed to serialise NotificationContext (type=ALERT)
+```
+
+> **Note:** A `null` source is handled gracefully, returning `null` rather than throwing an exception.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationReadStateRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationReadStateRepository.md
index 3f63e76ef..4c70a5b67 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationReadStateRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/.NotificationReadStateRepository.md
@@ -1,38 +1,45 @@
-<!-- source-hash: 896e6b913528607e4b470d395f0ff12a -->
-MongoDB repository interface for managing notification read states, providing CRUD operations and bulk update capabilities for tracking per-recipient notification status.
+<!-- source-hash: 791e2d6e32120c8f55fbfabdf3fff431 -->
+MongoDB repository interface for managing notification read state persistence, providing CRUD operations and bulk status update capabilities for tracking per-recipient notification read/unread/deleted states.
 
 ## Key Components
 
 | Method | Description |
 |--------|-------------|
 | `existsByRecipientIdAndRecipientTypeAndStatus` | Checks if a read state record exists for a given recipient and status |
-| `markAsRead` | Marks a specific notification as `READ` for a recipient, setting `readAt` timestamp |
+| `markAsRead` | Atomically marks a single notification as `READ` with a timestamp for a specific recipient |
 | `markAllAsRead` | Bulk-marks all `UNREAD` notifications as `READ` for a recipient |
-| `softDelete` | Soft-deletes a specific notification by setting status to `DELETED` (skips already deleted) |
+| `softDelete` | Soft-deletes a single notification by setting status to `DELETED` (skips already-deleted records) |
 | `softDeleteAllRead` | Bulk soft-deletes all `READ` notifications for a recipient |
-| `unreadCountsByCategory` | Aggregates unread notification counts grouped by category for a recipient |
-
-Extends both `MongoRepository<NotificationReadState, String>` and `CustomNotificationReadStateRepository` for standard CRUD plus custom query support.
+| `unreadCountsByCategory` | Aggregation query returning unread notification counts grouped by category for a tenant-scoped recipient |
 
 ## Usage Example
 
 ```java
-// Check if any unread notifications exist
-boolean hasUnread = repository.existsByRecipientIdAndRecipientTypeAndStatus(
-    "user-123", RecipientType.USER, ReadStatus.UNREAD
-);
-
 // Mark a single notification as read
 long updated = repository.markAsRead("user-123", RecipientType.USER, "notif-456");
 
-// Mark all notifications as read
-long totalMarked = repository.markAllAsRead("user-123", RecipientType.USER);
+// Mark all unread notifications as read for a recipient
+long count = repository.markAllAsRead("user-123", RecipientType.USER);
 
 // Soft-delete a specific notification
 long deleted = repository.softDelete("user-123", RecipientType.USER, "notif-456");
 
-// Get unread counts per category
-List<CategoryCount> counts = repository.unreadCountsByCategory("user-123", RecipientType.USER);
+// Bulk soft-delete all read notifications
+long cleaned = repository.softDeleteAllRead("user-123", RecipientType.USER);
+
+// Get unread counts grouped by category
+List<CategoryCount> counts = repository.unreadCountsByCategory(
+    "user-123",
+    RecipientType.USER,
+    "tenant-001"
+);
+
+// Check for any unread notifications
+boolean hasUnread = repository.existsByRecipientIdAndRecipientTypeAndStatus(
+    "user-123",
+    RecipientType.USER,
+    ReadStatus.UNREAD
+);
 ```
 
-> **Note:** All mutating methods (`markAsRead`, `markAllAsRead`, `softDelete`, `softDeleteAllRead`) use MongoDB's `$set` operator via `@Update`, returning the count of modified documents. Timestamps use MongoDB's `$$NOW` server-side expression for consistency.
\ No newline at end of file
+> All status mutations use MongoDB `$set` with `$$NOW` for server-side timestamping, ensuring atomic updates without read-modify-write cycles. Also extends `CustomNotificationReadStateRepository` for additional query flexibility.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/impl/.CustomNotificationRepositoryImpl.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/impl/.CustomNotificationRepositoryImpl.md
index 11917dd0d..77502a681 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/impl/.CustomNotificationRepositoryImpl.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/notification/impl/.CustomNotificationRepositoryImpl.md
@@ -1,32 +1,44 @@
-<!-- source-hash: b1178f55d6243caffba036108f7c043b -->
-Custom MongoDB repository implementation for paginated notification queries, supporting cursor-based pagination, read-status filtering, and title search for a given recipient.
+<!-- source-hash: 4f635b49dc48ef5c5d46152e653b5c14 -->
+Custom MongoDB repository implementation for paginated, cursor-based notification retrieval. Supports filtering by read status, full-text search, and bidirectional pagination for a given recipient.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `findPageForRecipient` | Public entry point; orchestrates read-state fetch and notification hydration |
-| `fetchReadStates` | Queries `NotificationReadState` collection with filtering, cursor, and sort; returns an ordered `notificationId → ReadStatus` map |
-| `fetchNotificationsPreservingOrder` | Bulk-fetches `Notification` documents by ID, then re-orders results to match the cursor-page order |
-| `applyStatusFilter` | Excludes `DELETED` records by default; filters to `READ` or `UNREAD` when a boolean filter is supplied |
-| `applyCursor` | Appends `lt`/`gt` predicate on `notificationId` to implement keyset (cursor) pagination in both forward and backward directions |
-| `applySearch` | Applies a case-insensitive regex on the `title` field using `Pattern.quote` to prevent injection |
+| Method | Description |
+|--------|-------------|
+| `findPageForRecipient` | Main entry point — builds a `NotificationPage` for a recipient using cursor pagination and optional filters |
+| `fetchReadStates` | Queries `NotificationReadState` collection with all filters applied; returns an ordered map of notification IDs to read statuses |
+| `fetchNotificationsPreservingOrder` | Fetches full `Notification` documents by ID and reorders them to match the cursor-sorted result from `fetchReadStates` |
+| `effectiveDirection` | Flips sort direction when paginating backward |
+| `applyStatusFilter` | Adds a `status` criterion: excludes `DELETED` (no filter), or matches `READ`/`UNREAD` explicitly |
+| `applyCursor` | Appends a `lt`/`gt` bound on `notificationId` depending on sort direction |
+| `applySearch` | Adds a case-insensitive regex filter on the `title` field using `Pattern.quote` to prevent injection |
 
 ## Usage Example
 
 ```java
-// Injected via Spring; called from a service layer
-NotificationPage page = customNotificationRepository.findPageForRecipient(
-    "user-123",          // recipientId
-    RecipientType.USER,  // recipientType
-    false,               // readFilter: null=all, true=read, false=unread
-    "server alert",      // search term (title contains)
-    lastSeenId,          // cursor from previous page
-    false,               // backward=false → newest-first
-    20                   // page size
+// Fetch the first page of unread notifications for a user, newest first
+NotificationPage page = repo.findPageForRecipient(
+    "user-123",
+    RecipientType.USER,
+    false,          // unread only
+    null,           // no search
+    null,           // no cursor (first page)
+    false,          // forward pagination
+    Sort.Direction.DESC,
+    20              // page size
 );
 
-List<NotificationWithStatus> notifications = page.getItems();
+// Fetch the next page using the last seen notification ID as cursor
+NotificationPage nextPage = repo.findPageForRecipient(
+    "user-123",
+    RecipientType.USER,
+    false,
+    null,
+    "663f1a2b4e0a1c0012345678", // cursor from previous page
+    false,
+    Sort.Direction.DESC,
+    20
+);
 ```
 
-> **Design note:** The two-phase fetch (read-state first, then notifications) keeps the pagination index lean and avoids a join, while `LinkedHashMap` preserves the cursor-sorted order across the document lookup.
\ No newline at end of file
+> **Design note:** Pagination is implemented as a two-phase query — read states are fetched first (lightweight), then full notification documents are hydrated in a single `$in` query, preserving cursor order without relying on MongoDB sort stability across collections.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/oauth/.OAuthClientRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/oauth/.OAuthClientRepository.md
index 824592f12..84b4ea2eb 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/oauth/.OAuthClientRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/oauth/.OAuthClientRepository.md
@@ -1,14 +1,15 @@
-<!-- source-hash: 91bc3cba98b545156cc064ff8bf5f29e -->
-Spring Data MongoDB repository interface for managing `OAuthClient` documents, providing standard CRUD operations plus custom lookup methods by client ID and machine ID.
+<!-- source-hash: 9a0be3a9fe29b66f873370db9990410d -->
+MongoDB repository interface for managing `OAuthClient` documents, providing lookup and existence-check operations by `clientId` and `machineId`.
 
 ## Key Components
 
-| Method | Return Type | Description |
-|--------|-------------|-------------|
-| `findByClientId(String clientId)` | `Optional<OAuthClient>` | Retrieves an OAuth client by its unique client ID |
-| `existsByMachineId(String machineId)` | `boolean` | Checks whether an OAuth client is registered for a given machine ID |
+| Method | Description |
+|--------|-------------|
+| `findByClientId(String clientId)` | Retrieves an `OAuthClient` by its OAuth client identifier |
+| `findByMachineId(String machineId)` | Retrieves an `OAuthClient` by its associated machine identifier |
+| `existsByMachineId(String machineId)` | Returns `true` if an `OAuthClient` exists for the given machine identifier |
 
-Inherits all standard MongoDB CRUD operations from `MongoRepository<OAuthClient, String>`.
+Inherits full CRUD operations from `MongoRepository<OAuthClient, String>`.
 
 ## Usage Example
 
@@ -16,19 +17,24 @@ Inherits all standard MongoDB CRUD operations from `MongoRepository<OAuthClient,
 @Service
 public class OAuthClientService {
 
-    private final OAuthClientRepository oAuthClientRepository;
+    private final OAuthClientRepository repository;
 
-    public OAuthClientService(OAuthClientRepository oAuthClientRepository) {
-        this.oAuthClientRepository = oAuthClientRepository;
+    public OAuthClientService(OAuthClientRepository repository) {
+        this.repository = repository;
     }
 
-    public OAuthClient getClient(String clientId) {
-        return oAuthClientRepository.findByClientId(clientId)
-                .orElseThrow(() -> new EntityNotFoundException("OAuth client not found: " + clientId));
+    public OAuthClient getByClientId(String clientId) {
+        return repository.findByClientId(clientId)
+                .orElseThrow(() -> new EntityNotFoundException("Client not found: " + clientId));
     }
 
     public boolean isMachineRegistered(String machineId) {
-        return oAuthClientRepository.existsByMachineId(machineId);
+        return repository.existsByMachineId(machineId);
+    }
+
+    public OAuthClient getByMachineId(String machineId) {
+        return repository.findByMachineId(machineId)
+                .orElseThrow(() -> new EntityNotFoundException("Machine not found: " + machineId));
     }
 }
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepository.md
new file mode 100644
index 000000000..c12d8d4b4
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepository.md
@@ -0,0 +1,35 @@
+<!-- source-hash: ce29b4354d59e1df7c6a1f75f83e4e60 -->
+Defines the custom repository interface for paginated, filterable `Script` document queries backed by `MongoTemplate`, supplementing standard Spring Data derived methods with cursor-based pagination support.
+
+## Key Components
+
+- **`findPageForTenant`** — Core list query scoped to a tenant, supporting optional filter (`ScriptQueryFilter`), regex name search, dynamic sort, and `ObjectId`-based cursor pagination in both forward and backward directions
+- **`isSortableField`** — Guard method to validate that a requested sort field is permitted before passing it to the query
+- **`getDefaultSortField`** — Returns the fallback sort field when none is provided by the caller
+
+## Usage Example
+
+```java
+// Fetch the first page of active scripts, sorted by name ascending
+List<Script> page = customScriptRepository.findPageForTenant(
+    "tenant-abc",            // tenantId
+    ScriptQueryFilter.ACTIVE, // filter
+    "deploy",                // search substring (regex, case-insensitive)
+    "name",                  // sortField
+    Sort.Direction.ASC,      // sortDirection
+    null,                    // cursor = first page
+    false,                   // forward pagination
+    26                       // pageSize + 1 to detect hasNextPage
+);
+
+// Detect if a next page exists
+boolean hasNextPage = page.size() > 25;
+List<Script> results = hasNextPage ? page.subList(0, 25) : page;
+```
+
+## Notes
+
+- Implementation lives in `CustomScriptRepositoryImpl`
+- DELETED records are always excluded regardless of the supplied `filter`
+- For backward pagination (`before`/`last`), the returned list should be **reversed** by the caller before display
+- The cursor is expected as a raw `ObjectId` hex string (base64-decoded by the caller before passing in)
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepositoryImpl.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepositoryImpl.md
new file mode 100644
index 000000000..e37a812ed
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.CustomScriptRepositoryImpl.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 779bf02b0793a3832a5a8b41d46e8e23 -->
+Implements cursor-based pagination queries for `Script` documents in MongoDB, providing tenant-scoped filtering, sorting, and search capabilities backed by `MongoTemplate`.
+
+## Key Components
+
+| Member | Description |
+|--------|-------------|
+| `findPageForTenant()` | Core pagination method — builds a `Query` with all active filters and executes it against MongoDB |
+| `applyStatusFilter()` | Filters by script status; defaults to excluding `DELETED` documents via `$ne` |
+| `applyShellsFilter()` | Restricts results to specified shell types |
+| `applyPlatformsFilter()` | Matches scripts whose `supportedPlatforms` array contains any of the requested values |
+| `applyTagFilter()` | Case-insensitive exact tag match using an anchored, quoted regex |
+| `applySearch()` | Case-insensitive substring match on `name` using `Pattern.quote` to escape user input |
+| `applyCursor()` | Parses a hex `ObjectId` cursor and applies `$lt`/`$gt` based on sort + pagination direction |
+| `isSortableField()` | Validates a field against the allowlist: `_id`, `name`, `createdAt`, `updatedAt` |
+| `getDefaultSortField()` | Returns `_id` as the fallback sort field |
+| `flip()` | Inverts sort direction for backward pagination |
+
+## Usage Example
+
+```java
+List<Script> page = customScriptRepository.findPageForTenant(
+    "tenant-123",
+    ScriptQueryFilter.builder()
+        .statuses(List.of(ScriptStatus.ACTIVE))
+        .shells(List.of("bash", "powershell"))
+        .supportedPlatforms(List.of("LINUX"))
+        .tag("monitoring")
+        .build(),
+    "deploy",                  // search term (substring match on name)
+    "_id",                     // sortField
+    Sort.Direction.DESC,       // sortDirection
+    "64f1a2b3c4d5e6f7a8b9c0d1", // cursor (ObjectId hex)
+    false,                     // backward
+    25                         // limit
+);
+```
+
+> **Cursor behavior:** An invalid or blank cursor is silently treated as "no cursor", returning the first page. Direction logic uses XOR between `sortDirection` and `backward` to determine `$lt` vs `$gt` comparisons, ensuring consistent ordering across forward and backward traversal.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.ScriptRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.ScriptRepository.md
new file mode 100644
index 000000000..138a3013e
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/rmm/.ScriptRepository.md
@@ -0,0 +1,38 @@
+<!-- source-hash: fc2449b4edfd9ce19017ed90f52c94c5 -->
+Tenant-scoped MongoDB repository interface for managing `Script` documents within the RMM (Remote Monitoring & Management) module.
+
+## Key Components
+
+| Method | Description |
+|--------|-------------|
+| `findByTenantIdAndId` | Retrieves a single script by its document ID, scoped to a tenant |
+| `findByTenantIdAndName` | Retrieves a script by name using the compound `(tenantId, name)` unique index |
+| `existsByTenantIdAndName` | Checks for name uniqueness within a tenant |
+| `existsByTenantIdAndNameAndIdNot` | Checks for name conflicts excluding a specific document (useful for update validation) |
+| `deleteByTenantIdAndId` | Hard-deletes a script by ID within a tenant; returns `0` or `1` |
+
+> List and pagination operations are handled by `CustomScriptRepository` via MongoTemplate for cursor-style paging.
+
+## Usage Example
+
+```java
+@Service
+@RequiredArgsConstructor
+public class ScriptService {
+
+    private final ScriptRepository scriptRepository;
+
+    public Script getScript(String tenantId, String scriptId) {
+        return scriptRepository.findByTenantIdAndId(tenantId, scriptId)
+                .orElseThrow(() -> new ScriptNotFoundException(scriptId));
+    }
+
+    public boolean isNameAvailable(String tenantId, String name, String excludeId) {
+        return !scriptRepository.existsByTenantIdAndNameAndIdNot(tenantId, name, excludeId);
+    }
+
+    public long removeScript(String tenantId, String scriptId) {
+        return scriptRepository.deleteByTenantIdAndId(tenantId, scriptId);
+    }
+}
+```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepository.md
index fc4b6fde5..4d9fb7930 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepository.md
@@ -1,40 +1,44 @@
-<!-- source-hash: 5d69d4ca00989c98ee974aad0491f86c -->
-Custom MongoDB query interface for ticket data access, providing advanced filtering, cursor-based pagination, bulk operations, and analytics beyond standard Spring Data repository capabilities.
+<!-- source-hash: b6323135bc72436b88e87ed51467330d -->
+Custom repository interface extending ticket data access with advanced querying, filtering, cursor-based pagination, and bulk operation capabilities for MongoDB-backed ticket management.
 
 ## Key Components
 
 | Method | Description |
 |--------|-------------|
-| `buildTicketQuery(...)` | Constructs a MongoDB `Query` from a `TicketQueryFilter`, with optional search, ID restriction, and machine owner filtering. Overloaded default for filter-only use. |
-| `findTicketsWithCursor(...)` | Retrieves a paginated list of tickets using cursor-based pagination with configurable sort field and direction. |
-| `countTickets(Query)` | Returns the total count of tickets matching a given query. |
-| `countTicketsByStatus()` | Returns a `Map<TicketStatus, Long>` aggregating ticket counts grouped by status. |
-| `getTotalCount()` | Returns the overall ticket count in the collection. |
-| `getAverageResolutionTimeMs()` | Returns an `Optional<Long>` representing the average ticket resolution time in milliseconds. |
-| `updateStatusBulk(...)` | Bulk-updates tickets from one status to another, returning the number of modified documents. |
-| `updateTitle(...)` | Updates the title of a specific ticket by ID. |
-| `isSortableField(String)` | Validates whether a given field name is allowed for sorting. |
-| `getDefaultSortField()` | Returns the default field used for ticket sorting. |
+| `buildTicketQuery(filter)` | Default overload — builds a `Query` from a `TicketQueryFilter` with no search, restrictions, or owner constraints |
+| `buildTicketQuery(filter, search, restrictToTicketIds, ownerMachineId)` | Full query builder supporting text search, ticket ID allowlist, and machine owner scoping |
+| `findTicketsWithCursor(query, cursor, limit, sortField, sortDirection)` | Cursor-based paginated ticket retrieval with configurable sort |
+| `countTickets(query)` | Returns total count matching a given `Query` |
+| `countTicketsByStatus()` | Aggregates ticket counts grouped by `TicketStatus` |
+| `countTicketsByStatusKind()` | Aggregates ticket counts grouped by `TicketStatusKind` |
+| `countTicketsByStatusId()` | Aggregates ticket counts keyed by raw status ID string |
+| `getTotalCount()` | Returns the total number of tickets in the collection |
+| `getAverageResolutionTimeMs()` | Computes average time-to-resolution in milliseconds (may be absent) |
+| `updateStatusBulk(fromStatus, toStatus)` | Bulk-transitions all tickets from one status to another; returns affected count |
+| `reassignTicketsToStatus(fromStatusId, toStatusId, toKind)` | Reassigns tickets between status IDs and updates the status kind |
+| `updateTitle(ticketId, title)` | Updates the title of a single ticket by ID |
+| `isSortableField(field)` | Validates whether a field name is eligible for sorting |
+| `getDefaultSortField()` | Returns the default sort field used when none is specified |
 
 ## Usage Example
 
 ```java
-// Build a filtered query and paginate with cursor
+// Build a filtered query with search and pagination
 Query query = ticketRepository.buildTicketQuery(
-    filter, "network issue", List.of("t1", "t2"), "machine-42"
+    filter,
+    "network outage",
+    List.of("TKT-001", "TKT-002"),
+    "machine-abc123"
 );
 
+// Paginate using a cursor
 List<Ticket> page = ticketRepository.findTicketsWithCursor(
-    query, lastCursorId, 25, "createdAt", "DESC"
+    query, "cursor_xyz", 25, "createdAt", "DESC"
 );
 
-// Aggregate ticket counts by status
-Map<TicketStatus, Long> statusCounts = ticketRepository.countTicketsByStatus();
+// Bulk status transition (e.g., auto-close stale open tickets)
+int affected = ticketRepository.updateStatusBulk(openStatus, closedStatus);
 
-// Bulk-close all open tickets
-int updated = ticketRepository.updateStatusBulk(TicketStatus.OPEN, TicketStatus.CLOSED);
-
-// Fetch average resolution time
-ticketRepository.getAverageResolutionTimeMs()
-    .ifPresent(ms -> log.info("Avg resolution: {}ms", ms));
+// Aggregate counts for a dashboard
+Map<TicketStatusKind, Long> kindCounts = ticketRepository.countTicketsByStatusKind();
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepositoryImpl.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepositoryImpl.md
index 066674f19..854179007 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepositoryImpl.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.CustomTicketRepositoryImpl.md
@@ -1,45 +1,44 @@
-<!-- source-hash: 4ba47c95191b51d3fb8cd2fddcabb86f -->
-Custom MongoDB repository implementation for the `Ticket` document, providing advanced query building, cursor-based pagination, aggregation analytics, and bulk update operations beyond standard Spring Data capabilities.
+<!-- source-hash: e19cae3864f4995c97e609eb045a30fd -->
+Custom MongoDB repository implementation for ticket querying, providing advanced filtering, cursor-based pagination, and aggregation-based counting operations on the `Ticket` collection.
 
 ## Key Components
 
 | Method | Description |
 |--------|-------------|
-| `buildTicketQuery()` | Constructs a dynamic MongoDB `Query` from filter criteria, search terms, ticket ID restrictions, and machine owner constraints |
-| `findTicketsWithCursor()` | Executes cursor-based paginated queries with configurable sort field and direction |
-| `countTickets()` | Returns total count for a pre-built query |
-| `countTicketsByStatus()` | Aggregates ticket counts grouped by `TicketStatus` enum values |
-| `getAverageResolutionTimeMs()` | Computes average resolution time (ms) across all resolved tickets using MongoDB aggregation |
-| `updateStatusBulk()` | Bulk-updates ticket status from one state to another, returning modified count |
-| `updateTitle()` | Updates the title of a single ticket by ID |
-| `isSortableField()` | Validates whether a given field name is in the allowed sort fields list |
-
-**Supported sortable fields:** `_id`, `ticketNumber`, `status`, `organizationName`, `assignedName`, `deviceHostname`, `createdAt`, `updatedAt`, `resolvedAt`, `order`
+| `buildTicketQuery()` | Constructs a `Query` from a `TicketQueryFilter`, optional free-text search, ticket ID restrictions, and owner machine ID |
+| `findTicketsWithCursor()` | Executes cursor-based pagination with configurable sort field/direction |
+| `countTickets()` | Returns total count for a given query |
+| `countTicketsByStatus()` | Aggregates ticket counts grouped by `TicketStatus` enum |
+| `countTicketsByStatusKind()` | Aggregates ticket counts grouped by `TicketStatusKind` enum |
+| `countTicketsByStatusId()` | Aggregates ticket counts grouped by raw status ID string |
+
+**Internal helpers:**
+- `applySearchCriteria()` — case-insensitive regex search across title, hostname, org name, and assignee name
+- `applyCursorCriteria()` — builds stable keyset pagination criteria handling tie-breaking by `_id`
+- `getSortFieldValue()` — reflective-style field extraction from a `Ticket` instance for cursor comparison
 
 ## Usage Example
 
 ```java
-// Build a filtered query
+// Build a filtered, paginated query
 TicketQueryFilter filter = TicketQueryFilter.builder()
-        .statuses(List.of(TicketStatus.OPEN))
-        .organizationIds(List.of("org-123"))
-        .createdAtFrom(Instant.now().minus(7, ChronoUnit.DAYS))
-        .build();
-
-Query query = repo.buildTicketQuery(filter, "printer", null, null);
-
-// Fetch first page (cursor-based)
-List<Ticket> page1 = repo.findTicketsWithCursor(query, null, 20, "createdAt", "DESC");
-
-// Fetch next page using last ticket's ID as cursor
-List<Ticket> page2 = repo.findTicketsWithCursor(query, page1.getLast().getId(), 20, "createdAt", "DESC");
-
-// Analytics
-Map<TicketStatus, Long> counts = repo.countTicketsByStatus();
-Optional<Long> avgMs = repo.getAverageResolutionTimeMs();
-
-// Bulk status transition
-int updated = repo.updateStatusBulk(TicketStatus.OPEN, TicketStatus.CLOSED);
+    .statusKinds(List.of(TicketStatusKind.OPEN))
+    .organizationIds(List.of("org-123"))
+    .build();
+
+Query query = repo.buildTicketQuery(filter, "network", null, null);
+
+List<Ticket> page = repo.findTicketsWithCursor(
+    query,
+    "64f1a2b3c4d5e6f7a8b9c0d1", // cursor (last seen _id)
+    25,                          // page size
+    "createdAt",                 // sort field
+    "DESC"                       // sort direction
+);
+
+// Aggregate counts by status
+Map<TicketStatus, Long> statusCounts = repo.countTicketsByStatus();
+// e.g. { OPEN=42, CLOSED=17, IN_PROGRESS=8 }
 ```
 
-> **Cursor pagination note:** When sorting by a non-ID field, the cursor fetches the pivot document to retrieve its sort value, then applies a compound OR predicate (`past sort value OR same sort value + past ID`) to ensure stable, gap-free pagination.
\ No newline at end of file
+> **Note:** Cursor-based pagination uses keyset logic — when sorting by a non-ID field, ties are broken by `_id` to ensure stable, gap-free page traversal across concurrent writes.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketRepository.md
index c7e3c8938..d5a762e2d 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketRepository.md
@@ -1,39 +1,50 @@
-<!-- source-hash: 74f2b8aed48a3cb8e4dd79d267b54427 -->
-MongoDB repository interface for `Ticket` documents, providing standard CRUD operations alongside specialized query and aggregation methods for ticket lookup, filtering, and kanban-style ordering.
+<!-- source-hash: bd8375dbc95ade2d55248b43c1898020 -->
+MongoDB repository interface for `Ticket` documents, providing both standard CRUD operations and specialized aggregation queries for ticket management within the OpenFrame platform.
 
 ## Key Components
 
-| Method | Type | Description |
-|--------|------|-------------|
-| `findByTicketNumber` | `@Query` (derived) | Lookup a ticket by its human-readable number |
-| `findByStatus` | Derived | Fetch all tickets matching a given `TicketStatus` |
-| `findByOrganizationId` | Derived | Retrieve tickets scoped to an organization |
-| `findByAssignedTo` | Derived | List tickets assigned to a specific technician |
-| `findByDeviceId` | Derived | Fetch tickets linked to a device |
-| `findByIdIn` | Derived | Bulk fetch tickets by a list of IDs |
-| `findByIdAndOwnerMachineId` | `@Query` | Secure lookup combining ticket ID and machine owner |
-| `findFirstInColumn` | `@Aggregation` | Retrieves the first ordered ticket in a status column |
-| `findLastInColumn` | `@Aggregation` | Retrieves the last ordered ticket in a status column |
-| `findFirstAfter` | `@Aggregation` | Gets the next ticket after a given order value |
-| `findFirstBefore` | `@Aggregation` | Gets the previous ticket before a given order value |
+### Legacy Methods (lifecycle feature flag OFF)
+
+| Method | Description |
+|--------|-------------|
+| `findByTicketNumber(Integer)` | Lookup a single ticket by its human-readable number |
+| `findByStatus(TicketStatus)` | Retrieve all tickets matching an enum status |
+| `findByOrganizationId(String)` | Fetch tickets scoped to an organization |
+| `findByAssignedTo(String)` | Fetch tickets assigned to a specific user |
+| `findByDeviceId(String)` | Fetch tickets linked to a device |
+| `findByIdIn(List<String>)` | Batch-fetch tickets by a list of IDs |
+| `findByIdAndOwnerMachineId(String, String)` | Find a ticket by ID and owner machine (custom `@Query`) |
+| `findFirstInColumn` / `findLastInColumn` | Get first/last ordered ticket in a status column |
+| `findFirstAfter` / `findFirstBefore` | Navigate adjacent tickets by `order` field |
+
+### Lifecycle Methods (lifecycle feature flag ON)
+
+Uses `statusId` (String) instead of `TicketStatus` enum, enabling dynamic status configurations.
+
+| Method | Description |
+|--------|-------------|
+| `countByStatusId(String)` | Count tickets in a given lifecycle status |
+| `findFirstInColumnByStatusId` | First ordered ticket for a `statusId`/tenant pair |
+| `findFirstAfterByStatusId` | Next ticket after a given order value |
+| `findFirstBeforeByStatusId` | Previous ticket before a given order value |
 
 ## Usage Example
 
 ```java
-// Fetch all open tickets for an organization
+// Legacy: fetch open tickets for an organization
 List<Ticket> openTickets = ticketRepository.findByStatus(TicketStatus.OPEN);
 
-// Find a specific ticket by number
-Optional<Ticket> ticket = ticketRepository.findByTicketNumber(1042);
-
-// Kanban board: find the bottom ticket in the IN_PROGRESS column
-Optional<Ticket> last = ticketRepository.findLastInColumn(TicketStatus.IN_PROGRESS);
+// Kanban navigation: find the first ticket in a column
+Optional<Ticket> first = ticketRepository
+    .findFirstInColumn(TicketStatus.IN_PROGRESS, "tenant-123");
 
-// Find the next ticket after a given order position (for drag-and-drop reordering)
-Optional<Ticket> next = ticketRepository.findFirstAfter(TicketStatus.OPEN, "order_abc123");
+// Lifecycle mode: navigate to the next ticket after a given order
+Optional<Ticket> next = ticketRepository
+    .findFirstAfterByStatusId("status-abc", "order-xyz", "tenant-123");
 
-// Validate ticket ownership by machine
-Optional<Ticket> owned = ticketRepository.findByIdAndOwnerMachineId(ticketId, machineId);
+// Custom query: validate ticket ownership by machine
+Optional<Ticket> ticket = ticketRepository
+    .findByIdAndOwnerMachineId("ticket-id", "machine-id");
 ```
 
-> The aggregation methods (`findFirstInColumn`, `findLastInColumn`, `findFirstAfter`, `findFirstBefore`) power kanban board ordering logic, enabling precise ticket positioning within status columns.
\ No newline at end of file
+> **Note:** Legacy methods using `TicketStatus` enum are scheduled for removal after the lifecycle feature flag rollout is complete. Prefer `*ByStatusId` variants in new code.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketStatusDefinitionRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketStatusDefinitionRepository.md
new file mode 100644
index 000000000..5753497bd
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/ticket/.TicketStatusDefinitionRepository.md
@@ -0,0 +1,46 @@
+<!-- source-hash: f7c72221ddb5f5539bc1524347d5fc80 -->
+MongoDB repository interface for managing `TicketStatusDefinition` documents, providing CRUD operations and custom queries for ticket status configurations in the OpenFrame platform.
+
+## Key Components
+
+| Method | Description |
+|--------|-------------|
+| `findAllByOrderByPositionAsc()` | Retrieves all status definitions sorted by position |
+| `findByKind(TicketStatusKind kind)` | Looks up a single status definition by its kind enum |
+| `findByName(String name)` | Looks up a single status definition by name |
+| `findByKindOrderByPositionAsc(TicketStatusKind kind)` | Retrieves all statuses of a specific kind, ordered by position |
+| `countByKind(TicketStatusKind kind)` | Returns the count of statuses for a given kind |
+| `existsByName(String name)` | Checks whether a status definition with the given name exists |
+
+## Usage Example
+
+```java
+@Service
+public class TicketStatusService {
+
+    private final TicketStatusDefinitionRepository statusRepository;
+
+    public TicketStatusService(TicketStatusDefinitionRepository statusRepository) {
+        this.statusRepository = statusRepository;
+    }
+
+    public List<TicketStatusDefinition> getOpenStatuses() {
+        // Fetch all "OPEN" kind statuses in display order
+        return statusRepository.findByKindOrderByPositionAsc(TicketStatusKind.OPEN);
+    }
+
+    public void createStatus(TicketStatusDefinition newStatus) {
+        // Guard against duplicate names before persisting
+        if (statusRepository.existsByName(newStatus.getName())) {
+            throw new IllegalArgumentException("Status name already exists: " + newStatus.getName());
+        }
+        statusRepository.save(newStatus);
+    }
+}
+```
+
+## Notes
+
+- Extends `MongoRepository<TicketStatusDefinition, String>` — inherits full Spring Data CRUD and pagination support
+- Query methods are resolved at runtime by Spring Data MongoDB via method name conventions — no manual query definitions needed
+- `TicketStatusKind` is an enum that categorizes statuses (e.g., `OPEN`, `CLOSED`, `PENDING`)
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/tool/.IntegratedToolRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/tool/.IntegratedToolRepository.md
index b2d5c01be..ceea06c9c 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/tool/.IntegratedToolRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/tool/.IntegratedToolRepository.md
@@ -1,24 +1,28 @@
-<!-- source-hash: c4c593dc736ef4f13a602c3aeffe272c -->
-Spring Data MongoDB repository interface for managing `IntegratedTool` documents, providing CRUD operations and custom query support for integrated MSP tools within the OpenFrame platform.
+<!-- source-hash: 79936f65794d10dedb7e9a0532c370cf -->
+MongoDB repository interface for managing `IntegratedTool` documents, providing standard CRUD operations alongside custom and base lookup methods.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `MongoRepository<IntegratedTool, String>` | Base Spring Data MongoDB CRUD operations |
-| `BaseIntegratedToolRepository` | Generic base interface typed for `Optional<IntegratedTool>`, `Boolean`, and `String` |
-| `CustomIntegratedToolRepository` | Custom query extensions for tool-specific operations |
-| `findByType(String type)` | Derived query method returning an `Optional<IntegratedTool>` by tool type |
+| Element | Description |
+|---|---|
+| `IntegratedToolRepository` | Main repository interface extending Spring Data MongoDB and custom base interfaces |
+| `findByType(String type)` | Retrieves an `IntegratedTool` by its tool type identifier |
+| `findByKey(String key)` | Retrieves an `IntegratedTool` by its unique key |
+
+**Extends:**
+- `MongoRepository<IntegratedTool, String>` — standard Spring Data CRUD operations
+- `BaseIntegratedToolRepository<Optional<IntegratedTool>, Boolean, String>` — shared base query contracts
+- `CustomIntegratedToolRepository` — project-specific custom query logic
 
 ## Usage Example
 
 ```java
 @Service
-public class IntegratedToolService {
+public class ToolService {
 
     private final IntegratedToolRepository toolRepository;
 
-    public IntegratedToolService(IntegratedToolRepository toolRepository) {
+    public ToolService(IntegratedToolRepository toolRepository) {
         this.toolRepository = toolRepository;
     }
 
@@ -27,18 +31,11 @@ public class IntegratedToolService {
                 .orElseThrow(() -> new ToolNotFoundException("No tool found for type: " + type));
     }
 
-    public IntegratedTool saveTool(IntegratedTool tool) {
-        return toolRepository.save(tool);
-    }
-
-    public boolean toolExists(String id) {
-        return toolRepository.existsById(id);
+    public IntegratedTool getToolByKey(String key) {
+        return toolRepository.findByKey(key)
+                .orElseThrow(() -> new ToolNotFoundException("No tool found for key: " + key));
     }
 }
 ```
 
-## Notes
-
-- Annotated with `@Repository` for Spring component scanning and exception translation
-- `findByType` returns `Optional<IntegratedTool>` to safely handle missing tool configurations
-- Inherits the full Spring Data MongoDB query API alongside any custom repository logic defined in `CustomIntegratedToolRepository`
\ No newline at end of file
+Both lookup methods return `Optional<IntegratedTool>`, ensuring null-safe handling when a tool is not found in the MongoDB collection.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/toolagent/.IntegratedToolAgentRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/toolagent/.IntegratedToolAgentRepository.md
index 934d7ab95..a6f2ba1f9 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/toolagent/.IntegratedToolAgentRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/toolagent/.IntegratedToolAgentRepository.md
@@ -1,13 +1,13 @@
-<!-- source-hash: f21874dfb02332dbe9ac192b6ae5bffe -->
-MongoDB repository interface for managing `IntegratedToolAgent` documents, providing data access operations for tool agents within the OpenFrame platform.
+<!-- source-hash: 3d482729127d8ff974e60a72e979fbed -->
+MongoDB repository interface for managing `IntegratedToolAgent` documents, providing query methods for filtering agents by status, release version, and unique key.
 
 ## Key Components
 
-| Component | Type | Description |
-|-----------|------|-------------|
-| `IntegratedToolAgentRepository` | Interface | Spring Data MongoDB repository extending `MongoRepository<IntegratedToolAgent, String>` |
-| `findByStatus` | Query Method | Retrieves all tool agents matching a given `ToolAgentStatus` |
-| `findByReleaseVersionTrue` | Query Method | Retrieves all tool agents flagged as release versions |
+| Method | Description |
+|--------|-------------|
+| `findByStatus(ToolAgentStatus status)` | Retrieves all tool agents matching a given `ToolAgentStatus` enum value |
+| `findByReleaseVersionTrue()` | Returns all agents flagged as a release version |
+| `findByKey(String key)` | Looks up a single agent by its unique string key, returning an `Optional` |
 
 ## Usage Example
 
@@ -21,21 +21,18 @@ public class ToolAgentService {
         this.repository = repository;
     }
 
-    // Fetch all active tool agents
     public List<IntegratedToolAgent> getActiveAgents() {
         return repository.findByStatus(ToolAgentStatus.ACTIVE);
     }
 
-    // Fetch only release-ready agents
-    public List<IntegratedToolAgent> getReleaseAgents() {
+    public List<IntegratedToolAgent> getReleasedAgents() {
         return repository.findByReleaseVersionTrue();
     }
+
+    public Optional<IntegratedToolAgent> getAgentByKey(String key) {
+        return repository.findByKey(key);
+    }
 }
 ```
 
-## Notes
-
-- Annotated with `@Repository`, enabling Spring component scanning and exception translation.
-- Inherits standard CRUD operations (`save`, `findById`, `deleteById`, etc.) from `MongoRepository`.
-- Query methods follow Spring Data naming conventions — no manual query definitions required.
-- `ToolAgentStatus` is an enum used to filter agents by lifecycle state (e.g., `ACTIVE`, `INACTIVE`).
\ No newline at end of file
+> Standard CRUD operations (`save`, `findById`, `deleteById`, etc.) are inherited from `MongoRepository<IntegratedToolAgent, String>` and require no additional implementation.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/version/.ReleaseVersionRepository.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/version/.ReleaseVersionRepository.md
index 7c754278e..3d4e5f36f 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/version/.ReleaseVersionRepository.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/repository/version/.ReleaseVersionRepository.md
@@ -1,12 +1,12 @@
-<!-- source-hash: cec5abcffce2fa84cf67155c4299fe36 -->
-Spring Data MongoDB repository interface for managing `ReleaseVersion` documents, designed to maintain a single document representing the current release version of the application.
+<!-- source-hash: ada1d56db14219ef0803c6fb21ea5d52 -->
+MongoDB repository interface for `ReleaseVersion` document operations, providing tenant-scoped access to the single release version record stored per tenant.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `ReleaseVersionRepository` | Extends `MongoRepository<ReleaseVersion, String>` providing standard CRUD operations |
-| `findFirstByOrderByCreatedAtAsc()` | Retrieves the oldest (and expected sole) release version document, ordered by creation date ascending |
+| Method | Description |
+|--------|-------------|
+| `findFirstByOrderByCreatedAtAsc()` | Retrieves the earliest release version document ordered by creation date |
+| `findFirstBy()` | Returns the single release version for the current tenant; automatically scoped by `TenantAwareMongoTemplate` |
 
 ## Usage Example
 
@@ -21,18 +21,19 @@ public class ReleaseVersionService {
     }
 
     public ReleaseVersion getCurrentVersion() {
-        return releaseVersionRepository.findFirstByOrderByCreatedAtAsc()
-                .orElseThrow(() -> new RuntimeException("No release version found"));
+        return releaseVersionRepository.findFirstBy()
+                .orElseThrow(() -> new IllegalStateException("No release version found for tenant"));
     }
 
-    public ReleaseVersion initializeVersion(ReleaseVersion version) {
-        return releaseVersionRepository.save(version);
+    public ReleaseVersion getEarliestVersion() {
+        return releaseVersionRepository.findFirstByOrderByCreatedAtAsc()
+                .orElseThrow(() -> new IllegalStateException("No release version records found"));
     }
 }
 ```
 
 ## Notes
 
-- The repository follows the **singleton document pattern** — only one `ReleaseVersion` document is expected to exist in the collection at any time.
-- `findFirstByOrderByCreatedAtAsc()` uses Spring Data's derived query mechanism, sorting by `createdAt` ascending to consistently return the earliest record if duplicates exist.
-- Standard inherited methods from `MongoRepository` (e.g., `save()`, `delete()`, `findAll()`) are also available.
\ No newline at end of file
+- Extends `MongoRepository<ReleaseVersion, String>` — inherits standard CRUD operations
+- Designed to maintain a **single document per tenant**; `TenantAwareMongoTemplate` handles automatic tenant scoping on `findFirstBy()`
+- Both methods return `Optional<ReleaseVersion>` — callers should handle the empty case explicitly
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/seed/ticket/.TicketStatusSeedCatalog.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/seed/ticket/.TicketStatusSeedCatalog.md
new file mode 100644
index 000000000..61194fee4
--- /dev/null
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/seed/ticket/.TicketStatusSeedCatalog.md
@@ -0,0 +1,30 @@
+<!-- source-hash: d890c632307490d97d64863293c3d84d -->
+Defines the seed catalog for default ticket status definitions used during system initialization, providing pre-configured statuses with names, colors, and LexoRank-based ordering positions.
+
+## Key Components
+
+**Constants**
+- `NAME_*` — Display names for built-in statuses: `AI Assistance`, `Tech Required`, `Resolved`, `Archived`, `On Hold`
+- `COLOR_*` — Hex color codes associated with each status (e.g., `#B39DDB` for AI Assistance, `#5EA62E` for Resolved)
+
+**Methods**
+- `systemStatuses()` — Returns an ordered `List<TicketStatusDefinition>` of the four core system statuses, with LexoRank positions generated relative to a middle anchor: `AI Assistance → Tech Required → [middle] → Resolved → Archived`
+- `onHoldCustom()` — Returns a single `CUSTOM`-kind `On Hold` status placed at the LexoRank middle position, used as an example or default custom status
+
+## Usage Example
+
+```java
+// Seed system-wide default statuses on tenant initialization
+List<TicketStatusDefinition> defaults = TicketStatusSeedCatalog.systemStatuses();
+ticketStatusRepository.saveAll(defaults);
+
+// Optionally seed a custom "On Hold" status
+TicketStatusDefinition onHold = TicketStatusSeedCatalog.onHoldCustom();
+ticketStatusRepository.save(onHold);
+```
+
+## Notes
+
+- The class is `final` with a private constructor — it is a non-instantiable utility class
+- LexoRank ordering ensures statuses render in a meaningful default sequence without requiring numeric indices
+- `CUSTOM` kind on `onHoldCustom()` signals that tenant operators can modify or remove it, unlike system-locked statuses
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolAgentService.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolAgentService.md
index 1c3e9df8d..42f3e6223 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolAgentService.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolAgentService.md
@@ -1,40 +1,35 @@
-<!-- source-hash: 8e138eabbfcd009614dcd531e2333870 -->
-Service layer for managing `IntegratedToolAgent` documents, handling CRUD operations, publish state transitions, and configuration synchronization with optimistic locking retry support.
+<!-- source-hash: a422455374d250704ca396ba4cb853f4 -->
+Service layer for managing `IntegratedToolAgent` MongoDB documents, handling CRUD operations, configuration synchronization, versioning, and publish-state lifecycle for tool agents in the OpenFrame platform.
 
 ## Key Components
 
 | Method | Description |
-|--------|-------------|
-| `getAll()` | Returns all tool agents |
-| `getAllEnabled()` | Returns only agents with `ENABLED` status |
-| `findById(String)` / `getById(String)` | Lookup by ID; `getById` throws if not found |
-| `findByReleaseVersionTrue()` | Returns agents flagged as release versions |
-| `markAsPublished(agent)` / `markAsNonPublished(agent)` | Transitions publish state and persists |
-| `updateConfigurationFields(configuration)` | Upserts an agent from a configuration object; creates if absent, merges if present |
-| `updateReleaseAgentVersion(id, newVersion)` | Updates version on release agents and marks them pending publish |
-| `mergeAndSave(existing, configuration)` | Detects version/asset drift and sets publish state to `pending` accordingly |
-| `hasAssetChanges(existing, configuration)` | Compares asset versions by ID to detect changes |
+|---|---|
+| `getAll()` / `getAllEnabled()` | Fetch all agents or only those with `ENABLED` status |
+| `findByKey(String)` / `getByKey(String)` | Look up agents by human-readable key (e.g. `"fleetmdm-agent"`) |
+| `findByUuid(String)` / `getByUuid(String)` | Look up agents by MongoDB document UUID |
+| `findById` / `getById` | **Deprecated** — prefer key or UUID variants |
+| `updateConfigurationFields(...)` | Upsert an agent from a configuration object; triggers publish-state changes on version/asset drift |
+| `updateReleaseAgentVersion(...)` | Bumps the version on a release-flagged agent and marks it `pending` for publish |
+| `markAsPublished(...)` / `markAsNonPublished(...)` | Transition agent publish state |
+| `hasAssetChanges(...)` | Detects asset version drift between existing agent and incoming configuration |
+
+Both `updateConfigurationFields` and `updateReleaseAgentVersion` are annotated with `@RetryOnOptimisticLockingFailure` to handle concurrent MongoDB write conflicts.
 
 ## Usage Example
 
 ```java
-// Upsert an agent from a configuration (create or merge)
-IntegratedToolAgentConfiguration config = loadConfiguration();
+// Upsert agent from a configuration payload
+IntegratedToolAgentConfiguration config = loadFromRegistry("fleetmdm-agent");
 integratedToolAgentService.updateConfigurationFields(config);
 
-// Mark a release agent's version as updated
-integratedToolAgentService.updateReleaseAgentVersion("agent-123", "2.1.0");
+// Fetch enabled agents for runtime dispatch
+List<IntegratedToolAgent> active = integratedToolAgentService.getAllEnabled();
 
-// Retrieve all enabled agents
-List<IntegratedToolAgent> activeAgents = integratedToolAgentService.getAllEnabled();
+// Promote a release agent to a new version
+integratedToolAgentService.updateReleaseAgentVersion(agentUuid, "2.1.0");
 
-// Transition publish state
-IntegratedToolAgent agent = integratedToolAgentService.getById("agent-123");
+// Publish state transitions
+IntegratedToolAgent agent = integratedToolAgentService.getByKey("fleetmdm-agent");
 integratedToolAgentService.markAsPublished(agent);
-```
-
-## Notes
-
-- `updateConfigurationFields` and `updateReleaseAgentVersion` are annotated with `@RetryOnOptimisticLockingFailure` to handle concurrent write conflicts safely.
-- Publish state is automatically set to `pending` when a non-release agent's version or assets change during a merge.
-- Release agents (`isReleaseVersion() == true`) have their version managed separately via `updateReleaseAgentVersion` and are skipped during standard configuration version writes.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolService.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolService.md
index 53a2a55f1..83d61d34f 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolService.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.IntegratedToolService.md
@@ -1,43 +1,35 @@
-<!-- source-hash: 1c3514df58b6e4fa3fe7a8962156f0d3 -->
-Provides CRUD operations for managing `IntegratedTool` documents in the OpenFrame platform, enabling retrieval and persistence of integrated MSP tool configurations.
+<!-- source-hash: d284a8e1eebe76c19d38cd9c94d53cc1 -->
+Spring `@Service` bean that provides CRUD and lookup operations for `IntegratedTool` documents stored in MongoDB, conditionally enabled via the `openframe.integration.tool.enabled` property.
 
 ## Key Components
 
-| Method | Return Type | Description |
-|--------|-------------|-------------|
-| `getAllTools()` | `List<IntegratedTool>` | Retrieves all registered integrated tools |
-| `getTool(String toolType)` | `Optional<IntegratedTool>` | Looks up a tool by its type identifier |
-| `getToolById(String toolId)` | `Optional<IntegratedTool>` | Looks up a tool by its unique document ID |
-| `saveTool(IntegratedTool tool)` | `IntegratedTool` | Persists a new or updated tool configuration |
+| Method | Description |
+|--------|-------------|
+| `getAllTools()` | Returns all `IntegratedTool` documents for the current tenant |
+| `getTool(String toolType)` | Looks up a tool by its **type** field |
+| `getToolById(String key)` | Looks up a tool by its **human-readable key** (e.g. `"fleetmdm-server"`); tenant-scoped automatically via `TenantAwareMongoTemplate` |
+| `findByUuid(String uuid)` | Looks up a tool by its raw MongoDB `_id` UUID — use only when the UUID is already known |
+| `saveTool(IntegratedTool tool)` | Persists (insert or update) an `IntegratedTool` document |
 
-> **Conditional Activation:** This service is only instantiated when the property `openframe.integration.tool.enabled=true` is set, allowing tool integration to be toggled per environment.
+> **Conditional activation:** This service only loads when `openframe.integration.tool.enabled=true` is set in application properties.
 
 ## Usage Example
 
 ```java
-// Retrieve all tools
-List<IntegratedTool> tools = integratedToolService.getAllTools();
+// Inject the service
+@Autowired
+private IntegratedToolService integratedToolService;
 
-// Find a tool by type (e.g., "psa", "rmm")
-Optional<IntegratedTool> rmm = integratedToolService.getTool("rmm");
-rmm.ifPresent(tool -> log.info("Found tool: {}", tool.getId()));
+// Retrieve a tool by human-readable key
+Optional<IntegratedTool> tool = integratedToolService.getToolById("fleetmdm-server");
+tool.ifPresent(t -> log.info("Found tool: {}", t.getType()));
 
-// Find a tool by its document ID
-Optional<IntegratedTool> tool = integratedToolService.getToolById("abc123");
+// Retrieve all registered tools
+List<IntegratedTool> tools = integratedToolService.getAllTools();
 
-// Persist a new tool configuration
+// Persist a new or updated tool
 IntegratedTool newTool = new IntegratedTool();
-newTool.setType("psa");
-IntegratedTool saved = integratedToolService.saveTool(newTool);
-```
-
-## Configuration
-
-Ensure the following property is set in your environment to activate this service:
-
-```yaml
-openframe:
-  integration:
-    tool:
-      enabled: true
+newTool.setKey("zabbix-server");
+newTool.setType("monitoring");
+integratedToolService.saveTool(newTool);
 ```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.OpenFrameClientConfigurationService.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.OpenFrameClientConfigurationService.md
index eb3e4e7cb..ee0fce5d6 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.OpenFrameClientConfigurationService.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.OpenFrameClientConfigurationService.md
@@ -1,38 +1,31 @@
-<!-- source-hash: de078580552b7cab47f783da69fd4805 -->
-Manages persistence and lifecycle of `OpenFrameClientConfiguration` documents, including version tracking, publish state transitions, and download configuration merging.
+<!-- source-hash: 86e1de1f2d911d0b9287d2479ce43823 -->
+Service layer for managing `OpenFrameClientConfiguration` documents, handling CRUD operations, publish state transitions, and version/configuration field updates with optimistic locking retry support.
 
 ## Key Components
 
 | Method | Description |
-|---|---|
-| `get()` | Retrieves the singleton default configuration (ID: `"default"`), throwing if absent |
-| `findById(String id)` | Optional lookup by arbitrary configuration ID |
+|--------|-------------|
+| `get()` | Retrieves the configuration for the current tenant; throws `IllegalStateException` if not found |
+| `findById(String id)` | Looks up a configuration by document ID, returning an `Optional` |
 | `save(OpenFrameClientConfiguration)` | Persists a configuration document via the repository |
-| `markAsNonPublished(config)` | Transitions publish state to non-published using current state |
-| `markAsPublished(config)` | Transitions publish state to published |
-| `updateVersion(String newVersion)` | Updates the client version and marks config as `pending` publish; no-ops if version unchanged. Retries on optimistic locking failure |
-| `updateConfigurationFields(config)` | Upserts a configuration by ID; merges download config and flags `pending` if changed. Retries on optimistic locking failure |
-| `mergeAndSave(existing, fromConfig)` | Internal merge: updates `downloadConfiguration` on the existing document and triggers pending state if a diff is detected |
+| `markAsNonPublished(config)` | Transitions publish state to non-published using the current state |
+| `markAsPublished(config)` | Sets publish state to published |
+| `updateVersion(String newVersion)` | Updates the client version and marks configuration as pending publish; no-op if version unchanged |
+| `updateConfigurationFields(config)` | Upserts configuration fields for the current tenant; merges into existing or inserts if absent |
+| `mergeAndSave(existing, fromConfig)` | Merges `DownloadConfiguration` from a source config into an existing one, marking pending if changed |
+
+> Methods annotated with `@RetryOnOptimisticLockingFailure` (`updateVersion`, `updateConfigurationFields`) automatically retry on concurrent write conflicts.
 
 ## Usage Example
 
 ```java
-// Retrieve and update the default client configuration version
-openFrameClientConfigurationService.updateVersion("1.4.2");
-
-// Merge incoming configuration (e.g. from a remote sync)
-OpenFrameClientConfiguration incoming = new OpenFrameClientConfiguration();
-incoming.setId("default");
-incoming.setDownloadConfiguration(newDownloadConfigs);
-openFrameClientConfigurationService.updateConfigurationFields(incoming);
-
-// Manually transition publish state
-OpenFrameClientConfiguration config = openFrameClientConfigurationService.get();
-openFrameClientConfigurationService.markAsPublished(config);
-```
+// Retrieve and publish the current tenant's configuration
+OpenFrameClientConfiguration config = configService.get();
+configService.markAsPublished(config);
 
-## Notes
+// Update the client version (retries on optimistic lock conflict)
+configService.updateVersion("2.5.0");
 
-- The constant `DEFAULT_ID = "default"` is the expected singleton document ID in the repository.
-- `@RetryOnOptimisticLockingFailure` on `updateVersion` and `updateConfigurationFields` ensures safe concurrent writes without manual locking.
-- Publish state changes are only triggered when actual data differences are detected, avoiding unnecessary re-publishes.
\ No newline at end of file
+// Upsert configuration fields from a remote/fetched config
+configService.updateConfigurationFields(fetchedConfig);
+```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/notification/.NotificationReadStateService.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/notification/.NotificationReadStateService.md
index 1ff26411c..efafb9889 100644
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/notification/.NotificationReadStateService.md
+++ b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/notification/.NotificationReadStateService.md
@@ -1,38 +1,43 @@
-<!-- source-hash: 34ee1b6a1c96e4d2816d796fa3083402 -->
-Manages the read/unread state lifecycle for notifications, providing operations to create, mark, delete, and query notification read states for individual recipients or audiences.
+<!-- source-hash: 5d1399d71247dce2ece5729f4c828973 -->
+Manages the read/unread state lifecycle for notifications, handling creation, status updates, deletions, and unread counts per recipient.
 
 ## Key Components
 
 | Method | Description |
 |--------|-------------|
-| `createForAudience` | Bulk-inserts `UNREAD` read-state records for a list of recipient IDs |
-| `hasUnread` | Checks if a recipient has any unread notifications |
+| `createForAudience` | Bulk-inserts `NotificationReadState` records (status `UNREAD`) for a collection of recipients |
+| `hasUnread` | Returns `true` if a recipient has any unread notifications |
 | `markRead` | Marks a single notification as read for a specific recipient |
 | `markAllAsRead` | Marks all notifications as read for a recipient, returns affected count |
-| `deleteNotification` | Soft-deletes a single notification for a recipient |
-| `deleteAllRead` | Soft-deletes all read notifications for a recipient |
-| `unreadCountsByCategory` | Returns a `Map<NotificationCategory, Long>` of unread counts grouped by category |
+| `deleteNotification` | Soft-deletes a single notification entry for a recipient |
+| `deleteAllRead` | Soft-deletes all read notifications for a recipient, returns affected count |
+| `unreadCountsByCategory` | Returns a `Map<NotificationCategory, Long>` of unread counts grouped by category for the current tenant |
 
 ## Usage Example
 
 ```java
-// Broadcast a new notification to multiple users
+// Fan out a new notification to a set of users
 notificationReadStateService.createForAudience(
     "notif-001",
     NotificationCategory.ALERT,
-    "System maintenance scheduled",
-    RecipientType.USER,
+    "Disk usage critical",
+    RecipientType.TECHNICIAN,
     List.of("user-1", "user-2", "user-3")
 );
 
-// Check for unread notifications before rendering badge
-boolean hasBadge = notificationReadStateService.hasUnread("user-1", RecipientType.USER);
+// Check for unread badge indicator
+boolean hasBadge = notificationReadStateService.hasUnread("user-1", RecipientType.TECHNICIAN);
 
-// Mark a single notification as read
-notificationReadStateService.markRead("user-1", RecipientType.USER, "notif-001");
+// Mark one notification read
+notificationReadStateService.markRead("user-1", RecipientType.TECHNICIAN, "notif-001");
 
-// Get per-category unread counts for a notification center UI
+// Get per-category unread counts (e.g. for sidebar counters)
 Map<NotificationCategory, Long> counts =
-    notificationReadStateService.unreadCountsByCategory("user-1", RecipientType.USER);
-// e.g., { ALERT: 3, BILLING: 1 }
-```
\ No newline at end of file
+    notificationReadStateService.unreadCountsByCategory("user-1", RecipientType.TECHNICIAN);
+// { ALERT -> 3, TICKET -> 7 }
+
+// Bulk-clear all read entries
+notificationReadStateService.deleteAllRead("user-1", RecipientType.TECHNICIAN);
+```
+
+> Soft-delete methods preserve audit history while removing entries from active views. All methods are validated via Jakarta Bean Validation — `null` or blank arguments will throw a constraint violation before reaching the repository layer.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.NotificationContextDispatchIT.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.NotificationContextDispatchIT.md
index b9634181b..fe72a949e 100644
--- a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.NotificationContextDispatchIT.md
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.NotificationContextDispatchIT.md
@@ -1,43 +1,42 @@
-<!-- source-hash: 836d3dd8b5f8e3f421f6d4ea90164bb8 -->
-Integration test verifying that `Notification` documents with polymorphic context objects are correctly persisted to and deserialized from MongoDB, using `type` as the sole discriminator field (no `_class` field).
+<!-- source-hash: c9ad81cd57cbd298c9f6ccda4511d3ae -->
+Integration test verifying that `Notification` documents with polymorphic context fields are correctly serialized to and deserialized from MongoDB, using `type` as the sole discriminator (no `_class` field).
 
 ## Key Components
 
 | Component | Role |
 |-----------|------|
 | `NotificationContextDispatchIT` | Main test class extending `BaseMongoIntegrationTest` |
-| `NotificationRepository` | Spring Data repository under test for saving/retrieving notifications |
-| `MongoTemplate` | Used for raw document inspection to validate storage structure |
-| `TestExtendedContext` | Concrete `GenericContext` subclass with extra fields used to exercise polymorphic dispatch |
-| `resetCollection()` | `@BeforeEach` teardown that drops the `Notification` collection before each test |
+| `NotificationRepository` | Spring Data repository under test |
+| `MongoTemplate` | Used for raw document inspection and collection teardown |
+| `TestExtendedContext` | Concrete `GenericContext` subclass with extra fields used in tests |
+| `@EnabledIfSystemProperty` | Guards execution behind `-Dintegration.tests=true` |
 
-## Test Coverage
+## Key Components
+
+**`given_extended_context_when_reread_then_dispatches_to_concrete_subclass`**
+Saves a `Notification` with a `TestExtendedContext` payload and asserts the deserialized result is the concrete subclass with all extra fields intact.
+
+**`given_generic_context_when_reread_then_round_trips_as_generic`**
+Saves a `Notification` with a `GenericContext` and asserts the `type` and raw `payload` string survive the round-trip.
 
-| Test | Validates |
-|------|-----------|
-| `given_extended_context_when_reread_then_dispatches_to_concrete_subclass` | A saved `Notification` with a typed extended context round-trips back as the correct concrete subclass with all extra fields intact |
-| `given_generic_context_when_reread_then_round_trips_as_generic` | A `GenericContext` with an arbitrary payload round-trips correctly without type loss |
-| `given_saved_notification_when_inspecting_raw_doc_then_context_has_no_class_field` | The raw MongoDB document uses `type` as the sole discriminator — no Spring `_class` metadata is written to the embedded context |
+**`given_saved_notification_when_inspecting_raw_doc_then_context_has_no_class_field`**
+Reads the raw MongoDB `Document` directly and asserts the embedded `context` subdocument contains a `type` field but **no** `_class` field, confirming Spring Data's default class-discriminator is suppressed.
 
 ## Usage Example
 
 ```java
-// Typical pattern exercised by these tests:
-Notification notification = Notification.builder()
-        .title("My Event")
-        .createdAt(Instant.now())
-        .context(TestExtendedContext.builder()
-                .type(TestExtendedContext.TYPE)
-                .extraField("value")
-                .extraNumber(99)
-                .build())
-        .build();
-
-Notification saved = repository.save(notification);
-Notification loaded = repository.findById(saved.getId()).orElseThrow();
-
-// Polymorphic dispatch — resolves to concrete subclass via `type`
-assertThat(loaded.getContext()).isInstanceOf(TestExtendedContext.class);
+// Run integration tests with the required system property
+// mvn verify -Dintegration.tests=true
+
+// Typical assertion pattern used in this test
+Optional<Notification> retrieved = repository.findById(persisted.getId());
+
+assertThat(retrieved.get().getContext()).isInstanceOf(TestExtendedContext.class);
+
+// Raw document check — no _class discriminator
+Document context = raw.get("context", Document.class);
+assertThat(context.containsKey("_class")).isFalse();
+assertThat(context.getString("type")).isEqualTo(TestExtendedContext.TYPE);
 ```
 
-> **Run condition:** Tests are gated by the system property `integration.tests=true` and require a live MongoDB instance configured via `BaseMongoIntegrationTest`.
\ No newline at end of file
+> **Note:** All tests require a running MongoDB instance. The collection is dropped via `@BeforeEach` to ensure test isolation. These tests are part of the OpenFrame data layer and validate the polymorphic context dispatch strategy used across the Flamingo notification pipeline.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.TestExtendedContext.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.TestExtendedContext.md
index b5cf79b9d..6de56dbd8 100644
--- a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.TestExtendedContext.md
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/document/notification/.TestExtendedContext.md
@@ -1,33 +1,34 @@
-<!-- source-hash: c5dcf8ef75c56fcbde13de61864fd79a -->
-A test implementation of `NotificationContext` that extends the base class with additional fields, used for validating polymorphic notification context handling in integration tests.
+<!-- source-hash: affdcab8077aa3dadae2e2ee912b54aa -->
+A concrete test implementation of `NotificationContext` used to verify polymorphic serialization and deserialization of extended notification context types, particularly validating that subclass-specific fields are preserved through JSON processing.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
 | `TYPE` | `String` constant | Discriminator value `"TEST_EXTENDED_CONTEXT"` identifying this context subtype |
-| `extraField` | `String` | Additional string field for testing context extension |
-| `extraNumber` | `int` | Additional numeric field for testing context extension |
+| `extraField` | `String` | Additional string field extending the base context |
+| `extraNumber` | `int` | Additional numeric field extending the base context |
+| `getType()` | Method | Returns `TYPE`; the `type` field is write-ignored via `@JsonIgnoreProperties` to prevent deserialization conflicts |
 
 ## Usage Example
 
 ```java
-// Build a test extended context instance
-TestExtendedContext context = TestExtendedContext.builder()
-    .extraField("someValue")
+// Build an instance using the Lombok SuperBuilder
+TestExtendedContext ctx = TestExtendedContext.builder()
+    .extraField("some-value")
     .extraNumber(42)
     .build();
 
-// Use type discriminator for routing/assertions
-String type = TestExtendedContext.TYPE; // "TEST_EXTENDED_CONTEXT"
+// Serializes with type discriminator included via getter
+String json = objectMapper.writeValueAsString(ctx);
+// {"type":"TEST_EXTENDED_CONTEXT","extraField":"some-value","extraNumber":42}
 
-// Polymorphic usage via base class
-NotificationContext base = context;
-System.out.println(base.toString()); // includes superclass fields via callSuper
+// Polymorphic deserialization resolves back to TestExtendedContext
+NotificationContext base = objectMapper.readValue(json, NotificationContext.class);
+assert base instanceof TestExtendedContext;
 ```
 
 ## Notes
 
-- Lombok `@SuperBuilder` enables fluent builder chaining with inherited fields from `NotificationContext`
-- `@EqualsAndHashCode(callSuper = true)` and `@ToString(callSuper = true)` ensure parent class fields are included in equality checks and string representation
-- Intended for use in integration tests only — not a production notification context type
\ No newline at end of file
+- `@JsonIgnoreProperties(value = "type", allowGetters = true)` allows `type` to be **serialized** (via getter) but **ignored on deserialization**, preventing conflicts with the parent class's type discriminator field.
+- Lombok's `@SuperBuilder`, `@EqualsAndHashCode(callSuper = true)`, and `@ToString(callSuper = true)` ensure proper inheritance-aware behavior across builder construction, equality checks, and string representation.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationLoadTestIT.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationLoadTestIT.md
index 1691722d7..e536a0948 100644
--- a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationLoadTestIT.md
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationLoadTestIT.md
@@ -1,42 +1,45 @@
-<!-- source-hash: eec6fafb1f78656ffd1366690fb18be2 -->
-Integration test that benchmarks notification query and write performance against a MongoDB database seeded with up to 1 million documents, validating latency budgets for inbox listing, search, bulk updates, and unread count aggregations.
+<!-- source-hash: 35f4639f5196d067c23e89ebefbba736 -->
+Integration/performance test that load-tests the `Notification` and `NotificationReadState` MongoDB collections at scale (up to 1 million documents), measuring latency for inbox listing, search, bulk updates, and unread count aggregations.
 
 ## Key Components
 
 | Component | Description |
 |-----------|-------------|
-| `seed()` | `@BeforeAll` setup: drops collections, rebuilds indexes, and inserts hot-user slices, sparse-user data, and noise recipients up to `TOTAL` documents |
-| `captureEnvironment()` | Records JVM, OS, CPU, heap, and MongoDB version metadata into the `PerfResultRecorder` |
-| `installSectionDescriptions()` | Attaches human-readable descriptions to each benchmark scenario for the generated report |
-| `BatchInserter` | Internal helper that buffers documents and flushes in configurable batch sizes (`BATCH_FLUSH_SIZE = 5,000`) |
-| `PerfResultRecorder` | Collects timing samples, environment metadata, and scenario descriptions; writes the final performance report |
-| `HOT_SLICES` | Array of inbox sizes (100, 1k, 10k, 100k) used to test that query latency does not scale with inbox size |
-
-**Scenarios measured:**
-
-| Scenario | Budget |
-|----------|--------|
-| S1 — List inbox (first page, no search) | 500 ms |
-| S2 — Dense search (100% hit rate) | 1,500 ms |
-| S3 — Sparse search (~1% hit rate) | 1,500 ms |
-| S4 — Mark all as read (bulk update, 100k rows) | 5,000 ms |
-| S5 — Unread counts by category (aggregation) | — |
+| `seed()` (@BeforeAll) | Seeds MongoDB with hot-user slices (100–100k), sparse users, and noise recipients up to `TOTAL` documents |
+| `captureEnvironment()` | Records JVM, OS, and MongoDB version metadata into the perf report |
+| `installSectionDescriptions()` | Registers human-readable descriptions for each scenario in the `PerfResultRecorder` |
+| `HOT_SLICES` | Array `{100, 1_000, 10_000, 100_000}` — inbox sizes for latency regression testing |
+| `SPARSE_SLICE` / `SPARSE_MATCH_EVERY` | Models a ~1% search hit-rate scenario (30k docs, match every 100th) |
+| `BatchInserter` | Helper for bulk-flushing documents into MongoDB collections in batches of 5,000 |
+| `PerfResultRecorder` | Captures wall-time percentiles (P50/P95/P99), explain output, and writes a perf report to `target/perf-results/` |
+
+### Scenarios Measured
+
+| ID | Scenario | Budget |
+|----|----------|--------|
+| S1 | Inbox list — first page, no search | 500 ms |
+| S2 | Dense search — 100% title match | 500 ms |
+| S3 | Sparse search — ~1% title match | 1,500 ms |
+| S4 | Mark all as read — bulk status flip | 5,000 ms |
+| S5 | Unread counts by category (aggregation) | — |
 
 ## Usage Example
 
 ```bash
-# Run only load tests (disabled by default via @EnabledIfSystemProperty)
-./mvnw verify -Dloadtest.tests=true \
-               -Dnotification.loadtest.total=1000000 \
-               -Dnotification.loadtest.sparse=30000 \
-               -pl openframe-data
+# Run load tests explicitly (disabled by default)
+mvn verify -Dloadtest.tests=true
+
+# Tune dataset size and sparse slice
+mvn verify -Dloadtest.tests=true \
+  -Dnotification.loadtest.total=500000 \
+  -Dnotification.loadtest.sparse=15000
 ```
 
 ```java
-// The test is activated only when the system property is set
+// Tests only activate when system property is set
 @EnabledIfSystemProperty(named = "loadtest.tests", matches = "true")
 @Tag("loadtest")
 class NotificationLoadTestIT extends BaseMongoIntegrationTest { ... }
 ```
 
-> **Note:** Results are written to `target/perf-results/`. Tests require a real MongoDB instance provided by `BaseMongoIntegrationTest`. Join the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) to discuss benchmarking and contribute.
\ No newline at end of file
+> **Note:** Results are written to `target/perf-results/` after each run. The test is annotated `@Tag("loadtest")` so it is excluded from standard CI and must be opted into explicitly.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationReadStateIndexUsageIT.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationReadStateIndexUsageIT.md
index db68b886f..8d5f3a608 100644
--- a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationReadStateIndexUsageIT.md
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/performance/.NotificationReadStateIndexUsageIT.md
@@ -1,40 +1,40 @@
-<!-- source-hash: d628d9b3d357c72c6bd758b89f98fc79 -->
-Integration test that validates MongoDB index usage and query performance for the `NotificationReadState` collection, ensuring critical notification read-state operations use optimal index plans and stay within defined execution time budgets.
+<!-- source-hash: d8dc42c0b2410e47face7858d9d0f5d1 -->
+Integration test that verifies MongoDB index usage and query performance for the `NotificationReadState` collection, ensuring all major notification read-state operations (list, mark-read, unread counts, etc.) use covered index plans rather than collection scans.
 
 ## Key Components
 
 | Component | Description |
 |-----------|-------------|
-| `seed()` / `@BeforeAll` | Drops and re-seeds `notifications` and `notification_read_states` collections with configurable data volumes before the test suite runs |
-| `ensureIndexes()` | Programmatically resolves and applies MongoDB entity indexes via `MongoPersistentEntityIndexResolver` |
-| `MongoExplain` | Test support utility that wraps MongoDB's `explain()` for find, upsert, and aggregation operations, exposing an assertion-friendly `Stats` object |
-| `PerfResultRecorder` | Captures execution metrics and writes a Markdown performance report to `target/perf-results/` |
-| Index constants | Named references to the three key indexes: `recipient_notification_unique`, `recipient_status`, `recipient_category_status` |
-
-## Test Coverage
-
-| Test Method | Operation Verified | Expected Index |
-|---|---|---|
-| `list_for_recipient_step_one_uses_indexed_plan` | Paginated find for USER recipient | `recipient_notification_unique` or `recipient_status` |
-| `list_for_recipient_machine_uses_indexed_plan` | Paginated find for MACHINE recipient | `recipient_notification_unique` or `recipient_status` |
-| `has_unread_uses_recipient_status_index` | Existence check for UNREAD status | `recipient_status` |
-| `mark_read_uses_unique_compound_index` | Single-document update by recipient + notificationId | `recipient_notification_unique` |
-| `mark_all_as_read_uses_recipient_status_index` | Bulk update UNREAD → READ | `recipient_status` |
-| `unread_counts_by_category_uses_recipient_category_status_index` | Aggregation group by category | `recipient_category_status` or `recipient_status` |
+| `seed()` / `@BeforeAll` | Drops and re-seeds `notifications` + `notification_read_states` collections with configurable volumes (default 30k notifications, 3k hot admin read states, 20k noise records) |
+| `list_for_recipient_step_one_uses_indexed_plan` | Asserts `findPageForRecipient` uses `recipient_notification_unique` or `recipient_status` index, no collection scan, ≤ `limit × 4` keys examined |
+| `has_unread_uses_recipient_status_index` | Verifies the existence check short-circuits on `recipient_status`, examining at most 2 keys |
+| `mark_read_uses_unique_compound_index` | Confirms single-row `markRead` lookup hits `recipient_notification_unique` with exactly 1 key examined |
+| `mark_all_as_read_uses_recipient_status_index` | Validates bulk update query plan against `recipient_status` within hot-recipient slice |
+| `unread_counts_by_category_uses_recipient_category_status_index` | Ensures `$match` stage of aggregation hits `recipient_category_status` or `recipient_status` |
+| `MongoExplain.Stats` | Helper wrapper around MongoDB `explain()` output; provides assertion methods for index names, execution time, and keys examined |
+| `PerfResultRecorder` | Writes per-test timing/key stats to `target/perf-results/` as a Markdown report |
 
 ## Usage Example
 
-```java
-// Run performance tests explicitly via Maven system property
+```bash
+# Run only performance tests (disabled by default)
 mvn verify -Dperformance.tests=true
 
-// Override data volume for local runs
+# Tune dataset sizes via system properties
 mvn verify -Dperformance.tests=true \
-           -Dperf.notifications.count=5000 \
-           -Dperf.readStates.hotAdmin=500
+  -Dperf.notifications.count=50000 \
+  -Dperf.readStates.hotAdmin=5000 \
+  -Dperf.readStates.noise=30000
+```
+
+```java
+// Core assertion pattern used in every test
+Stats stats = MongoExplain.explainFind(mongoTemplate, READS_COLL, query);
 
-// All tests are tagged "performance" and skipped unless the system property is set
-// Results are written to target/perf-results/<ClassName>.md
+stats.assertNoCollectionScan()
+     .assertUsesAnyOf(IDX_RECIPIENT_NOTIF, IDX_RECIPIENT_STATUS)
+     .assertExecutionTimeBelow(FIND_BUDGET_MS);  // 200 ms
+stats.assertExaminedAtMost(limit * 4L);
 ```
 
-> **Note:** Tests are conditionally enabled via `@EnabledIfSystemProperty(named = "performance.tests", matches = "true")` and tagged `@Tag("performance")`, keeping them isolated from the standard CI test run.
\ No newline at end of file
+> **Note:** Tests are gated by `@EnabledIfSystemProperty(named = "performance.tests", matches = "true")` and tagged `@Tag("performance")` so they never run in standard CI pipelines — only in dedicated performance verification runs.
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/notification/.CustomNotificationRepositoryPaginationIT.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/notification/.CustomNotificationRepositoryPaginationIT.md
index 6a6ae03c4..40a3c4d0b 100644
--- a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/notification/.CustomNotificationRepositoryPaginationIT.md
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/notification/.CustomNotificationRepositoryPaginationIT.md
@@ -1,52 +1,48 @@
-<!-- source-hash: 85335126ab548399f85ac8cc250aa896 -->
-Integration test suite for cursor-based pagination of the `NotificationRepository`, verifying filtering, isolation, search, and streaming behavior against a real MongoDB instance.
+<!-- source-hash: a55892cacea56abfb3342984c0313d3b -->
+Integration test suite for the `NotificationRepository`'s custom pagination logic, verifying cursor-based navigation, recipient isolation, read/delete filtering, and title search behavior against a real MongoDB instance.
 
 ## Key Components
 
 | Component | Role |
 |-----------|------|
 | `CustomNotificationRepositoryPaginationIT` | Main test class extending `BaseMongoIntegrationTest` |
-| `NotificationRepository` | Repository under test, injected via `@Autowired` |
+| `NotificationRepository` | Repository under test, injected via Spring context |
 | `MongoTemplate` | Used in `@BeforeEach` to reset `Notification` and `NotificationReadState` collections |
-| `NotificationFixtures` | Helper for building seed `Notification` documents |
-| `NotificationWithStatus` | Result type pairing a `Notification` with its `ReadStatus` |
-| `NotificationPage` | Cursor-based page wrapper returned by the repository |
-
-## Covered Test Scenarios
-
-| Scenario | Test Method |
-|----------|-------------|
-| No cursor → newest-first descending order | `given_no_cursor_returns_descending` |
-| Forward cursor → older rows only | `given_forward_cursor_returns_older_rows` |
-| Backward cursor → newer rows only | `given_backward_cursor_returns_newer_rows` |
-| Audience isolation by recipient ID | `audience_isolation_by_id` |
-| Audience isolation by recipient type (`USER` vs `MACHINE`) | `audience_isolation_by_type` |
-| `limit` parameter honored | `limit_honored` |
-| Empty result when no rows exist | `empty_when_no_rows` |
-| `DELETED` status excluded by default | `deleted_excluded_by_default` |
-| `readFilter=true` returns only READ rows | `read_filter_true` |
-| `readFilter=false` returns only UNREAD rows | `read_filter_false` |
-| Title search (case-insensitive) | `search_filters_by_title` |
-| Streaming fills a full page when matches are sparse | `search_streams_until_full_page_collected` |
-| Streaming exhausts gracefully when matches < limit | `search_exhausts_when_fewer_matches_than_limit` |
-| Batch growth when matches are beyond initial 64-row window | `search_grows_batch_to_reach_distant_matches` |
+| `NotificationFixtures` | Factory helpers for seeding test documents |
+| `NotificationWithStatus` | DTO returned by pagination queries, carrying notification + read status |
+| `NotificationPage` | Pagination result wrapper |
+
+## Test Coverage Summary
+
+| Test | What It Validates |
+|------|-------------------|
+| `given_no_cursor_returns_descending` | Default newest-first ordering |
+| `given_forward_cursor_returns_older_rows` | Forward cursor excludes newer results |
+| `given_backward_cursor_returns_newer_rows` | Backward cursor fetches newer results |
+| `audience_isolation_by_id` | Different recipient IDs don't bleed data |
+| `audience_isolation_by_type` | `USER` vs `MACHINE` type isolation |
+| `limit_honored` | Page size cap respected |
+| `deleted_excluded_by_default` | `DELETED` status filtered out by default |
+| `read_filter_true/false` | `READ`/`UNREAD` filtering |
+| `search_filters_by_title` | Case-insensitive title search |
+| `search_streams_until_full_page_collected` | Streaming fills full page despite sparse matches |
+| `search_grows_batch_to_reach_distant_matches` | Batch growth handles matches past initial 64-document window |
 
 ## Usage Example
 
 ```java
-// Tests run only when the system property is set:
-// mvn verify -Dintegration.tests=true
-
-// Typical pagination call exercised in these tests:
-List<NotificationWithStatus> page = repository.findPage(
-    recipientId,       // e.g. "user-alice"
-    recipientType,     // RecipientType.USER or RecipientType.MACHINE
-    readFilter,        // Boolean: true=READ, false=UNREAD, null=both
-    search,            // String: case-insensitive title filter, or null
-    cursor,            // String: ObjectId of last seen notification, or null
-    backward,          // boolean: true = fetch newer rows (previous page)
-    limit              // int: max rows to return
-);
+// Tests are guarded by a system property — run integration tests with:
+// -Dintegration.tests=true
+
+// Typical test flow pattern used internally:
+List<Notification> seeded = seedSequentialForRecipient(ALICE, U, 5);
+String cursor = seeded.get(2).getId();
+
+// Forward page: returns items older than the cursor
+List<NotificationWithStatus> page = page(ALICE, U, null, null, cursor, false, 10);
+
+// Search page: streams until `limit` matching titles are found
+List<NotificationWithStatus> results = page(ALICE, U, null, "alert", null, false, 3);
 ```
 
-> **Note:** Tests are guarded by `@EnabledIfSystemProperty(named = "integration.tests", matches = "true")` and require a running MongoDB instance configured in `BaseMongoIntegrationTest`. Each test resets both the `Notification` and `NotificationReadState` collections in `@BeforeEach`.
\ No newline at end of file
+> **Note:** Tests are only activated when `-Dintegration.tests=true` is set, requiring a live MongoDB instance configured via `BaseMongoIntegrationTest`. Community support is available on [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA).
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/rmm/.ScriptRepositoryIT.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/rmm/.ScriptRepositoryIT.md
new file mode 100644
index 000000000..da30d3298
--- /dev/null
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/repository/rmm/.ScriptRepositoryIT.md
@@ -0,0 +1,33 @@
+<!-- source-hash: a92ab0832aa315660d881a6dd95e5045 -->
+Integration test suite for `ScriptRepository`, validating MongoDB persistence, multi-tenant isolation, cursor-based pagination, soft-delete filtering, and compound unique index enforcement for the `Script` document.
+
+## Key Components
+
+- **`resetCollection()`** — Clears all `Script` documents before each test while preserving indexes (avoids losing the compound unique constraint that Spring Data only creates at startup).
+- **Audit tests** — Verifies that `createdAt`/`updatedAt` fields are auto-populated on save.
+- **Tenant isolation tests** — Confirms `findByTenantIdAndId`, `findByTenantIdAndName`, `existsByTenantIdAndName`, `deleteByTenantIdAndId`, and `findPageForTenant` never leak data across tenant boundaries.
+- **Cursor pagination tests** — Covers no-cursor (newest-first), forward cursor (older rows), backward cursor (newer rows ascending), page size limit, and graceful fallback on invalid cursor values.
+- **Soft-delete filtering** — Ensures `DELETED` status scripts are excluded from default list queries.
+- **Collision detection** — Tests `existsByTenantIdAndNameAndIdNot` for self-edit (no false collision) and real same-name conflict.
+- **Compound unique index** — Asserts duplicate `(tenantId, name)` throws `DuplicateKeyException`, while the same name across different tenants is allowed.
+
+## Usage Example
+
+```java
+// Run integration tests with the required system property
+// mvn verify -Dintegration.tests=true
+
+// Typical test pattern used throughout the suite
+Script script = newScript(TENANT_A, "Restart Spooler");
+Script saved = scriptRepository.save(script);
+
+// Tenant-scoped lookup
+Optional<Script> found = scriptRepository.findByTenantIdAndId(TENANT_A, saved.getId());
+
+// Cursor-based pagination (newest-first, page size 10)
+List<Script> page = scriptRepository.findPageForTenant(
+    TENANT_A, null, null, "_id", Sort.Direction.DESC, null, false, 10);
+
+// Cross-tenant delete guard
+long removed = scriptRepository.deleteByTenantIdAndId(TENANT_B, saved.getId()); // returns 0
+```
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/support/.RmmIntegrationTestApplication.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/support/.RmmIntegrationTestApplication.md
new file mode 100644
index 000000000..4cce4831f
--- /dev/null
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/integration/support/.RmmIntegrationTestApplication.md
@@ -0,0 +1,40 @@
+<!-- source-hash: f3c00a3448721a4cec1701ab88e3f997 -->
+Minimal Spring Boot test application context for RMM repository integration tests, scoping MongoDB repository scanning to the RMM package and importing required custom repository fragments.
+
+## Key Components
+
+| Element | Description |
+|---|---|
+| `@SpringBootConfiguration` | Marks this as a Spring Boot configuration class for the test context |
+| `@EnableAutoConfiguration` | Activates Spring Boot's auto-configuration for MongoDB and related infrastructure |
+| `@EnableMongoAuditing` | Enables `@CreatedDate` / `@LastModifiedDate` population on `Script` documents, matching production behavior |
+| `@EnableMongoRepositories` | Restricts repository scanning to the RMM package via `ScriptRepository` as the base class anchor |
+| `@Import(CustomScriptRepositoryImpl.class)` | Explicitly registers the custom repository fragment since `@EnableMongoRepositories` does not auto-detect it in a test context |
+
+## Usage Example
+
+```java
+// Reference this configuration in your RMM integration test
+@DataMongoTest
+@Import(RmmIntegrationTestApplication.class)
+class ScriptRepositoryIntegrationTest {
+
+    @Autowired
+    private ScriptRepository scriptRepository;
+
+    @Test
+    void shouldPersistScriptWithAuditDates() {
+        Script script = new Script("cleanup-script", "rm -rf /tmp/*");
+        Script saved = scriptRepository.save(script);
+
+        assertNotNull(saved.getCreatedDate());
+        assertNotNull(saved.getLastModifiedDate());
+    }
+}
+```
+
+## Notes
+
+- Intentionally minimal — excludes notification, organization, and other unrelated repositories to keep the test context lightweight and fast
+- `CustomScriptRepositoryImpl` must be explicitly imported here because in production it is resolved via the tenant application's component scan, not by `@EnableMongoRepositories` alone
+- Mirrors the pattern of the broader `IntegrationTestApplication` but is scoped exclusively to RMM concerns
\ No newline at end of file
diff --git a/openframe-data-mongo-sync/src/test/java/com/openframe/data/repository/notification/.NotificationContextWriteConverterTest.md b/openframe-data-mongo-sync/src/test/java/com/openframe/data/repository/notification/.NotificationContextWriteConverterTest.md
new file mode 100644
index 000000000..6784673c4
--- /dev/null
+++ b/openframe-data-mongo-sync/src/test/java/com/openframe/data/repository/notification/.NotificationContextWriteConverterTest.md
@@ -0,0 +1,43 @@
+<!-- source-hash: d39949e5a5d0396d1c5d856ec15b25c6 -->
+Unit test suite for `NotificationContextWriteConverter`, validating the conversion of `NotificationContext` objects into BSON `Document` instances for MongoDB persistence.
+
+## Key Components
+
+| Test Method | Purpose |
+|---|---|
+| `given_null_source_when_converting_then_returns_null` | Verifies null input returns null without invoking Jackson |
+| `given_generic_context_when_converting_then_document_contains_type_and_payload` | Confirms a populated `GenericContext` produces a BSON document with correct `type` and `payload` fields |
+| `given_jackson_failure_when_converting_then_throws_with_type_in_message` | Ensures serialization failures surface as `IllegalStateException` with the discriminator type embedded in the message |
+
+## Coverage Summary
+
+```text
+Null guard         → short-circuits without ObjectMapper invocation
+Happy path         → discriminator + payload fields present in output Document
+Error path         → JsonProcessingException wrapped into IllegalStateException
+                     with type name for log diagnosability
+```
+
+## Usage Example
+
+```java
+// Production wiring (Spring Data MongoDB converter registration)
+ObjectMapper objectMapper = new ObjectMapper();
+NotificationContextWriteConverter converter =
+        new NotificationContextWriteConverter(objectMapper);
+
+GenericContext ctx = GenericContext.builder()
+        .type("ALERT")
+        .payload("{\"message\":\"Disk usage at 90%\"}")
+        .build();
+
+Document bson = converter.convert(ctx);
+// bson.getString("type")    → "ALERT"
+// bson.getString("payload") → "{\"message\":\"Disk usage at 90%\"}"
+```
+
+## Design Notes
+
+- Uses **Mockito BDD-style** stubbing (`given(...).willThrow(...)`) for the error path, keeping mock setup expressive and readable
+- The `IllegalStateException` message deliberately includes the discriminator type so production log searches can pinpoint which context variant triggered the failure
+- Jackson is **not invoked** on null input, preventing unnecessary mock interactions and reflecting the converter's early-exit contract
\ No newline at end of file
diff --git a/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolAgentUpdateUpdatePublisher.md b/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolAgentUpdateUpdatePublisher.md
index 54c984475..a9d3c35b0 100644
--- a/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolAgentUpdateUpdatePublisher.md
+++ b/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolAgentUpdateUpdatePublisher.md
@@ -1,51 +1,28 @@
-<!-- source-hash: f1b733fa701e98b77782ffd42dc22ca5 -->
-Publishes tool agent update messages to NATS persistent subjects, handling optimistic locking conflicts and delegating publish-state tracking to `IntegratedToolAgentService`.
+<!-- source-hash: d86a19e76afd56c5755ca11b35b70b46 -->
+Publishes tool agent update messages to NATS persistent streams when an `IntegratedToolAgent` is updated, handling optimistic locking conflicts and marking publish state accordingly.
 
 ## Key Components
 
-| Member | Type | Description |
-|--------|------|-------------|
-| `TOPIC_NAME_TEMPLATE` | Constant | Subject pattern `machine.all.tool.<id>.update` used to route messages per tool agent |
-| `publish()` | Method | Orchestrates send + state marking; catches exceptions and falls back to `markAsNonPublished` for scheduler retry |
-| `send()` | Method | Builds the topic name and `ToolAgentUpdateMessage`, then delegates to `NatsMessagePublisher.publishPersistent()` |
-| `buildMessage()` | Method | Assembles a `ToolAgentUpdateMessage` from the `IntegratedToolAgent` document, mapping download configs and assets |
-| `mapAssets()` | Method | Converts a list of `ToolAgentAsset` domain objects to `AssetUpdate` DTOs |
-
-> **Activation:** The bean is only created when `spring.cloud.stream.enabled` is set, keeping NATS publishing opt-in per environment.
+| Element | Description |
+|---|---|
+| `TOPIC_NAME_TEMPLATE` | Topic pattern `machine.all.tool.<toolAgentId>.update` |
+| `publish()` | Sends the update and marks the agent as published; marks as non-published on failure |
+| `send()` | Builds and dispatches the `ToolAgentUpdateMessage` to the NATS persistent stream |
+| `buildMessage()` | Constructs the full `ToolAgentUpdateMessage` including version, session type, download configs, and assets |
+| `mapAssets()` | Maps `ToolAgentAsset` list to `AssetUpdate` DTOs |
+| `@ConditionalOnProperty` | Only active when `spring.cloud.stream.enabled` is set |
 
 ## Usage Example
 
 ```java
-// Injected by Spring – typically called from a scheduler or event handler
-@Service
-@RequiredArgsConstructor
-public class ToolAgentUpdateScheduler {
+// Triggered when a tool agent update needs to be broadcast
+IntegratedToolAgent toolAgent = integratedToolAgentService.findById("my-tool");
 
-    private final ToolAgentUpdateUpdatePublisher publisher;
-    private final IntegratedToolAgentService toolAgentService;
+// Full publish with state tracking (marks as published or non-published)
+toolAgentUpdateUpdatePublisher.publish(toolAgent);
 
-    public void retryUnpublished() {
-        toolAgentService.findAllNonPublished().forEach(toolAgent -> {
-            // publish() handles send errors and concurrent-write races internally
-            publisher.publish(toolAgent);
-        });
-    }
-}
+// Fire-and-forget send without state management
+toolAgentUpdateUpdatePublisher.send(toolAgent);
 ```
 
-```java
-// Direct send (no state tracking) – use when publish state is managed externally
-publisher.send(toolAgent);
-```
-
-**Error handling flow:**
-
-```mermaid
-graph TD
-    A["publish(toolAgent)"] --> B["send()"]
-    B --> C{"Success?"}
-    C -->|Yes| D["markAsPublished()"]
-    C -->|No| E["markAsNonPublished()"]
-    E --> F["Scheduler retries later"]
-    D --> G["Log: Published"]
-```
\ No newline at end of file
+> **Note:** `publish()` handles `OptimisticLockingFailureException` on both the failure-mark and success-mark paths, safely skipping the state update if a concurrent writer is detected. Failed publishes are left in a non-published state for retry by a scheduled job.
\ No newline at end of file
diff --git a/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolInstallationNatsPublisher.md b/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolInstallationNatsPublisher.md
index 9761fcdd7..b9793c739 100644
--- a/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolInstallationNatsPublisher.md
+++ b/openframe-data-nats/src/main/java/com/openframe/data/nats/publisher/.ToolInstallationNatsPublisher.md
@@ -1,31 +1,25 @@
-<!-- source-hash: 9de755832f51e1fe9001ea73498cae6b -->
-Publishes tool installation messages to NATS for a specific machine, translating `IntegratedToolAgent` and `IntegratedTool` domain objects into a `ToolInstallationMessage` payload.
+<!-- source-hash: d49e3df252a4a8493177f2724aaefed7 -->
+Publishes tool installation messages to NATS for a specific machine, triggering agent deployment or reinstallation workflows.
 
 ## Key Components
 
-| Member | Description |
-|--------|-------------|
-| `TOPIC_NAME_TEMPLATE` | Topic pattern `machine.{machineId}.tool-installation` used to route messages per machine |
-| `publish(machineId, toolAgent, tool)` | Publishes an installation message with `reinstall = false` |
-| `publish(machineId, toolAgent, tool, reinstall)` | Publishes an installation message with an explicit reinstall flag |
-| `buildMessage(...)` | Assembles a `ToolInstallationMessage` from the tool agent, tool metadata, and reinstall flag |
-| `mapAssets(...)` | Converts a list of `ToolAgentAsset` objects to `ToolInstallationMessage.Asset` entries |
-| `mapAsset(...)` | Maps a single `ToolAgentAsset`, including download configs, local filename, source, path, and executable flag |
-| `mapAssetSource(...)` | Translates `ToolAgentAssetSource` enum (`ARTIFACTORY`, `TOOL_API`, `GITHUB`) to the message model equivalent |
+- **`TOPIC_NAME_TEMPLATE`** — Topic pattern `machine.{machineId}.tool-installation` used to route messages per machine
+- **`publish(machineId, toolAgent, tool)`** — Publishes a standard installation message (reinstall defaults to `false`)
+- **`publish(machineId, toolAgent, tool, reinstall)`** — Publishes an installation message with explicit reinstall flag via persistent NATS delivery
+- **`buildMessage(...)`** — Assembles a `ToolInstallationMessage` from `IntegratedToolAgent` and `IntegratedTool`, mapping download configs, assets, and command args
+- **`mapAssets(...)`** — Converts a list of `ToolAgentAsset` into `ToolInstallationMessage.Asset` objects including filenames, download configs, and source
+- **`mapAssetSource(...)`** — Translates `ToolAgentAssetSource` enum (`ARTIFACTORY`, `TOOL_API`, `GITHUB`) to the message-layer equivalent
 
-> **Note:** This component is conditionally loaded — it requires `spring.cloud.stream.enabled` to be set in application properties.
+> **Note:** Active only when `spring.cloud.stream.enabled` property is set (`@ConditionalOnProperty`).
 
 ## Usage Example
 
 ```java
-// Inject and call from a service
-@Autowired
-private ToolInstallationNatsPublisher publisher;
-
 // Standard installation
-publisher.publish(machineId, toolAgent, tool);
+toolInstallationNatsPublisher.publish(machineId, toolAgent, tool);
 
 // Force reinstall
-publisher.publish(machineId, toolAgent, tool, true);
-// Publishes to: machine.<machineId>.tool-installation
-```
\ No newline at end of file
+toolInstallationNatsPublisher.publish(machineId, toolAgent, tool, true);
+```
+
+The publisher delegates to `NatsMessagePublisher.publishPersistent(...)`, ensuring the message is durably stored in the NATS JetStream layer until the target machine acknowledges receipt.
\ No newline at end of file
diff --git a/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CancelMessage.md b/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CancelMessage.md
new file mode 100644
index 000000000..539086ade
--- /dev/null
+++ b/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CancelMessage.md
@@ -0,0 +1,24 @@
+<!-- source-hash: 0b2e3c3169477deedfa35206d5fc987c -->
+Wire payload model sent over NATS to the OpenFrame agent to abort an in-flight execution. Contains the identifier of the execution to cancel.
+
+## Key Components
+
+| Element | Description |
+|---------|-------------|
+| `executionId` | The unique identifier of the in-flight execution to be aborted |
+| `@JsonInclude(NON_NULL)` | Omits null fields from the serialized JSON payload |
+| `@Builder` | Enables fluent builder construction via Lombok |
+| `@Data` | Generates getters, setters, `equals`, `hashCode`, and `toString` via Lombok |
+
+## Usage Example
+
+```java
+// Build and publish a cancellation message over NATS
+CancelMessage cancelMessage = CancelMessage.builder()
+        .executionId("exec-7f3a1b2c")
+        .build();
+
+// Serialize and publish to the appropriate NATS subject
+String payload = objectMapper.writeValueAsString(cancelMessage);
+natsConnection.publish("openframe.agent.cancel", payload.getBytes());
+```
\ No newline at end of file
diff --git a/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CommandMessage.md b/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CommandMessage.md
new file mode 100644
index 000000000..b503417fd
--- /dev/null
+++ b/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/model/.CommandMessage.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 226a0d304e0233aa080ba6fbef72e45f -->
+NATS wire payload model for dispatching a single ad-hoc command to an OpenFrame agent, published on the `machine.{machineId}.command-execution` subject.
+
+## Key Components
+
+| Field | Type | Description |
+|---|---|---|
+| `executionId` | `String` | Unique identifier for this command execution |
+| `code` | `String` | The command/script content to execute |
+| `shell` | `ScriptShell` | Target shell interpreter (e.g., `BASH`, `POWERSHELL`) |
+| `privilegeLevel` | `PrivilegeLevel` | Execution privilege level (e.g., `ADMIN`, `USER`) |
+| `timeout` | `Integer` | Maximum execution time in seconds; `null` fields are omitted via `@JsonInclude` |
+
+## Usage Example
+
+```java
+CommandMessage message = CommandMessage.builder()
+    .executionId("01HXYZ...")
+    .code("echo hello")
+    .shell(ScriptShell.BASH)
+    .privilegeLevel(PrivilegeLevel.ADMIN)
+    .timeout(30)
+    .build();
+
+// Publish to agent over NATS
+String subject = "machine." + machineId + ".command-execution";
+natsConnection.publish(subject, objectMapper.writeValueAsBytes(message));
+```
+
+> **Note:** `@JsonInclude(NON_NULL)` ensures unset optional fields (e.g., `timeout`) are excluded from the serialized payload, keeping the wire format clean for the receiving agent.
\ No newline at end of file
diff --git a/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisher.md b/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisher.md
new file mode 100644
index 000000000..67f5ff0e6
--- /dev/null
+++ b/openframe-data-nats/src/main/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisher.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 82c38203ebadc8233e02c294d9d27bdc -->
+A Spring component that publishes RMM (Remote Monitoring & Management) ad-hoc command and cancellation messages to target agents over core NATS messaging.
+
+## Key Components
+
+| Member | Description |
+|--------|-------------|
+| `MACHINE_SUBJECT_TEMPLATE` | NATS subject pattern `machine.{machineId}.command-execution` |
+| `CANCEL_SUBJECT_TEMPLATE` | NATS subject pattern `machine.{machineId}.command-cancel` |
+| `publishCommand()` | Publishes a `CommandMessage` to the target agent for execution |
+| `publishCancel()` | Publishes a `CancelMessage` to abort an in-flight execution |
+
+**Activation:** Only loaded when `spring.cloud.stream.enabled` property is set.
+
+**Validation:** Both methods guard against blank `machineId` and null/blank `executionId`, throwing `IllegalArgumentException` on violation.
+
+## Usage Example
+
+```java
+@Autowired
+private CommandNatsPublisher commandNatsPublisher;
+
+// Publish a command to a remote agent
+CommandMessage command = CommandMessage.builder()
+    .executionId("exec-001")
+    .script("ipconfig /all")
+    .build();
+
+commandNatsPublisher.publishCommand("machine-abc123", command);
+// → publishes to: machine.machine-abc123.command-execution
+
+// Cancel an in-flight execution
+CancelMessage cancel = CancelMessage.builder()
+    .executionId("exec-001")
+    .build();
+
+commandNatsPublisher.publishCancel("machine-abc123", cancel);
+// → publishes to: machine.machine-abc123.command-cancel
+```
\ No newline at end of file
diff --git a/openframe-data-nats/src/test/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisherTest.md b/openframe-data-nats/src/test/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisherTest.md
new file mode 100644
index 000000000..bcdf15001
--- /dev/null
+++ b/openframe-data-nats/src/test/java/com/openframe/data/nats/rmm/publisher/.CommandNatsPublisherTest.md
@@ -0,0 +1,45 @@
+<!-- source-hash: 72dfd26b50e21f88979efb8f94d0b384 -->
+Unit test suite for `CommandNatsPublisher`, verifying NATS subject routing, payload validation, transport selection, and error propagation for RMM command and cancel message publishing.
+
+## Key Components
+
+| Test Method | What It Verifies |
+|---|---|
+| `publishCommand_routesToMachineSubjectWithUnchangedPayload` | Subject resolves to `machine.<machineId>.command-execution` and payload is forwarded unchanged |
+| `publishCommand_usesCoreNatsNotJetStream` | Core NATS `publish()` is used — never `publishPersistent()` |
+| `publishCommand_rejectsBlankMachineId` | Blank/whitespace `machineId` throws `IllegalArgumentException` before any broker call |
+| `publishCommand_rejectsNullMessage` | Null `CommandMessage` throws `IllegalArgumentException` |
+| `publishCommand_rejectsBlankExecutionId` | Blank `executionId` throws `IllegalArgumentException` |
+| `publishCommand_propagatesTransportFailure` | `NatsException` from the broker propagates to the caller |
+| `publishCancel_routesToCancelSubject` | Subject resolves to `machine.<machineId>.command-cancel` |
+| `publishCancel_usesCoreNatsNotJetStream` | Cancel messages also use core NATS, not JetStream |
+| `publishCancel_rejectsBlankMachineId` | Blank `machineId` rejected before broker call |
+| `publishCancel_rejectsMissingExecutionId` | Both null message and blank `executionId` rejected |
+
+## Usage Example
+
+```java
+// Test setup pattern used across all cases
+@BeforeEach
+void setUp() {
+    messagePublisher = mock(NatsMessagePublisher.class);
+    publisher = new CommandNatsPublisher(messagePublisher);
+}
+
+// Verifying subject routing with ArgumentCaptor
+CommandMessage message = CommandMessage.builder()
+        .executionId("exec-1")
+        .code("df -h")
+        .build();
+
+publisher.publishCommand("machine-42", message);
+
+ArgumentCaptor<String> subject = ArgumentCaptor.forClass(String.class);
+verify(messagePublisher).publish(subject.capture(), any());
+assertThat(subject.getValue()).isEqualTo("machine.machine-42.command-execution");
+```
+
+## Design Rationale
+
+- **Core NATS over JetStream** — Commands and cancels are intentionally non-durable. Re-delivering a cancel after a broker restart could target an unrelated subsequent execution.
+- **Pre-flight validation** — All guard checks run before any broker interaction, ensuring `NatsMessagePublisher` is never called with a malformed subject or incomplete correlation ID.
\ No newline at end of file
diff --git a/openframe-debezium-initializer/src/main/java/com/openframe/debezium/service/.DebeziumService.md b/openframe-debezium-initializer/src/main/java/com/openframe/debezium/service/.DebeziumService.md
index 19563e587..1765378c6 100644
--- a/openframe-debezium-initializer/src/main/java/com/openframe/debezium/service/.DebeziumService.md
+++ b/openframe-debezium-initializer/src/main/java/com/openframe/debezium/service/.DebeziumService.md
@@ -1,47 +1,46 @@
-<!-- source-hash: d3bb46ee05544e031498a09967e1ca6f -->
-Manages lifecycle operations for Debezium connectors via the Kafka Connect REST API, including creation, versioned updates, drift detection, deletion, and status retrieval.
+<!-- source-hash: ee6b6998d3630f9a14f1abcc108639b7 -->
+Manages Debezium connector lifecycle via the Kafka Connect REST API, handling creation, versioned recreation on config drift, updates, deletion, and status retrieval for CDC connectors in the OpenFrame platform.
 
 ## Key Components
 
-| Method | Description |
+| Member | Description |
 |--------|-------------|
-| `createOrUpdateDebeziumConnector` | Entry point for applying one or more connector specs; delegates to `applyConnectorSpec` |
-| `applyConnectorSpec` | Routes connector creation/update based on naming strategy (identity vs. versioned) |
-| `createInitialVersion` | Creates a new connector when no version exists yet |
-| `recreateOnConfigDrift` | Versioned-strategy path: compares running config to incoming spec and recreates on drift, gated by `RecreationTracker` |
-| `tryUpdateExistingIdentityConnector` | Identity-strategy path: pushes updated config in-place via `PUT /connectors/{name}/config` |
-| `configsEquivalent` | Normalises both config maps to `Map<String, String>` (dropping `name`) for semantic comparison |
-| `createConnector` | POSTs a new connector payload to Kafka Connect |
-| `deleteConnector` | DELETEs a connector; tolerates 404 |
-| `listConnectors` | Returns all registered connector names; returns empty list on failure |
-| `getConnectorStatus` | Returns `ConnectorStatus` or `null` if the connector is gone |
-| `getConnectorConfig` | Returns the currently-deployed config map or `null` on 404/error |
+| `createOrUpdateDebeziumConnector(Object[])` | Entry point — processes an array of connector specs and applies create/update logic per spec |
+| `applyConnectorSpec(Map)` | Routes each spec to the correct strategy: initial creation, identity update, or versioned recreation |
+| `createInitialVersion(...)` | Creates a connector for the first time using the name strategy's resolved name |
+| `tryUpdateExistingIdentityConnector(...)` | PUT-updates config in-place when the identity naming strategy is in use |
+| `recreateOnConfigDrift(...)` | Detects config changes for versioned connectors, rate-gates recreation via `RecreationTracker`, creates new version, and prunes stale ones |
+| `createConnector(String, Map)` | POST to `/connectors` with the effective connector name and config payload |
+| `deleteConnector(String)` | DELETE `/connectors/{name}`, tolerates 404 |
+| `listConnectors()` | GET `/connectors` — returns empty list on transient failure |
+| `getConnectorStatus(String)` | GET `/connectors/{name}/status` — returns `null` on 404 |
+| `getConnectorConfig(String)` | GET `/connectors/{name}/config` — returns `null` on 404 or unreachable |
+| `configsEquivalent(Map, Map)` | Semantic equality check that normalizes all values to strings and ignores the `name` key |
 
 ## Usage Example
 
 ```java
-// Inject the service
+// Spring-managed; inject and call after tools are resolved
 @Autowired
 private DebeziumService debeziumService;
 
-// Apply connector specs loaded from MongoDB (e.g. IntegratedTool config)
-Object[] specs = tool.getDebeziumConnectors();
+// Apply a connector spec array sourced from an IntegratedTool document
+Object[] specs = integratedTool.getDebeziumConnectors();
 debeziumService.createOrUpdateDebeziumConnector(specs);
 
-// Manually create a connector
+// Directly create a named connector
 Map<String, Object> config = new HashMap<>();
-config.put("connector.class", "io.debezium.connector.postgresql.PostgresConnector");
-config.put("database.hostname", "localhost");
-debeziumService.createConnector("my-connector-v1", config);
+config.put("connector.class", "io.debezium.connector.mongodb.MongoDbConnector");
+config.put("mongodb.connection.string", "mongodb://localhost:27017");
+config.put("topic.prefix", "openframe");
+debeziumService.createConnector("openframe-mongo-v1", config);
 
 // Check connector health
-ConnectorStatus status = debeziumService.getConnectorStatus("my-connector-v1");
+ConnectorStatus status = debeziumService.getConnectorStatus("openframe-mongo-v1");
 if (status == null) {
     log.warn("Connector not found or Kafka Connect unreachable");
 }
 
-// List all active connectors
-List<String> connectors = debeziumService.listConnectors();
-```
-
-> **Note:** `RecreationTracker` is optional (`required = false`). When absent, drift-driven recreation proceeds without rate-limiting. The service reads `openframe.debezium.base-url`, `connect-timeout` (default `5s`), and `read-timeout` (default `30s`) from application properties.
\ No newline at end of file
+// Remove a stale versioned connector
+debeziumService.deleteConnector("openframe-mongo-v0");
+```
\ No newline at end of file
diff --git a/openframe-exception/src/main/java/com/openframe/core/exception/.ErrorCode.md b/openframe-exception/src/main/java/com/openframe/core/exception/.ErrorCode.md
index 646228a75..7e0024658 100644
--- a/openframe-exception/src/main/java/com/openframe/core/exception/.ErrorCode.md
+++ b/openframe-exception/src/main/java/com/openframe/core/exception/.ErrorCode.md
@@ -1,38 +1,41 @@
-<!-- source-hash: 9766ca9f6334d892855b69cb0b90d7ca -->
-Enum defining standardized error codes paired with their corresponding HTTP status codes for the OpenFrame platform's exception handling system.
+<!-- source-hash: b90b7054307ba96e1127a995f0bee427 -->
+Enum defining all standardized error codes used across the OpenFrame platform, pairing each error with a string identifier and its corresponding HTTP status code.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `code` | `String` | Machine-readable error identifier string |
-| `httpStatus` | `int` | Associated HTTP status code |
-| `getCode()` | Method | Returns the string error code |
-| `getHttpStatus()` | Method | Returns the HTTP status integer |
+| `code` | `String` | Machine-readable error identifier returned in API responses |
+| `httpStatus` | `int` | HTTP status code associated with the error |
+| `getCode()` | `String` | Returns the string error code |
+| `getHttpStatus()` | `int` | Returns the HTTP status integer |
 
-### Error Categories
+**Error categories:**
 
 | Category | Examples |
 |----------|---------|
-| Generic HTTP | `NOT_FOUND`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `CONFLICT`, `INTERNAL_ERROR` |
-| Domain-specific | `USER_NOT_FOUND`, `DEVICE_NOT_FOUND`, `ENCRYPTION_FAILED`, `INITIAL_KEY_INVALID` |
-| External API | `EVENT_NOT_FOUND`, `ORGANIZATION_NOT_FOUND`, `ORGANIZATION_HAS_MACHINES` |
-| Tag | `TAG_NOT_FOUND`, `TAG_ALREADY_EXISTS` |
-| Authorization | `USER_ACTIVE_IN_ANOTHER_TENANT` |
+| Generic HTTP | `NOT_FOUND`, `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN` |
+| Domain | `USER_NOT_FOUND`, `DEVICE_NOT_FOUND`, `ENCRYPTION_FAILED` |
+| Tickets | `TICKET_NOT_FOUND`, `TICKET_INVALID_TRANSITION`, `TICKET_AI_DISABLED` |
+| Authorization | `USER_ACTIVE_IN_ANOTHER_TENANT`, `OWNER_CANNOT_SWITCH_TENANT` |
 | Infrastructure | `PINOT_QUERY_ERROR`, `DATABASE_ERROR` |
 
 ## Usage Example
 
 ```java
-// Throwing a domain exception using an ErrorCode
-throw new OpenFrameException(ErrorCode.DEVICE_NOT_FOUND);
-
-// Accessing code and status directly
-ErrorCode error = ErrorCode.VALIDATION_ERROR;
-System.out.println(error.getCode());       // "VALIDATION_ERROR"
-System.out.println(error.getHttpStatus()); // 400
-
-// Mapping to an HTTP response
-ResponseEntity.status(error.getHttpStatus())
-    .body(Map.of("error", error.getCode()));
+// Throwing a domain exception with a specific ErrorCode
+if (user == null) {
+    throw new OpenFrameException(ErrorCode.USER_NOT_FOUND);
+}
+
+// Reading code and status from the enum
+ErrorCode error = ErrorCode.TICKET_INVALID_TRANSITION;
+int status = error.getHttpStatus(); // 409
+String code  = error.getCode();    // "TICKET_INVALID_TRANSITION"
+
+// Using in an API error response builder
+ApiErrorResponse response = ApiErrorResponse.builder()
+    .code(ErrorCode.FORBIDDEN.getCode())
+    .httpStatus(ErrorCode.FORBIDDEN.getHttpStatus())
+    .build();
 ```
\ No newline at end of file
diff --git a/openframe-external-api-service-core/src/main/java/com/openframe/external/service/.RestProxyService.md b/openframe-external-api-service-core/src/main/java/com/openframe/external/service/.RestProxyService.md
index 160c29edb..179b3f1c0 100644
--- a/openframe-external-api-service-core/src/main/java/com/openframe/external/service/.RestProxyService.md
+++ b/openframe-external-api-service-core/src/main/java/com/openframe/external/service/.RestProxyService.md
@@ -1,35 +1,32 @@
-<!-- source-hash: 0d68c4b1736e188cc4e5710a7be25200 -->
-A Spring service that proxies HTTP requests to external integrated tools, handling authentication, URL resolution, and request forwarding with comprehensive error handling and logging.
+<!-- source-hash: 0edb7b222fa265b9797c30f441fd76a5 -->
+Proxies HTTP requests from incoming servlet requests to configured external tool APIs, handling authentication header injection and URL resolution for integrated MSP tools.
 
 ## Key Components
 
-- **proxyApiRequest()** - Main entry point that validates tools and proxies incoming HTTP requests
-- **buildApiRequestHeaders()** - Constructs request headers with authentication (API key, Bearer token, or none)
-- **proxy()** - Executes the HTTP request to the target service and returns the response
-- **createHttpRequest()** - Factory method for creating Apache HTTP client request objects
-- **createHttpClient()** - Configures HTTP client with timeouts and connection settings
+- **`proxyApiRequest(String toolId, HttpServletRequest, String body)`** — Entry point that validates the tool exists and is enabled, resolves the target URI, builds auth headers, and delegates to `proxy()`.
+- **`buildApiRequestHeaders(IntegratedTool)`** — Constructs request headers including `Content-Type`/`Accept` defaults and injects credentials based on `APIKeyType` (`HEADER`, `BEARER_TOKEN`, or `NONE`).
+- **`proxy(IntegratedTool, URI, String method, Map headers, String body)`** — Executes the outbound HTTP request using Apache HttpClient 5, forwards headers and body, and returns the upstream status code and response body.
+- **`createHttpRequest(String method, URI)`** — Maps HTTP method strings to typed Apache HC5 request objects (`HttpGet`, `HttpPost`, `HttpPut`, `HttpPatch`, `HttpDelete`, `HttpOptions`).
+- **`createHttpClient()`** — Builds a shared `CloseableHttpClient` with a 10-second connection timeout and 60-second response timeout.
 
 ## Usage Example
 
 ```java
-@Autowired
-private RestProxyService restProxyService;
-
-// Proxy a request to an external tool
-public ResponseEntity<String> handleToolRequest(
-    @PathVariable String toolId,
-    HttpServletRequest request,
-    @RequestBody String body) {
-    
-    return restProxyService.proxyApiRequest(toolId, request, body);
-}
+// Injected via Spring context
+@RestController
+public class ToolProxyController {
+
+    private final RestProxyService proxyService;
 
-// The service handles:
-// - Tool validation and enablement checks
-// - URL resolution through ProxyUrlResolver
-// - Authentication header injection
-// - HTTP method mapping (GET, POST, PUT, PATCH, DELETE, OPTIONS)
-// - Response forwarding with original status codes
+    @RequestMapping("/tools/{toolId}/**")
+    public ResponseEntity<String> proxy(
+            @PathVariable String toolId,
+            HttpServletRequest request,
+            @RequestBody(required = false) String body) {
+
+        return proxyService.proxyApiRequest(toolId, request, body);
+    }
+}
 ```
 
-The service supports multiple authentication types (header-based API keys and Bearer tokens), includes comprehensive logging at INFO and DEBUG levels, and provides robust error handling with appropriate HTTP status codes for various failure scenarios.
\ No newline at end of file
+> **Note:** The service resolves tool API base URLs via `ToolUrlService` (type `API`) and builds the full target URI using `ProxyUrlResolver`, stripping the `/tools` prefix from the incoming path before forwarding.
\ No newline at end of file
diff --git a/openframe-frontend-core/.tsup.config.md b/openframe-frontend-core/.tsup.config.md
index 937dd9d49..96644b7c2 100644
--- a/openframe-frontend-core/.tsup.config.md
+++ b/openframe-frontend-core/.tsup.config.md
@@ -1,50 +1,39 @@
-<!-- source-hash: ccf98e3cd521ae06a03d9f6ee736d517 -->
-Configures the dual-build pipeline for the shared UI library, splitting outputs into server-safe and client-side bundles to prevent React context errors in Next.js server environments.
+<!-- source-hash: 9373efae61fa207f708b22f47e22fed7 -->
+Configures the dual-build pipeline for the component library using `tsup`, splitting output into server-safe and client-side bundles to correctly handle Next.js `"use client"` boundaries.
 
 ## Key Components
 
-**Build 1 — Server/Universal Entries**
-Compiles pure types, configs, NATS utilities, Zod schemas, assets, fonts, and Tailwind config. Targets both `esm` and `cjs` formats with `treeshake: true` and no `"use client"` banner.
+**Server/Universal Build**
+- Compiles pure types, configs, schemas, fonts, utilities, and server-safe constants (e.g. Mux CDN origins, Zod contact schema)
+- `treeshake: true` — enables dead code elimination
+- No `"use client"` banner — safe for server-side imports
 
-| Entry | Source |
-|---|---|
-| `nats/index` | NATS messaging utilities |
-| `types/*` | Shared TypeScript types (navigation, announcements) |
-| `schemas/contact-schema` | Zod validation schema (server + client shared) |
-| `utils/index` | Server-safe utility functions |
-| `assets/index`, `fonts`, `tailwind.config` | Static assets and styling config |
+**Client Build**
+- Compiles React components, hooks, contexts, NATS bindings, and embed shims
+- `banner: { js: '"use client";' }` — prepends `"use client"` to every output file, establishing a Next.js Client Component boundary
+- `splitting: true` — enables code splitting for the larger component surface; `treeshake` omitted (incompatible with `banner`)
 
-**Build 2 — Client Entries**
-Compiles all React components, hooks, contexts, and embed shims. Injects `"use client";` as a banner on every output file so Next.js treats them as Client Component boundaries. Uses `splitting: true` instead of `treeshake` (incompatible with `banner`).
+**Embed Shims**
+- Individual entries per Next.js adapter (`next-image`, `next-link`, `next-dynamic`, `next-navigation`) allowing deep imports without loading the full barrel
 
-| Entry Group | Contents |
-|---|---|
-| `components/*` | UI, chat, tickets, contact, features, toast, icons, navigation |
-| `hooks/index` | React hooks |
-| `contexts/index` | React context providers |
-| `embed-shims/*` | Per-entry wrappers for `next/dynamic`, `next/link`, `next/image`, `next/navigation` |
-
-## Key Design Decisions
-
-- **`dts: false`** on both builds — declarations are generated separately via `tsc` + `tsconfig.declarations.json` to produce `.d.ts.map` files for source navigation
-- **`treeshake` vs `banner`** are mutually exclusive — Rollup strips banners during tree-shaking, so each build uses only one
-- **`dist/` cleanup** is handled by the build script (`rm -rf dist`) rather than `clean: true`
-- **Embed shims as individual entries** — allows deep imports (`embed-shims/next-image`) without loading the full barrel
+**Shared Settings (both builds)**
+- Output formats: `esm` + `cjs`
+- `dts: false` — declarations are generated separately via `tsc` to produce `.d.ts.map` files
+- `sourcemap: true`
+- Externals: `react`, `react-dom`, `next`, `@tanstack/react-query`
 
 ## Usage Example
 
 ```bash
-# Build both server and client bundles
-rm -rf dist && tsup && tsc -p tsconfig.declarations.json
+# Declarations generated by tsc (see tsconfig.declarations.json)
+# dist/ is cleaned by the build script before tsup runs
+tsup
 ```
 
 ```typescript
-// Server-safe import (no "use client" boundary crossed)
-import { contactSchema } from '@your-lib/schemas/contact-schema'
-
-// Client component import (banner ensures Next.js treats as client boundary)
-import { Button } from '@your-lib/components/ui'
+// Deep import a server-safe schema (no client boundary pollution)
+import { contactSchema } from '@flamingo/ui/schemas/contact-schema'
 
-// Deep embed-shim import without pulling full barrel
-import { NextImage } from '@your-lib/embed-shims/next-image'
+// Deep import a single embed shim without loading the full barrel
+import { NextImageShim } from '@flamingo/ui/embed-shims/next-image'
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.content-loading-container.md b/openframe-frontend-core/src/components/.content-loading-container.md
index 6df8e2f21..95812d1ad 100644
--- a/openframe-frontend-core/src/components/.content-loading-container.md
+++ b/openframe-frontend-core/src/components/.content-loading-container.md
@@ -1,40 +1,52 @@
-<!-- source-hash: 136d5eb8692fb936306eaef6f2ae6216 -->
-A React component that provides smooth loading transitions with skeleton states while preventing layout jumps during content loading.
+<!-- source-hash: b7d95eae06e3f4248319cf0584641bd9 -->
+A unified container component that manages content loading states by overlaying skeleton components while keeping layout dimensions stable and preventing UI jumps.
 
 ## Key Components
 
-- **ContentLoadingContainer** - Main component that overlays skeleton loading states over actual content
-- **useContentLoading** - Hook providing common loading state patterns and utilities for different content types
+### `ContentLoadingContainer`
+Main exported component that wraps content with a skeleton overlay during loading states.
 
-## Core Features
+**Props:**
 
-- **Layout Stability** - Maintains consistent dimensions during loading with configurable `minHeight`
-- **Smooth Transitions** - Customizable opacity transitions between loading and loaded states
-- **Accessibility** - Proper ARIA labels, live regions, and screen reader support
-- **Flexible Skeletons** - Accepts any skeleton component for different content types
-- **Visual Overlay** - Dark background overlay that smoothly fades in/out during state changes
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | — | Controls loading/loaded state |
+| `children` | `ReactNode` | — | Content rendered when loaded |
+| `skeletonComponent` | `ReactNode` | — | Skeleton shown during loading |
+| `className` | `string` | — | Additional CSS classes |
+| `minHeight` | `string` | `"min-h-[300px] md:min-h-[800px]"` | Prevents layout jumps |
+| `loadingOpacity` | `number` | `1` | Overlay opacity (0–1) |
+| `transitionDuration` | `number` | `300` | Fade transition in ms |
+
+### `useContentLoading`
+Helper hook that returns ARIA container props and utility functions for common content types.
+
+**Returns:**
+
+| Member | Description |
+|--------|-------------|
+| `containerProps` | `aria-busy` and `data-loading` attributes |
+| `getSkeletonCount(type)` | Returns `12` for `vendor`, `6` for `blog` |
+| `getMinHeight(type)` | Returns type-appropriate `min-h` Tailwind class |
 
 ## Usage Example
 
 ```typescript
-import { ContentLoadingContainer, useContentLoading } from './content-loading-container'
+import { ContentLoadingContainer, useContentLoading } from "./content-loading-container"
+import { CardSkeletonGrid } from "./card-skeleton-grid"
 
 function VendorPage() {
-  const [vendors, setVendors] = useState([])
-  const [isLoading, setIsLoading] = useState(true)
+  const { isLoading, vendors } = useVendors()
   const { getMinHeight, getSkeletonCount } = useContentLoading(isLoading)
 
   return (
     <ContentLoadingContainer
       isLoading={isLoading}
       skeletonComponent={
-        <CardSkeletonGrid 
-          variant="vendor" 
-          count={getSkeletonCount('vendor')} 
-        />
+        <CardSkeletonGrid variant="vendor" count={getSkeletonCount("vendor")} />
       }
-      minHeight={getMinHeight('vendor')}
-      transitionDuration={200}
+      minHeight={getMinHeight("vendor")}
+      transitionDuration={400}
     >
       <VendorGrid vendors={vendors} />
     </ContentLoadingContainer>
@@ -42,4 +54,4 @@ function VendorPage() {
 }
 ```
 
-The component uses absolute positioning to overlay the skeleton during loading while keeping the actual content rendered but hidden, ensuring smooth transitions without DOM manipulation delays.
\ No newline at end of file
+> The skeleton overlay uses `absolute` positioning over the container, while actual content fades from `opacity-0` to visible — both transitions respect `transitionDuration` for a smooth UX. Full ARIA support (`aria-live`, `aria-busy`, `role="status"`) ensures screen readers announce loading state changes.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.empty-state.md b/openframe-frontend-core/src/components/.empty-state.md
index 82e1e8d06..16ff8674d 100644
--- a/openframe-frontend-core/src/components/.empty-state.md
+++ b/openframe-frontend-core/src/components/.empty-state.md
@@ -1,52 +1,49 @@
-<!-- source-hash: 50c4ce7ece14f33f4a6cb6591ed66364 -->
-A reusable React client component that renders context-aware empty state UI for vendors, posts, search results, or generic scenarios — with smart CTA logic that adapts based on the current URL path.
+<!-- source-hash: 1582ab9459a52542a48304eea16b4b71 -->
+A reusable React component that renders contextual empty states for vendors, posts, search results, and generic scenarios, with smart CTA logic that adapts based on the current URL path.
 
 ## Key Components
 
 ### `EmptyStateProps` Interface
-
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `type` | `'vendors' \| 'posts' \| 'search' \| 'generic'` | required | Determines default icon, title, and description |
-| `title` | `string` | — | Overrides default title |
-| `description` | `string` | — | Overrides default description |
+| `type` | `'vendors' \| 'posts' \| 'search' \| 'generic'` | — | Determines default icon, title, and description |
+| `title` | `string` | auto | Overrides default title for the given type |
+| `description` | `string` | auto | Overrides default description |
 | `showBackButton` | `boolean` | `false` | Renders an optional back button |
-| `onGoBack` | `() => void` | — | Handler for the back button |
-| `backButtonText` | `string` | `"Go Back"` | Back button label |
+| `onGoBack` | `() => void` | — | Callback for the back button |
 | `showCTA` | `boolean` | `true` | Toggles the smart CTA button |
-| `ctaText` | `string` | — | Overrides smart CTA label |
-| `onCtaClick` | `() => void` | — | Overrides smart CTA action |
-| `ctaVariant` | `'primary' \| 'secondary'` | `'primary'` | CTA button styling |
+| `ctaText` | `string` | auto | Custom CTA label (requires `onCtaClick`) |
+| `onCtaClick` | `() => void` | auto | Custom CTA handler |
+| `ctaVariant` | `'primary' \| 'secondary'` | `'primary'` | Button style variant |
 
 ### Internal Helpers
-
-- **`getDefaultContent()`** — Returns icon, title, and description based on `type`
-- **`getSmartCTA()`** — Derives CTA label and action from `type` + current pathname (e.g., resets filters on `/vendors` or `/blog`, navigates to `/vendors` from `/profile`)
+- **`getDefaultContent()`** — Maps `type` to a Lucide icon, title, and description
+- **`getSmartCTA()`** — Derives CTA text and navigation action from `type` + `window.location.pathname`, falling back to custom props if provided
 
 ## Usage Example
 
 ```typescript
-// Basic usage
+// Basic usage with type defaults
 <EmptyState type="vendors" />
 
-// Search with custom CTA
+// Search with custom title
 <EmptyState
   type="search"
-  title="No results"
-  description="Try different keywords."
-  ctaText="Clear Search"
-  onCtaClick={() => setQuery('')}
-  ctaVariant="secondary"
+  title="No matching results"
+  description="Try broadening your search terms."
 />
 
-// With back button, no CTA
+// Custom CTA and back button
 <EmptyState
   type="posts"
-  showCTA={false}
-  showBackButton={true}
+  showCTA
+  ctaText="Start Writing"
+  onCtaClick={() => router.push('/blog/new')}
+  ctaVariant="secondary"
+  showBackButton
   onGoBack={() => router.back()}
-  backButtonText="Return to Feed"
+  backButtonText="Return"
 />
 ```
 
-> **Smart CTA behavior:** When no `ctaText`/`onCtaClick` is provided, the component inspects `window.location.pathname` to decide whether to reset URL filters or navigate to `/vendors` or `/blog`.
\ No newline at end of file
+> **Note:** Smart CTA routing is path-aware — for example, `type="vendors"` on `/vendors` renders **Reset Filters**, while on `/profile` it renders **Browse Vendors**.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.faq-accordion.md b/openframe-frontend-core/src/components/.faq-accordion.md
index dfa6702b8..fa30e3a8a 100644
--- a/openframe-frontend-core/src/components/.faq-accordion.md
+++ b/openframe-frontend-core/src/components/.faq-accordion.md
@@ -1,17 +1,17 @@
-<!-- source-hash: 287c2bd98ac7a3ef2c0c3e9abfc07ed3 -->
-Accessible, animated FAQ accordion component that renders a list of question/answer pairs with smooth height transitions and keyboard navigation support.
+<!-- source-hash: 5e7d46caa4a813430cc5fe32d76d8776 -->
+Accessible FAQ accordion component with animated expand/collapse transitions, supporting multiple simultaneously open items and keyboard navigation.
 
 ## Key Components
 
 ### Interfaces
-- **`FaqItem`** — Data shape for each FAQ entry (`id`, `question`, `answer`)
-- **`FaqAccordionProps`** — Component props accepting `items` array and optional `defaultOpenIds` for pre-expanded panels
+- **`FaqItem`** — Shape of each FAQ entry: `id`, `question`, `answer`
+- **`FaqAccordionProps`** — Accepts an `items` array and optional `defaultOpenIds` for pre-expanded entries
 
-### Hooks
-- **`useMeasuredHeight(isOpen)`** — Internal hook that measures `scrollHeight` outside the render cycle to drive CSS `max-height` animations; returns `ref` and `maxHeight` string
+### Hook
+- **`useMeasuredHeight(isOpen)`** — Internal hook that measures `scrollHeight` outside the render cycle to drive smooth `max-height` CSS transitions, returning a `ref` and `maxHeight` string
 
 ### Component
-- **`FaqAccordion`** — Main export; manages a `Set`-based open/close state, renders each item with animated expansion, `aria-expanded` attribute, and keyboard (`Enter`/`Space`) support
+- **`FaqAccordion`** — Renders a bordered card list where each row toggles independently; uses a `Set` to track open IDs, supports multiple open items simultaneously
 
 ## Usage Example
 
@@ -19,30 +19,16 @@ Accessible, animated FAQ accordion component that renders a list of question/ans
 import { FaqAccordion, FaqItem } from './faq-accordion'
 
 const faqs: FaqItem[] = [
-  {
-    id: 1,
-    question: 'What is Flamingo?',
-    answer: 'Flamingo is an AI-powered MSP platform that replaces expensive proprietary software.',
-  },
-  {
-    id: 2,
-    question: 'What is OpenFrame?',
-    answer: 'OpenFrame is a unified platform integrating multiple MSP tools into a single AI-driven interface.',
-  },
+  { id: 1, question: 'What is Flamingo?', answer: 'An AI-powered MSP platform.' },
+  { id: 2, question: 'What is OpenFrame?', answer: 'A unified AI-driven IT support interface.' },
 ]
 
-export default function FaqPage() {
-  return (
-    <FaqAccordion
-      items={faqs}
-      defaultOpenIds={[1]} // First item open by default
-    />
-  )
-}
+// Render with the second item open by default
+<FaqAccordion items={faqs} defaultOpenIds={[2]} />
 ```
 
 ## Notes
 
-- Multiple panels can be open simultaneously
-- Height animation uses a measured `scrollHeight` approach rather than fixed values, so dynamic content is handled correctly
-- Fully keyboard accessible via `role="button"`, `tabIndex`, and `onKeyDown` handlers
\ No newline at end of file
+- **Accessibility** — Each header uses `role="button"`, `tabIndex={0}`, `aria-expanded`, and handles `Enter`/`Space` keydown events
+- **Animation** — `max-height` and `opacity` transition over `0.35s ease-in-out`; height is measured lazily only when an item opens
+- **Styling** — Uses `ods-*` design tokens and `cn()` utility for conditional class merging
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.footer-waitlist-button.md b/openframe-frontend-core/src/components/.footer-waitlist-button.md
index 92a21bf88..fe64b8522 100644
--- a/openframe-frontend-core/src/components/.footer-waitlist-button.md
+++ b/openframe-frontend-core/src/components/.footer-waitlist-button.md
@@ -1,25 +1,23 @@
-<!-- source-hash: 8e25a68fa3e51dd5cde8b484877f10f2 -->
-A footer button component that navigates users to the OpenFrame waitlist page, routing through the unified navigation system when available.
+<!-- source-hash: 4d908f9cf7af91751965e17795b7dff2 -->
+A footer UI component that renders a "Join Waitlist" button, routing navigation through the unified `ChatRuntimeContext` navigation system or falling back to the embed-shim router.
 
 ## Key Components
 
-### `FooterWaitlistButtonProps`
+**`FooterWaitlistButtonProps`**
 - `className?: string` — Optional CSS class for styling overrides.
 
-### `FooterWaitlistButton`
-A `Button` wrapper that handles navigation to `/waitlist#top` via a two-tier fallback strategy:
-
-1. **Primary:** `runtime.navigation.navigate` — the host's unified-nav hook (provided by `HubRuntimeProvider`), which handles cross-platform new-tab decisions, same-URL re-scroll, and embed-mode short-circuiting.
-2. **Fallback:** `router.push` via the embed-shim's `useRouter` — used when no `ChatRuntimeContext` is mounted (e.g., third-party embedders).
-
-Renders with the `OpenFrameLogo` icon as a left icon inside the button.
+**`FooterWaitlistButton`**
+- Reads the host's `ChatRuntimeContext` via `useChatRuntime()` to access `runtime.navigation.navigate`.
+- Uses `executeNavigationImperative` to route clicks through the unified navigation pipeline (handles cross-platform new-tab logic, embed-mode short-circuiting, same-URL re-scroll, etc.).
+- Falls back to `router.push` (embed-shim) when no `ChatRuntimeContext` is mounted, keeping the component usable in third-party embed scenarios.
+- Navigates to `/waitlist#top`, where `#top` maps to an explicit `<div id="top">` anchor for reliable cross-browser scroll behavior.
 
 ## Usage Example
 
 ```typescript
+// Standard usage inside a footer layout
 import { FooterWaitlistButton } from './footer-waitlist-button';
 
-// Basic usage inside a footer layout
 export function AppFooter() {
   return (
     <footer>
@@ -29,17 +27,15 @@ export function AppFooter() {
 }
 ```
 
-> **Navigation note:** The `#top` anchor targets an explicit `<div id="top">` at the top of the waitlist page's `<main>` element, ensuring consistent scroll behavior across all browsers regardless of HTML5 magic-anchor handling.
+```typescript
+// Without ChatRuntimeContext (third-party embed fallback)
+// No additional setup needed — component auto-detects missing
+// runtime and falls back to embed-shim router.push
+import { FooterWaitlistButton } from './footer-waitlist-button';
 
-## Navigation Flow
+export function EmbedFooter() {
+  return <FooterWaitlistButton />;
+}
+```
 
-```mermaid
-graph TD
-    A["FooterWaitlistButton clicked"] --> B{"runtime.navigation.navigate available?"}
-    B -->|Yes| C["Call runtime.navigation.navigate"]
-    C --> D{"Handled?"}
-    D -->|Yes| E["Done - unified nav handled"]
-    D -->|No| F["Fallback: router.push"]
-    B -->|No| F
-    F --> G["Navigate to /waitlist#top"]
-```
\ No newline at end of file
+> **Note:** For full unified navigation features (new-tab decisions, embed-mode handling), wrap the component tree with `ChatRuntimeContext` via `HubRuntimeProvider`. Without it, basic `router.push` navigation to `/waitlist#top` is used instead.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.index.md b/openframe-frontend-core/src/components/.index.md
index f8058107d..5dedf8f23 100644
--- a/openframe-frontend-core/src/components/.index.md
+++ b/openframe-frontend-core/src/components/.index.md
@@ -1,42 +1,49 @@
-<!-- source-hash: 6641c546041f6054d9c547ffd4f0f173 -->
-Central barrel export file for the Flamingo/OpenFrame shared UI component library. Re-exports all components, hooks, and utilities from the component subdirectories and individual component modules, enabling single-import access across the platform.
+<!-- source-hash: ae3de92dfcbda63bfa0ed185b75a96d7 -->
+Central barrel export file for the Flamingo/OpenFrame shared UI component library, re-exporting all components, utilities, and types from their respective subdirectories and modules for unified package consumption.
 
 ## Key Components
 
-The file organizes exports into logical groups:
+Organized into the following export groups:
 
-| Group | Source |
-|---|---|
-| **Component Directories** | `chat`, `features`, `icons`, `navigation`, `platform`, `ui` |
-| **Individual Components** | `announcement-bar`, `media-carousel`, `pricing-display`, `vendor-display-button`, etc. |
-| **Shared Modules** | `onboarding`, `product-release`, `dev-section`, `roadmap`, `delivery`, `legal-document` |
-| **Utilities** | `unified-filter-logic`, `unified-pagination`, `persistent-filter-controls` |
-| **Auth & Loading** | `auth-stub`, `loading` |
-| **Date/Time** | `date-time-picker` |
+| Group | Path | Description |
+|-------|------|-------------|
+| **Core UI** | `./ui` | Base UI primitives and page containers |
+| **Chat** | `./chat` | AI chat interface components (Mingo/Fae) |
+| **Navigation** | `./navigation` | App navigation components |
+| **Platform** | `./platform` | MSP platform-specific components |
+| **Features** | `./features` | Feature-flag-driven components |
+| **Shared/Onboarding** | `./shared/onboarding` | Client/technician onboarding flows |
+| **Shared/Doc Search** | `./shared/doc-search` | RAG-powered search dropdown (data-room + guide catalog) |
+| **Shared/Dev Section** | `./shared/dev-section` | Roadmap, delivery, and DevSectionView chrome |
+| **Shared/Legal** | `./shared/legal-document` | Privacy policy, terms of service renderer |
+| **Loading** | `./loading` | Skeleton and loading state components |
+| **Auth** | `./auth-stub` | Authentication stub components |
 
-Notable named export: `DetailPageSkeleton` and its `DetailPageSkeletonProps` type are explicitly re-exported from `./shared/detail-page-skeleton`.
+Notable named export:
+
+```typescript
+export { DetailPageSkeleton, type DetailPageSkeletonProps } from './shared/detail-page-skeleton'
+```
 
 ## Usage Example
 
 ```typescript
-// Instead of deep imports across many paths:
-import { VendorIcon } from '@flamingo/components/vendor-icon'
-import { Pagination } from '@flamingo/components/pagination'
-
-// Import everything from the single barrel:
+// Import any component directly from the shared package
 import {
+  AnnouncementBar,
+  EmptyState,
+  MetricValue,
+  PricingDisplay,
   VendorIcon,
-  Pagination,
   DetailPageSkeleton,
   type DetailPageSkeletonProps,
-  MspDisplay,
-  MediaCarousel,
-  UnifiedFilterLogic,
 } from '@flamingo/components'
-```
 
-## Notes
+// MSP-specific display components
+import { MspDisplay, UserDisplay, VendorDisplayButton } from '@flamingo/components'
+
+// Shared search + onboarding
+import { DocSearchBar, OnboardingGuide } from '@flamingo/components'
+```
 
-- Marked `"use client"` — all exported components are React Client Components (Next.js App Router compatible).
-- `PageContainer` is intentionally not re-exported here; it is already available via `./ui/page-container`.
-- Duplicate `chat` export exists in the file; only one is resolved at runtime.
\ No newline at end of file
+> **Note:** Marked `"use client"` — all exports are React Client Components and must be used within Next.js client boundaries. Server Components should import from individual submodules directly to avoid bundling the full client graph.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.logs-list.md b/openframe-frontend-core/src/components/.logs-list.md
index 59277476a..3e11c377c 100644
--- a/openframe-frontend-core/src/components/.logs-list.md
+++ b/openframe-frontend-core/src/components/.logs-list.md
@@ -1,36 +1,34 @@
-<!-- source-hash: a6c222ce8e1ab58308ac9ed1a6a4776e -->
-A scrollable log viewer component that renders a list of `LogEntry` items with severity indicators, timestamps, and optional tool icons, connected by visual timeline connectors.
+<!-- source-hash: cc82911fa048dc5d6f9239e14cb486bb -->
+Scrollable log entry list component that renders a collection of `LogEntry` items with severity indicators, timestamps, and optional tool icons, connected by a vertical timeline line.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `LogsList` | `React.ForwardRefExoticComponent` | Main container that renders a scrollable, bordered list of log entries |
-| `LogCard` | `React.FC` (internal) | Individual log row with severity dot, title, formatted timestamp, and optional tool icon |
-| `formatTimestamp` | `function` (internal) | Formats a `string \| Date` into `YYYY/MM/DD,HH:mm` display format |
+- **`LogsList`** — Main exported component (forwarded ref) that renders the log container with overflow scrolling, loading state, and empty state handling
+- **`LogCard`** — Internal card component for individual log entries with click/keyboard handlers, severity dot, formatted timestamp, and optional tool icon
+- **`formatTimestamp`** — Utility that formats a `string | Date` into `YYYY/MM/DD,HH:mm` display format
 
-### `LogsList` Props (`LogsListProps`)
+## Props (`LogsListProps`)
 
 | Prop | Default | Description |
 |------|---------|-------------|
 | `logs` | — | Array of `LogEntry` items to display |
-| `maxHeight` | `'400px'` | Container max height; use `'100%'` for full-height flex layout |
-| `showConnector` | `true` | Renders vertical timeline connector lines between entries |
+| `maxHeight` | `'400px'` | Container max height; use `'100%'` for full parent height |
+| `showConnector` | `true` | Renders vertical timeline connector between entries |
 | `onLogClick` | — | Callback fired with the clicked `LogEntry` |
-| `loading` | `false` | Shows a loading state placeholder |
-| `emptyMessage` | `'No logs to display'` | Message shown when `logs` is empty |
-| `className` | — | Additional Tailwind classes for the container |
+| `loading` | `false` | Shows a loading placeholder |
+| `emptyMessage` | `'No logs to display'` | Text shown when `logs` is empty |
+| `className` | — | Additional CSS classes for the container |
 
 ## Usage Example
 
 ```typescript
-import { LogsList } from './components/logs-list'
-import { LogEntry } from './types/logs.types'
+import { LogsList } from './logs-list'
+import { LogEntry } from '../types/logs.types'
 
 const logs: LogEntry[] = [
   {
     id: '1',
-    title: 'Agent task completed successfully',
+    title: 'Agent task completed',
     severity: 'info',
     timestamp: new Date(),
     toolType: 'bash',
@@ -38,17 +36,17 @@ const logs: LogEntry[] = [
   {
     id: '2',
     title: 'Connection timeout detected',
-    severity: 'warning',
+    severity: 'error',
     timestamp: '2024-01-15T10:30:00Z',
   },
 ]
 
-export default function LogsPanel() {
+export function ActivityPanel() {
   return (
     <LogsList
       logs={logs}
       maxHeight="500px"
-      showConnector={true}
+      showConnector
       onLogClick={(log) => console.log('Selected:', log.id)}
     />
   )
diff --git a/openframe-frontend-core/src/components/.media-carousel.md b/openframe-frontend-core/src/components/.media-carousel.md
index 58ecdcefb..2625b1ae1 100644
--- a/openframe-frontend-core/src/components/.media-carousel.md
+++ b/openframe-frontend-core/src/components/.media-carousel.md
@@ -1,48 +1,52 @@
-<!-- source-hash: 3e808df6d9836b82a787de725d9821af -->
-A responsive, accessible media carousel component supporting images, videos (MP4/HLS via MuxPlayer), and YouTube embeds with thumbnail navigation, swipe gestures, and keyboard controls.
+<!-- source-hash: b57b1ca61808efb762b7dc148c33bbbf -->
+A memoized React carousel component for displaying mixed media (images, videos, YouTube embeds) with thumbnail navigation, swipe/keyboard support, and configurable aspect ratios.
 
 ## Key Components
 
-### `MediaCarousel` (default export)
-A memoized React component with the following props:
+**`MediaCarousel`** — Primary exported component (memoized)
+- Accepts a `MediaItem[]` array supporting `'image'`, `'video'`, and `'youtube'` types
+- Delegates video/YouTube rendering to the shared `<Video>` component (MuxPlayer/lite-youtube facade)
+- Auto-clamps `currentIndex` when the media array shrinks to prevent stale selection state
+
+**Internal Renderers**
+- `renderImage` — Lazy-loaded `<img>` with configurable `objectFit`
+- `renderVideo` — MuxPlayer via `<Video>` (handles HLS + MP4)
+- `renderYouTubeEmbed` — lite-youtube facade via `<Video>`
+- `renderThumbnail` — Clickable thumbnail buttons; auto-generates YouTube poster URLs via `extractYouTubeId`
+
+**Navigation**
+- Arrow buttons (hover-revealed), keyboard (`ArrowLeft`/`ArrowRight`), and touch swipe (50px threshold)
+- `ChevronLeftIcon` / `ChevronRightIcon` — inline SVG nav icons
+
+## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `media` | `MediaItem[]` | — | Array of media items to display |
-| `className` | `string` | — | Additional CSS classes |
 | `aspectRatio` | `'16/9' \| '4/3' \| '3/2' \| '1/1'` | `'16/9'` | Container aspect ratio |
-| `showThumbnails` | `boolean` | `true` | Toggle thumbnail strip |
-| `autoPlay` | `boolean` | `false` | Auto-advance slides |
-| `objectFit` | `'contain' \| 'cover'` | `'contain'` | Image fit behavior |
-
-### Internal Renderers
-- `renderImage` — renders images with lazy loading and error fallback
-- `renderVideo` — delegates to `<Video>` (MuxPlayer facade) for MP4/HLS
-- `renderYouTubeEmbed` — delegates to `<Video>` with `kind="youtube"` for lite-youtube embed
-- `renderThumbnail` — clickable thumbnail with active indicator and video play overlay
+| `showThumbnails` | `boolean` | `true` | Show thumbnail strip |
+| `autoPlay` | `boolean` | `false` | Reserved for future use |
+| `objectFit` | `'contain' \| 'cover'` | `'contain'` | Image fit mode |
 
 ## Usage Example
 
 ```typescript
 import { MediaCarousel } from './media-carousel';
-import { MediaItem } from '../utils/media-carousel-utils-stub';
 
-const items: MediaItem[] = [
-  { type: 'image', src: 'https://example.com/photo.jpg', alt: 'Photo' },
-  { type: 'youtube', src: 'https://youtube.com/watch?v=dQw4w9WgXcQ', alt: 'Demo' },
-  { type: 'video', src: 'https://example.com/clip.mp4', poster: 'https://example.com/thumb.jpg' },
+const items = [
+  { type: 'image', src: '/hero.png', alt: 'Hero shot' },
+  { type: 'youtube', src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', alt: 'Demo' },
+  { type: 'video', src: '/demo.mp4', poster: '/demo-thumb.jpg', alt: 'Walkthrough' },
 ];
 
-<MediaCarousel
-  media={items}
-  aspectRatio="16/9"
-  showThumbnails={true}
-  objectFit="contain"
-/>
-```
-
-## Interaction Support
-- **Keyboard**: `←` / `→` arrow keys when carousel is focused
-- **Touch/Swipe**: 50px minimum swipe distance triggers slide change
-- **Hover**: Navigation arrows reveal on hover; hidden for single-item carousels
-- **Accessibility**: `role="region"` and `aria-label` applied when multiple items exist
\ No newline at end of file
+export function ProductGallery() {
+  return (
+    <MediaCarousel
+      media={items}
+      aspectRatio="16/9"
+      objectFit="cover"
+      showThumbnails={true}
+    />
+  );
+}
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.open-source-features.md b/openframe-frontend-core/src/components/.open-source-features.md
index 964f46c4c..2cc98a628 100644
--- a/openframe-frontend-core/src/components/.open-source-features.md
+++ b/openframe-frontend-core/src/components/.open-source-features.md
@@ -1,28 +1,34 @@
-<!-- source-hash: 86b90e3350490d5e683b6b4b06497f43 -->
-A Next.js client component that renders a responsive marketing section showcasing OpenFrame's open-source value propositions as a 4-column feature card grid.
+<!-- source-hash: 5e12de6def0e47f9cb53051e876023db -->
+A client-side React section component that renders a responsive grid of feature cards highlighting OpenFrame's open-source philosophy.
 
 ## Key Components
 
-- **`FeatureCard`** — Reusable card component accepting an icon, title, and description; renders with hover transition styling using ODS design tokens
-- **`OpenSourceFeatures`** — Main section component that composes the feature grid with a headline and four predefined feature entries
-- **`features` array** — Static data defining the four pillars: *Built on FOSS*, *Own Your Stack*, *Modular by Design*, and *Community-Powered*
-
-## Props
-
-### `FeatureCardProps`
+### `FeatureCard`
+A presentational card component displaying an icon, title, and description with hover styling.
 
+**Props (`FeatureCardProps`):**
 | Prop | Type | Description |
 |------|------|-------------|
-| `icon` | `React.ReactNode` | Lucide icon element rendered in the card header |
-| `title` | `string` | Feature headline text |
-| `description` | `string` | Supporting body copy |
+| `icon` | `React.ReactNode` | Lucide icon element |
+| `title` | `string` | Card heading |
+| `description` | `string` | Card body text |
+
+### `OpenSourceFeatures` (default export)
+Section component rendering four feature cards in a responsive 1→2→4 column grid with the heading **"100% Open-Source. 0% Bullsh*t."**
+
+**Feature cards:**
+| Icon | Title | Theme |
+|------|-------|-------|
+| `Terminal` | Built on FOSS | Transparency |
+| `DollarSign` | Own Your Stack | Cost control |
+| `Network` | Modular by Design | Flexibility |
+| `Users` | Community-Powered | Open roadmap |
 
 ## Usage Example
 
 ```typescript
 import OpenSourceFeatures from '@/components/open-source-features';
 
-// Drop into any page layout — no props required
 export default function LandingPage() {
   return (
     <main>
@@ -32,7 +38,7 @@ export default function LandingPage() {
 }
 ```
 
-To add a custom feature card standalone:
+Standalone card usage:
 
 ```typescript
 import { FeatureCard } from '@/components/open-source-features';
@@ -41,8 +47,8 @@ import { Shield } from 'lucide-react';
 <FeatureCard
   icon={<Shield className="w-6 h-6" />}
   title="Secure by Default"
-  description="Auditable code with no vendor lock-in."
+  description="Auditable components with no hidden dependencies."
 />
 ```
 
-> **Note:** `FeatureCard` is not a named export by default — export it explicitly if reuse outside this component is needed. The section uses ODS design tokens (`ods-card`, `ods-border`, `ods-accent`) from the OpenFrame design system.
\ No newline at end of file
+> **Note:** `FeatureCard` is not explicitly exported — extract it or re-export if standalone usage is needed.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.vendor-icon.md b/openframe-frontend-core/src/components/.vendor-icon.md
index a2bcfa08b..9bed9c196 100644
--- a/openframe-frontend-core/src/components/.vendor-icon.md
+++ b/openframe-frontend-core/src/components/.vendor-icon.md
@@ -1,52 +1,49 @@
-<!-- source-hash: f84ca33f36e32d62304615a416d5acac -->
-Renders a vendor logo icon with configurable size, background style, and fallback initials when no logo is available.
+<!-- source-hash: 4d59156b00f20c02d98dca1a215ddfb8 -->
+Renders a vendor logo icon with configurable size, background style, and fallback initials — designed for consistent vendor branding across cards, tables, and dropdowns.
 
 ## Key Components
 
-### `VendorIconProps`
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `vendor` | `VendorWithMedia & { id?, title, slug?, logo? }` | — | Vendor data including logo URL |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'l' \| 'xl'` | `'md'` | Icon container size |
-| `className` | `string` | `''` | Additional CSS classes |
-| `showBackground` | `boolean` | `true` | Toggles container background/border |
-| `backgroundStyle` | `'dark' \| 'light' \| 'white'` | `'dark'` | Container background variant |
-
-### Size Map
-| Size | Container | Image (px) |
-|------|-----------|------------|
-| `xs` | 24×24 | 16×16 |
-| `sm` | 32×32 | 20×20 |
-| `md` | 40×40 | 32×32 |
-| `lg` | 48×48 | 40×40 |
-| `xl` | 64×64 | 40×40 |
+**`VendorIconProps`** — Interface defining:
+- `vendor` — Vendor object extending `VendorWithMedia` with `title`, optional `id`, `slug`, and `logo`
+- `size` — One of `xs | sm | md | lg | l | xl` (default: `md`)
+- `showBackground` — Toggles rounded container with border (default: `true`)
+- `backgroundStyle` — Container theme: `dark | light | white` (default: `dark`)
+- `className` — Additional Tailwind classes for the container
 
-### `VendorIcon` (named export)
-The primary export. Resolves the logo via `getVendorLogo`, proxies the URL via `getProxiedImageUrl`, and falls back to a two-character uppercase initials placeholder when no logo is found.
+**`VendorIcon`** — Main exported component that:
+1. Resolves the logo URL via `getVendorLogo`
+2. Proxies the image URL via `getProxiedImageUrl`
+3. Renders an `<Image>` if a logo is available, or falls back to a 2-character uppercase abbreviation of `vendor.title`
 
 ## Usage Example
 
 ```typescript
 import { VendorIcon } from './vendor-icon'
 
-// Default dark background, medium size
-<VendorIcon vendor={vendor} />
+// With background (default)
+<VendorIcon vendor={vendor} size="lg" backgroundStyle="white" />
 
-// White background, large, no border
-<VendorIcon
-  vendor={vendor}
-  size="lg"
-  backgroundStyle="white"
-  showBackground={true}
-/>
+// Logo only, no container background
+<VendorIcon vendor={vendor} size="sm" showBackground={false} />
 
-// Logo only, no background (e.g. inside a styled card)
+// In a comparison table with custom class
 <VendorIcon
   vendor={vendor}
-  size="sm"
-  showBackground={false}
-  className="rounded-full"
+  size="xl"
+  backgroundStyle="light"
+  className="mx-auto"
 />
+
+// Fallback renders initials when logo is unavailable
+// e.g. vendor.title = "Acme Corp" → displays "AC"
 ```
 
-> When `logoUrl` resolves to `null` or `undefined`, the component renders a dark/light pill with the first two characters of `vendor.title` (e.g. `"MI"` for *Microsoft*).
\ No newline at end of file
+## Size Reference
+
+| Prop | Container | Image |
+|------|-----------|-------|
+| `xs` | 24×24 | 16×16 |
+| `sm` | 32×32 | 20×20 |
+| `md` | 40×40 | 32×32 |
+| `lg` | 48×48 | 40×40 |
+| `xl` | 64×64 | 40×40 |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.vendor-tag.md b/openframe-frontend-core/src/components/.vendor-tag.md
index 2590286bb..1cf26bcd5 100644
--- a/openframe-frontend-core/src/components/.vendor-tag.md
+++ b/openframe-frontend-core/src/components/.vendor-tag.md
@@ -1,49 +1,53 @@
-<!-- source-hash: 288686d02f75f571a8af9576a88762b3 -->
-A React component that renders categorized vendor tags with icons and styling for different software types and classifications.
+<!-- source-hash: ba846c52b7e939bb646adeb50a0aed1f -->
+A client-side React component that renders styled classification badges for vendors and tools, supporting multiple tag types (licensing, AI selection, OpenFrame status, etc.) with configurable size and appearance.
 
 ## Key Components
 
-- **VendorTag**: Main component that displays a styled tag with icon and text based on vendor type
-- **VendorTagProps**: Interface defining props including type, text, styling options, and size variants
-- **getTagContent()**: Internal function that maps vendor types to their corresponding icons, colors, and display text
-
-## Supported Tag Types
-
-The component supports various vendor classifications:
-- **Licensing**: `open-source`, `commercial`, `free`, `freemium`, `paid`, `enterprise`
-- **Selection**: `ai`, `manual`, `openframe_selected`, `recommended`
-- **Generic**: `classification`, `placeholder`
-
-Each type has predefined styling, icons, and color schemes with support for custom accent colors and text overrides.
+### `VendorTagProps` Interface
+| Prop | Type | Description |
+|------|------|-------------|
+| `type` | union string | Tag category — see supported types below |
+| `text` | `string` | Override default label text |
+| `className` | `string` | Additional CSS classes |
+| `size` | `'sm' \| 'md'` | Controls padding and font size |
+| `hidden` | `boolean` | Renders invisibly (preserves layout space) |
+| `accentColor` | `string` | Custom background color for the icon badge (open-source only) |
+
+### Supported `type` Values
+| Type | Default Label |
+|------|--------------|
+| `open-source` | Open Source |
+| `commercial` | Commercial Vendor |
+| `free` / `freemium` | Free / Freemium |
+| `paid` | Paid |
+| `enterprise` | Enterprise |
+| `recommended` | Recommended |
+| `ai` | AI Selected |
+| `manual` | Manually Selected |
+| `openframe_selected` | OpenFrame Selected |
+| `classification` | Dynamic — resolves based on `text` value |
+| `placeholder` | Placeholder |
+
+### `VendorTag` Function
+Main export. Uses `getTagContent()` internally to map `type` → `{ text, icon, textColor }` then renders a flex container with an icon badge and a monospace uppercase label.
 
 ## Usage Example
 
 ```typescript
 import { VendorTag } from './vendor-tag'
 
-// Basic open source tag
+// Basic open-source badge
 <VendorTag type="open-source" />
 
-// Custom commercial tag with accent color
-<VendorTag 
-  type="commercial" 
-  text="Enterprise Solution" 
-  accentColor="#ff6b35"
-  size="sm"
-/>
-
-// AI-selected tag with custom styling
-<VendorTag 
-  type="ai"
-  className="ml-2"
-  hidden={!showTags}
-/>
-
-// Classification tag with dynamic content
-<VendorTag 
-  type="classification"
-  text="openframe_selected"
-/>
-```
-
-The component uses Tailwind CSS classes with a dark theme design system (`ods-*` custom colors) and includes responsive sizing options.
\ No newline at end of file
+// AI-selected badge, small size
+<VendorTag type="ai" size="sm" />
+
+// Custom accent color for open-source
+<VendorTag type="open-source" accentColor="#4ECDC4" />
+
+// Classification resolved from text
+<VendorTag type="classification" text="openframe_selected" />
+
+// Hidden (invisible but still occupies space)
+<VendorTag type="recommended" hidden />
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/.why-it-matters.md b/openframe-frontend-core/src/components/.why-it-matters.md
index a55c1b0e1..7811fe7d7 100644
--- a/openframe-frontend-core/src/components/.why-it-matters.md
+++ b/openframe-frontend-core/src/components/.why-it-matters.md
@@ -1,30 +1,17 @@
-<!-- source-hash: 0a0456d4a0a372cdfeb0bc7afca3a55f -->
-A Next.js client component that renders a numbered list section highlighting the key value propositions of the OpenFrame/Flamingo platform.
+<!-- source-hash: 6b4a8aba56514b5977710031a0b744e4 -->
+A React client component that renders a styled "Why It Matters" section displaying four numbered value propositions for the Flamingo/OpenFrame platform.
 
 ## Key Components
 
-### `WhyItMattersItem` (internal)
-A list item component rendering a numbered entry with title and description. Accepts:
-- `number` — display number string (e.g. `"1."`)
-- `title` — short benefit headline
-- `description` — supporting copy
-- `isLast?` — omits bottom border on the final item
-
-### `WhyItMatters` (default export)
-The parent section component containing four hardcoded value propositions:
-
-| # | Title | Description |
-|---|-------|-------------|
-| 1 | Cut Costs | Eliminate vendor fees with proven open-source alternatives |
-| 2 | Stay in Control | Full visibility and data ownership |
-| 3 | Build What You Need | Customize without vendor limitations |
-| 4 | Scale Freely | Designed for multi-tenant MSP environments |
+- **`WhyItMattersItem`** — Internal list item component rendering a numbered entry with title and description. Accepts `number`, `title`, `description`, and optional `isLast` props to conditionally suppress the bottom border on the final item.
+- **`WhyItMatters`** — Default export. Renders the full section with a hardcoded list of four value propositions: Cut Costs, Stay in Control, Build What You Need, and Scale Freely.
 
 ## Usage Example
 
 ```typescript
 import WhyItMatters from '@/components/why-it-matters';
 
+// Drop into any page layout — no props required
 export default function LandingPage() {
   return (
     <main>
@@ -34,9 +21,21 @@ export default function LandingPage() {
 }
 ```
 
+To extend or customize the value propositions, update the `items` array inside `WhyItMatters`:
+
+```typescript
+const items = [
+  {
+    number: "1.",
+    title: "Your Custom Title",
+    description: "Your custom description text",
+  },
+  // ...
+];
+```
+
 ## Notes
 
-- Marked `"use client"` — requires a Next.js App Router client boundary.
-- Styled with Tailwind CSS using `ods-` design tokens (`ods-accent`, `ods-border`, `ods-text-primary`, `ods-card`).
-- Items hover to `#2A2A2A` with a smooth transition for subtle interactivity.
-- Layout is responsive: stacks vertically on mobile (`flex-col`), switches to row on `md+`.
\ No newline at end of file
+- Marked as `"use client"` — runs on the client side in Next.js App Router.
+- Styled exclusively with Tailwind CSS using design tokens (`ods-bg`, `ods-card`, `ods-accent`, `ods-text-primary`, `ods-border`) — ensure these are defined in your Tailwind config.
+- Layout is responsive: items stack vertically on mobile (`flex-col`) and switch to horizontal on `md+` breakpoints (`flex-row`).
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-archive-page.md b/openframe-frontend-core/src/components/chat/.chat-archive-page.md
new file mode 100644
index 000000000..b0a171de3
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-archive-page.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 07dbe6bd3d4374b48e5eef1d822e7c95 -->
+Renders the Chat Archive page within the chat panel, displaying a header with back/close navigation and a date-grouped list of archived dialogs powered by `MingoChatHistory`.
+
+## Key Components
+
+**`ChatArchivePage`** — Primary exported component that composes:
+- `ChatPanelHeaderMobile` — Mobile header (back + close) hidden on `md+`
+- Desktop header bar — Back chevron + title + close button (visible `md+`)
+- `MingoChatHistory` — Reused dialog list (pagination-aware, no row action menus)
+- Loading skeleton — 6 animated pulse rows matching dialog-item height
+- Empty state — Centered `BoxArchiveIcon` with instructional copy
+
+**`ChatArchivePageProps`** — Interface defining:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `dialogs` | `ReadonlyArray<DialogItem>` | Archived dialogs (pre-grouped by date) |
+| `onSelectDialog` | `(id: string) => void` | Opens a selected archived dialog |
+| `onBack` | `() => void` | Returns to previous list view |
+| `onClose` | `() => void` | Closes the entire chat panel |
+| `isLoading` | `boolean?` | Drives skeleton/spinner display |
+| `hasMore` | `boolean?` | Indicates additional pages available |
+| `onLoadMore` | `() => void?` | Fetches next page of dialogs |
+
+## Usage Example
+
+```typescript
+<ChatArchivePage
+  dialogs={archivedDialogs}
+  onSelectDialog={(id) => openDialog(id)}
+  onBack={() => setView('list')}
+  onClose={() => setChatOpen(false)}
+  isLoading={isFetching}
+  hasMore={pagination.hasNextPage}
+  onLoadMore={fetchNextPage}
+/>
+```
+
+The component renders three content states: a paginated dialog list when `dialogs.length > 0`, a pulse skeleton during initial load (`isLoading && dialogs.length === 0`), and an empty state when no archived chats exist.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-attachment-bar.md b/openframe-frontend-core/src/components/chat/.chat-attachment-bar.md
index e8fae3e5d..0512eb906 100644
--- a/openframe-frontend-core/src/components/chat/.chat-attachment-bar.md
+++ b/openframe-frontend-core/src/components/chat/.chat-attachment-bar.md
@@ -1,64 +1,41 @@
-<!-- source-hash: f3fb53b66abf55ba1b2ac14522e64cbb -->
-Provides two composable React primitives for the chat compose-box attachment UX: a `+` add-button rendered inline in the bottom controls row, and a horizontal chip strip rendered above the textarea showing staged file previews with upload progress.
+<!-- source-hash: 449b64d6486300a53ef74327aef340b7 -->
+Renders the attachment UI layer for the chat compose box: a horizontal chip strip (above the textarea) showing staged files with progress/status, and an icon-only `+` button (below the textarea) for picking new files.
 
 ## Key Components
 
 ### Exports
+- **`ChatAttachmentChipStrip`** — Renders a horizontal row of file chips above the textarea. Returns `null` when no attachments are staged.
+- **`ChatAttachmentAddButton`** — Borderless `+` icon button rendered inline in the bottom-controls row. Renders an invisible same-size `<span>` placeholder when `attachmentsEnabled` is `false` to prevent layout shift on async identity resolution.
+- **`StagedAttachment`** — Interface mirroring the hub's `useChatAttachments` output (`id`, `file`, `status`, `progress`, `storagePath`, `viewToken`, `errorMessage`).
+- **`ChatAttachmentSize`** — `'default' | 'compact'` density token for narrow surfaces (e.g. ticket-drawer reply composer).
+- **`CHAT_ATTACHMENT_MIME_TYPES`** — Curated allow-list (images + video); excludes `image/svg+xml` for XSS safety.
+- **`CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER`** — Client-side cap of 5 concurrent uploads.
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatAttachmentAddButton` | Component | Borderless `+` icon button for triggering file picker; renders an invisible 28×28 spacer when `attachmentsEnabled` is false to prevent layout shift |
-| `ChatAttachmentChipStrip` | Component | Horizontal strip of file chips above the textarea; returns `null` when no attachments are staged |
-| `StagedAttachment` | Interface | Shape consumed by the chip strip, mirrors the hub's `useChatAttachments` output |
-| `CHAT_ATTACHMENT_MIME_TYPES` | Constant | Allowed MIME types (JPEG, PNG, WebP, GIF, MP4, WebM, QuickTime) — excludes `image/svg+xml` for XSS safety |
-| `CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER` | Constant | Client-side cap of 5 concurrent staged files |
-
-### Internal Helpers
-
-| Name | Purpose |
-|------|---------|
-| `AttachmentChip` | Single chip: inline blob thumbnail (images), progress bar overlay, filename, status text, × remove button |
-| `useObjectUrl` | Hook managing `URL.createObjectURL` lifecycle — revokes on unmount and file change |
-| `formatFileSize` | Human-readable byte formatter (B / KB / MB / GB) |
-| `extLabel` | Extracts up to 3-char file extension for non-image chip placeholders |
+### Internal
+- **`AttachmentChip`** — Single file pill with blob-URL thumbnail preview (images), extension initials fallback, upload progress bar overlay, and `×` remove button.
 
 ## Usage Example
 
 ```typescript
 import {
-  ChatAttachmentAddButton,
   ChatAttachmentChipStrip,
-  StagedAttachment,
+  ChatAttachmentAddButton,
 } from './chat-attachment-bar'
 
-function Composebox() {
-  const { attachments, addFiles, removeFile } = useChatAttachments()
-  const { attachmentsEnabled } = useChatIdentity()
-
-  return (
-    <div className="flex flex-col">
-      {/* Chip strip floats above textarea — hidden when empty */}
-      <ChatAttachmentChipStrip
-        attachments={attachments}
-        onRemove={removeFile}
-        disabled={isStreaming}
-      />
-
-      <textarea placeholder="Message…" />
-
-      {/* Bottom controls row */}
-      <div className="flex items-center gap-2">
-        <ChatAttachmentAddButton
-          attachmentsEnabled={attachmentsEnabled}
-          attachmentsCount={attachments.length}
-          onAddFiles={addFiles}
-          disabled={isStreaming}
-        />
-        <ModelDisplay />
-      </div>
-    </div>
-  )
-}
-```
-
-> **Layout stability note:** `ChatAttachmentAddButton` renders an invisible `<span>` placeholder before `attachmentsEnabled` resolves, preventing the bottom-controls row from shifting when chat identity loads asynchronously (~100–500 ms).
\ No newline at end of file
+// Above textarea:
+<ChatAttachmentChipStrip
+  attachments={stagedAttachments}
+  onRemove={(id) => removeAttachment(id)}
+  disabled={isStreaming}
+  size="compact"
+/>
+
+// Inside bottom-controls row:
+<ChatAttachmentAddButton
+  attachmentsEnabled={identity.attachmentsEnabled}
+  attachmentsCount={stagedAttachments.length}
+  onAddFiles={(files) => addFiles(files)}
+  disabled={isStreaming}
+  size="compact"
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-composer.md b/openframe-frontend-core/src/components/chat/.chat-composer.md
new file mode 100644
index 000000000..4079af92e
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-composer.md
@@ -0,0 +1,60 @@
+<!-- source-hash: 3030823cbfb0980f8a7f1419c1385f28 -->
+Composes the chat panel footer by combining the message input (or archived placeholder) with the model/usage display row and an optional file attachment button.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatComposer` | `React.FC` | Main composer component rendering the full footer region |
+| `ChatComposerProps` | `interface` | Props contract for the composer |
+
+**Internal dependencies:** `ChatFooter`, `ChatInput`, `ChatAttachmentAddButton`, `ModelDisplay`, `BoxArchiveIcon`
+
+## Usage Example
+
+```typescript
+import { ChatComposer } from './chat-composer'
+import { useRef } from 'react'
+import type { ChatInputRef } from './types/component.types'
+
+function ChatPanel() {
+  const inputRef = useRef<ChatInputRef>(null)
+
+  return (
+    <ChatComposer
+      inputRef={inputRef}
+      onSend={(text) => console.log('Send:', text)}
+      onStop={() => console.log('Stop')}
+      sending={false}
+      placeholder="Type a message…"
+      autoFocus
+      model={{
+        modelName: 'gpt-4o',
+        tokensUsed: 1200,
+        tokenLimit: 8000,
+      }}
+      // Guide mode: enable file attachments
+      showAttachmentButton
+      attachmentsCount={2}
+      onAddFiles={(files) => handleFiles(files)}
+    />
+  )
+}
+
+// Archived (read-only) state — renders the unarchive prompt instead of input
+<ChatComposer
+  archived
+  inputRef={inputRef}
+  onSend={() => {}}
+  onStop={() => {}}
+  sending={false}
+  placeholder=""
+  model={modelProps}
+/>
+```
+
+## Behavior Notes
+
+- **`archived`** swaps the `ChatInput` for a read-only banner prompting the user to unarchive — no input is rendered
+- **`showAttachmentButton`** is Guide-only; omitting it (or `onAddFiles`) collapses the attachment slot entirely to avoid a 28 px ghost gap
+- Bottom padding respects the iOS safe-area inset via `max(xxs, env(safe-area-inset-bottom))`
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-container.md b/openframe-frontend-core/src/components/chat/.chat-container.md
index 283edeff3..5d3566977 100644
--- a/openframe-frontend-core/src/components/chat/.chat-container.md
+++ b/openframe-frontend-core/src/components/chat/.chat-container.md
@@ -1,15 +1,26 @@
-<!-- source-hash: 748948c6317fda009af640633bb6c0e5 -->
-Composable React components for building a full-screen chat interface shell, including layout, header, content area, and footer sections with ODS design token styling.
+<!-- source-hash: 5208b3e83fdf2b6f40585ec3be3fbe77 -->
+Provides the core layout primitives for Flamingo's chat UI shell, composing a full-screen chat view with a header, scrollable content area, and footer — used by both the Fae client assistant and Mingo AI technician interfaces.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `ChatContainer` | Root full-screen wrapper with ODS background and responsive padding |
-| `ChatHeader` | Rich header with avatar, user info, connection status, ticket context, and action buttons |
-| `ChatContent` | Flex-grow scrollable content region between header and footer |
-| `ChatFooter` | Sticky footer wrapper with optional full-width or narrow-column layout |
-| `ConnectionIndicator` | Internal dot badge showing `connected` / `connecting` / `disconnected` states using ODS attention tokens |
+| Export | Type | Description |
+|--------|------|-------------|
+| `ChatContainer` | `forwardRef<div>` | Root full-screen flex wrapper with ODS background/text tokens |
+| `ChatHeader` | `forwardRef<div>` | Avatar, name, connection status, ticket info, and action buttons |
+| `ChatContent` | `forwardRef<div>` | Flex-grow scrollable content column |
+| `ChatFooter` | `forwardRef<div>` | Sticky bottom wrapper with optional narrow-column constraint |
+| `ConnectionIndicator` | `FC` | Pulsing dot using ODS attention tokens (`connected` / `connecting` / `disconnected`) |
+
+### `ChatHeader` Notable Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `connectionStatus` | `'connected' \| 'connecting' \| 'disconnected'` | `'disconnected'` | Drives `ConnectionIndicator` dot color |
+| `serverUrl` | `string \| null` | `null` | Shows URL + dot when provided |
+| `ticketInfo` | `object` | — | Renders a divider row with title, meta, and `TicketStatusTag` |
+| `fullWidth` | `boolean` | `false` | Drops `max-w-ods-content-narrow` for side-panel use |
+| `bare` | `boolean` | `false` | Removes card border/background |
+| `onBack` | `() => void` | — | Renders a back chevron button anchored outside the card |
 
 ## Usage Example
 
@@ -19,40 +30,34 @@ import {
   ChatHeader,
   ChatContent,
   ChatFooter,
-} from "./chat-container"
+} from "@/components/chat/chat-container"
 
-export function MyChatShell() {
+export function MyChatView() {
   return (
     <ChatContainer>
       <ChatHeader
-        userName='Grace "Fae" Meadows'
+        userName="Fae"
         userTitle="Your Personal Assistant"
         connectionStatus="connected"
         serverUrl="mcp.flamingo.run"
-        showNewChat
-        onNewChat={() => console.log("new chat")}
-        onClose={() => console.log("close")}
+        onNewChat={() => startNewSession()}
+        onClose={() => closePanel()}
+        fullWidth
         ticketInfo={{
-          title: "Printer offline – Ticket #4821",
-          meta: "Assigned to: J. Smith",
-          status: "in-progress",
+          title: "VPN not connecting",
+          meta: "TKT-1042 · John Smith",
+          status: "in_progress",
         }}
-        fullWidth
       />
       <ChatContent>
-        {/* message list */}
+        {/* message bubbles */}
       </ChatContent>
       <ChatFooter fullWidth>
-        {/* input bar */}
+        {/* input composer */}
       </ChatFooter>
     </ChatContainer>
   )
 }
 ```
 
-## Notes
-
-- `fullWidth` on both `ChatHeader` and `ChatFooter` drops the default `max-w-ods-content-narrow` (≈600px) column — use this when embedding the chat in a side panel.
-- `ChatFooter.contentClassName` is a legacy escape hatch for custom `max-w` overrides; prefer `fullWidth` for standard full-panel layouts.
-- `ChatHeader` accepts a `bare` prop to remove card chrome (shadow, border, background) for flush-mounted contexts.
-- All components are `forwardRef`-compatible and spread unknown props to their root `<div>`.
\ No newline at end of file
+> `fullWidth` should be set consistently on both `ChatHeader` and `ChatFooter` when embedding the chat shell inside a side panel, otherwise the header and input composer will misalign at narrower widths.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-header-icon-button.md b/openframe-frontend-core/src/components/chat/.chat-header-icon-button.md
new file mode 100644
index 000000000..8f8e31315
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-header-icon-button.md
@@ -0,0 +1,34 @@
+<!-- source-hash: 782139de0458dedc9ada7521e4b46ee1 -->
+Square 56×56 icon button component used in the chat panel's top-navigation bar, serving as a styled cell for actions like archive, restore, close, and the overflow menu trigger.
+
+## Key Components
+
+- **`ChatHeaderIconButton`** — A `forwardRef` button component that renders a fixed-size (`size-14`) icon cell with a left border divider, hover background, and focus ring styles. Fully compatible as a Radix UI `asChild` trigger via prop spread.
+- **`ChatHeaderIconButtonProps`** — Extends `React.ButtonHTMLAttributes<HTMLButtonElement>` with no additional props.
+
+## Usage Example
+
+```typescript
+import { ChatHeaderIconButton } from './chat-header-icon-button'
+import { X } from 'lucide-react'
+
+// Basic close button
+<ChatHeaderIconButton onClick={handleClose} aria-label="Close chat">
+  <X className="size-5" />
+</ChatHeaderIconButton>
+
+// As a Radix DropdownMenu trigger
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+
+<DropdownMenu.Trigger asChild>
+  <ChatHeaderIconButton aria-label="More options">
+    <MoreHorizontal className="size-5" />
+  </ChatHeaderIconButton>
+</DropdownMenu.Trigger>
+```
+
+## Notes
+
+- Default `type` is `'button'` to prevent accidental form submission.
+- Icon color stays `ods-text-secondary` on hover; only the background transitions to `ods-bg-hover`.
+- Accessibility: pass `aria-label` when the button has no visible text label.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-input.md b/openframe-frontend-core/src/components/chat/.chat-input.md
index dccb8291a..c7f79da62 100644
--- a/openframe-frontend-core/src/components/chat/.chat-input.md
+++ b/openframe-frontend-core/src/components/chat/.chat-input.md
@@ -1,56 +1,52 @@
-<!-- source-hash: 6d459e335b05378d1756f274a61128f0 -->
-A controlled chat input component with slash-command autocomplete, send/stop functionality, and an imperative ref API for programmatic control.
+<!-- source-hash: 2de053665f659d097f11f201cb11d877 -->
+Chat input component for AI chat interfaces that handles message composition, submission, slash command autocomplete, and exposes an imperative ref API for programmatic control.
 
 ## Key Components
 
 ### `ChatInput` (default export)
-A `forwardRef` component that renders a textarea-based chat input with:
-- **Slash command autocomplete** — triggers on `/` prefix, debounced 150ms, keyboard-navigable dropdown
-- **Send/Stop modes** — toggles between send and stop-stream actions based on `sending`/`onStop` props
-- **Awaiting response indicator** — replaces input with `ChatTypingIndicator` while waiting for a reply
-- **Auto-refocus** — restores focus after send completes or streaming stops
+A `forwardRef` component wrapping a resizable `Textarea` with:
+- **Send/Stop controls** — toggles between a Send button and Stop button based on `sending`/`awaitingResponse` state
+- **Slash command autocomplete** — debounced (150ms) dropdown triggered by `/` prefix, with keyboard navigation (↑/↓/Tab/Enter/Escape)
+- **Smart submit** — clears draft only on successful send (`onSend` return value gating); supports `allowEmptySend` for attachment surfaces
+- **`preventScroll` focus** — all focus paths use `{ preventScroll: true }` to avoid viewport jumps
 
 ### `ChatInputRef` (imperative handle)
-Exposed methods for parent components:
+Exposed methods for parent control:
 
 | Method | Description |
-|---|---|
-| `focus()` / `blur()` | Programmatic focus control |
-| `clear()` | Resets input value |
-| `setValue(next)` | Prefills input, places caret at end |
-| `setValueAndCursor(next, offset)` | Prefills input with clamped caret position |
-| `submit(next)` | Fires `onSend` and clears, bypassing user interaction |
-| `getValue()` | Returns current value via stable ref |
+|--------|-------------|
+| `focus()` | Focus the textarea |
+| `blur()` | Blur the textarea |
+| `clear()` | Clear the draft |
+| `setValue(text)` | Pre-fill and focus with cursor at end |
+| `setValueAndCursor(text, offset)` | Pre-fill with clamped cursor position |
+| `submit(text)` | Programmatically fire a message |
+| `getValue()` | Read current draft value |
 
 ### `SLASH_INPUT_TRIGGER`
-Regex `/^\/([a-z][a-z0-9-]*)?$/` — kept in sync with server-side slash command registration to prevent suggesting commands the API would reject.
+Regex `/^\/([a-z][a-z0-9-]*)?$/` — shared constraint kept in sync with `lib/config/slash-commands-config.ts` and the chat-route slash dispatch parser.
 
 ## Usage Example
 
 ```typescript
-import { useRef } from "react"
-import { ChatInput } from "./chat-input"
-import type { ChatInputRef } from "./types"
-
-function ChatPanel() {
-  const inputRef = useRef<ChatInputRef>(null)
-
-  const prefillSlashCommand = () => {
-    inputRef.current?.setValue("/reboot ")
-  }
-
-  return (
-    <ChatInput
-      ref={inputRef}
-      sending={false}
-      awaitingResponse={false}
-      onSend={(message) => console.log("Sending:", message)}
-      onStop={() => abortStream()}
-      slashCommands={{
-        fetchCommands: async (prefix, signal) => fetchSlashCommands(prefix, signal),
-      }}
-      autoFocus
-    />
-  )
-}
+const inputRef = useRef<ChatInputRef>(null)
+
+// Programmatically inject a slash command
+inputRef.current?.setValue('/restart ')
+
+// Submit on behalf of the user
+inputRef.current?.submit('/status check')
+
+<ChatInput
+  ref={inputRef}
+  onSend={async (message) => {
+    const ok = await sendMessage(message)
+    return ok ? undefined : false // returning false keeps the draft
+  }}
+  onStop={() => abortController.abort()}
+  sending={isSending}
+  awaitingResponse={isWaiting}
+  slashCommands={{ fetchCommands: fetchSlashCommands }}
+  autoFocus
+/>
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-message-enhanced.md b/openframe-frontend-core/src/components/chat/.chat-message-enhanced.md
index 861df4e52..9410116b3 100644
--- a/openframe-frontend-core/src/components/chat/.chat-message-enhanced.md
+++ b/openframe-frontend-core/src/components/chat/.chat-message-enhanced.md
@@ -1,22 +1,23 @@
-<!-- source-hash: d70b1713cdb85568acf904d7a2daa162 -->
-Renders enhanced chat messages with support for multi-segment content, inline/block entity card markers, tool executions, approval flows, and rich markdown — delegating entity resolution and navigation to host-provided callbacks.
+<!-- source-hash: ff4775e73b4e5bffec2e96add901ee7f -->
+Renders an enhanced chat message bubble with support for multi-segment content, inline/block entity card resolution, tool execution displays, approval flows, thinking indicators, and rich markdown — all composed from host-provided render props to keep the library data-agnostic.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatMessageEnhanced` | `forwardRef` component | Main message renderer with role-aware layout (`user`, `error`, assistant variants) |
-| `normalizeContent` | Function | Normalizes `MessageContent` (string or `MessageSegment[]`) to a uniform segment array |
-| `CARD_MARKER_REGEX` | Regex | Shared pattern matching `[card://type:id]` markers — kept in lockstep with `remarkCardLinks` |
-| `renderingPlan` | `useMemo` | Per-message plan splitting text segments at block card markers for accurate streaming position |
-| `cardComponentOverrides` | `useMemo` | Overrides `<a>` tags for `card://` URLs, resolving inline/block entity cards via host callbacks |
-
-### Supporting Displays (composed internally)
-- `ToolExecutionDisplay` — renders tool call segments
-- `ApprovalRequestMessage` / `ApprovalBatchMessage` — approval flow segments
-- `ErrorMessageDisplay` — error role messages
-- `ContextCompactionDisplay` — context compaction events
-- `ThinkingDisplay` — streaming thinking segments
+**`ChatMessageEnhanced`** — Main `forwardRef` component accepting:
+- `role` — `'user' | 'error' | 'assistant'` controls layout and avatar type
+- `content` — `MessageContent` (string or `MessageSegment[]`); normalized via `normalizeContent()`
+- `chatRefs` — host-provided `Record<string, ChatRef>` for resolving `[card://type:id]` markers
+- `renderEntityCard` — host callback returning inline or `<BlockCard>`-wrapped JSX per ref
+- `NavLinkAnchor` — host navigation component injected into markdown link overrides
+- `assistantType` — `'mingo' | 'fae'` controls avatar/author styling
+
+**`normalizeContent()`** — Converts string content to a single `MessageSegment[]` for uniform rendering.
+
+**`CARD_MARKER_REGEX`** — Shared regex kept in lockstep with `remarkCardLinks` to consistently detect `[card://type:id]` patterns across pre-scan and remark transforms.
+
+**`renderingPlan` (useMemo)** — Builds per-segment split plans: text segments containing block-level card markers are split into `{ kind: 'text' }` and `{ kind: 'block' }` parts so block cards render at marker position during streaming, not appended at segment end.
+
+**`cardComponentOverrides`** — Overrides the markdown `<a>` element to intercept `card://` hrefs and render pre-computed inline nodes or graceful fallbacks (real title, raw `cardId`, or dimmed placeholder).
 
 ## Usage Example
 
@@ -25,20 +26,10 @@ Renders enhanced chat messages with support for multi-segment content, inline/bl
   role="assistant"
   assistantType="mingo"
   content={[
-    { type: 'text', text: 'Here is your ticket [card://ticket:123].' },
-    { type: 'tool_execution', toolName: 'search', result: '...' },
+    { type: 'text', text: 'Here is the ticket [card://ticket:abc-123]' },
   ]}
-  chatRefs={{
-    'ticket:123': { type: 'ticket', id: '123', title: 'Login bug', url: '/tickets/123' },
-  }}
+  chatRefs={{ 'ticket:abc-123': { type: 'ticket', id: 'abc-123', title: 'Fix login bug', url: '/tickets/abc-123' } }}
   renderEntityCard={(ref) => <TicketPill ref={ref} />}
-  NavLinkAnchor={({ href, children }) => <Link href={href}>{children}</Link>}
-  showAvatar
+  NavLinkAnchor={AppNavLink}
 />
-```
-
-## Notes
-
-- **Data-agnostic**: the library never imports entity types or routing — the host provides `renderEntityCard` and `NavLinkAnchor`.
-- Block card markers split their text segment so block payloads render at the marker position during streaming, not appended at the end.
-- Three distinct fallbacks for unresolved `card://` hrefs prevent LLM hallucinations from appearing as real cards.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-message-list.md b/openframe-frontend-core/src/components/chat/.chat-message-list.md
index 762730479..453bf6a8f 100644
--- a/openframe-frontend-core/src/components/chat/.chat-message-list.md
+++ b/openframe-frontend-core/src/components/chat/.chat-message-list.md
@@ -1,67 +1,45 @@
-<!-- source-hash: ddaad2500e41f9ee61eff7435b990d72 -->
-A scrollable chat message list component with stick-to-bottom behavior, prepend anchoring for load-older pagination, and streaming indicators.
+<!-- source-hash: c19afecf5246525c6445a4be64c572cb -->
+A scrollable chat message list component with automatic stick-to-bottom behavior, prepend anchoring for infinite scroll, and streaming indicators.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatMessageList` | `forwardRef` Component | Main scrollable message list with auto-scroll management |
-| `STREAMING_WORDS` | `const` | Flamingo-themed cycling phrases shown during AI streaming |
-| `hasNonEmptyContent` | Helper Function | Checks if a `MessageContent` value carries visible text |
-| `disposeAnchorWatcher` | Helper Function | Idempotent teardown for `AnchorWatcher` instances |
-| `AnchorWatcher` | Interface | Tracks `ResizeObserver` + timeout for top-anchor settle window |
-
-## Key Props (`ChatMessageListProps`)
-
-| Prop | Description |
-|------|-------------|
-| `messages` | Array of chat messages to render |
-| `dialogId` | Triggers instant scroll-to-bottom on dialog change |
-| `isLoading` / `isTyping` | Controls skeleton and streaming indicator visibility |
-| `autoScroll` | Enables/disables stick-to-bottom behavior |
-| `hasNextPage` / `onLoadMore` | Infinite scroll upward (load-older pagination) |
-| `renderEntityCard` | Custom renderer for entity card messages |
+- **`ChatMessageList`** — Main `forwardRef` component rendering a virtualized-style message list with `useStickToBottom` for physics-based auto-scroll
+- **`useStickToBottom`** — External hook managing scroll-to-bottom with spring animation, user-escape detection, and ResizeObserver
+- **`STREAMING_WORDS`** — Flamingo-themed cycling phrases displayed during AI response streaming
+- **`hasNonEmptyContent`** — Utility checking if a `MessageContent` (string or `MessageSegment[]`) contains visible text
+- **`AnchorWatcher` / `disposeAnchorWatcher`** — Interface and teardown helper for the 2s prepend-settle ResizeObserver window
+- **Force-stick effects** — Handles dialog changes, first-load, and new user messages with instant scroll snaps
+- **Prepend anchoring** (`useLayoutEffect`) — Preserves viewport position when older messages load above the current reading position
 
 ## Usage Example
 
 ```typescript
-import { ChatMessageList } from "@/components/chat"
+import { ChatMessageList } from "./chat-message-list"
+import type { ChatMessageListProps } from "./types"
 
 const messages = [
   { id: "1", role: "user", content: "Hello!" },
   { id: "2", role: "assistant", content: "Hi there!" },
 ]
 
-export function ChatPanel() {
+function ChatWindow() {
   const listRef = useRef<HTMLDivElement>(null)
 
   return (
     <ChatMessageList
       ref={listRef}
       messages={messages}
-      dialogId="conv-abc123"
-      isTyping={false}
+      dialogId="dialog-123"
+      isLoading={false}
+      isTyping={true}
       autoScroll={true}
       showAvatars={true}
       hasNextPage={true}
+      isFetchingNextPage={false}
       onLoadMore={() => fetchOlderMessages()}
     />
   )
 }
 ```
 
-## Scroll Management Strategy
-
-The component uses [`use-stick-to-bottom`](https://github.com/stackblitz-labs/use-stick-to-bottom) (same library powering bolt.new) with three additional behaviors layered on top:
-
-```mermaid
-graph TD
-    A["Message Update"] --> B{"Trigger Type?"}
-    B -->|"Dialog changed"| C["scrollToBottom instant"]
-    B -->|"First message"| C
-    B -->|"New user message"| C
-    B -->|"Streaming assistant"| D["Library spring physics"]
-    A --> E{"Content prepended?"}
-    E -->|"Load-older"| F["Preserve viewport via scrollTop delta"]
-    E -->|"No prepend"| G["Update scrollHeight snapshot"]
-```
\ No newline at end of file
+> **Scroll strategy:** The library handles streaming growth via spring physics. Explicit `scrollToBottom({ animation: 'instant' })` calls are reserved for intent transitions — dialog switches, first message, and new user sends (including post-image-load follow-ups).
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-message-row.md b/openframe-frontend-core/src/components/chat/.chat-message-row.md
new file mode 100644
index 000000000..717913585
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-message-row.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 733d7241f3fd52b80be75f4fe1eb1256 -->
+Reusable Slack-style message row component that renders a single chat message with avatar, display name, timestamp, body text, and an optional footer slot. Shared across the OpenMSP community feed and ticket conversation surfaces to guarantee pixel-identical layout.
+
+## Key Components
+
+### `ChatMessageRow`
+The primary export. Renders a full message row with:
+- **Avatar** — proxied image via `useProxiedImageUrl`, falls back to initials in an identically-sized `rounded-lg` box
+- **Header** — bold display name + optional relative-time label
+- **Body** — `whitespace-pre-wrap` text block (hidden when empty)
+- **Footer slot** — per-surface customization (Slack reply badge or `<TicketAttachmentsList>`)
+
+### `ChatMessageRowSkeleton`
+Structural 1:1 skeleton that mirrors the real component's DOM layout (same wrapper, avatar box, and bar heights) to prevent reflow on the loading→loaded transition.
+
+### `ChatMessageRowProps`
+```typescript
+interface ChatMessageRowProps {
+  displayName: string       // Bold name in header
+  avatarUrl?: string | null // Proxied; falls back to initials
+  timeLabel?: string | null // Pre-formatted, e.g. "2h ago"
+  body: string              // Message text (pre-wrap)
+  footer?: ReactNode        // Per-surface slot (replies / attachments)
+}
+```
+
+## Usage Example
+
+```typescript
+import { ChatMessageRow, ChatMessageRowSkeleton } from './chat-message-row'
+import { formatRelativeTime } from '../../utils/format'
+
+// Loaded state
+<ChatMessageRow
+  displayName="Jane Smith"
+  avatarUrl="https://cdn.example.com/avatars/jane.png"
+  timeLabel={formatRelativeTime(message.createdAt)}
+  body={message.text}
+  footer={<TicketAttachmentsList attachments={message.attachments} />}
+/>
+
+// Loading state — no layout shift when data arrives
+<ChatMessageRowSkeleton />
+```
+
+> **Note:** All colors use ODS theme tokens (`text-ods-text-primary`, `text-ods-text-secondary`). Do not override with raw color utilities — both surfaces rely on this for consistent theming.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-message-skeleton.md b/openframe-frontend-core/src/components/chat/.chat-message-skeleton.md
index 5c46bdcc9..482ba67c2 100644
--- a/openframe-frontend-core/src/components/chat/.chat-message-skeleton.md
+++ b/openframe-frontend-core/src/components/chat/.chat-message-skeleton.md
@@ -1,40 +1,60 @@
-<!-- source-hash: dc7cb2f1d39ceeb5b0684dbef38a8d20 -->
-Animated loading skeleton components that simulate the layout of chat messages while content is being fetched, matching the `ChatMessageEnhanced` hanging-avatar layout.
+<!-- source-hash: 9441ef9ba725bb4df64a6b4449a92a2d -->
+Loading state skeleton components for chat message UI, mirroring the layout of `ChatMessageEnhanced` and `ChatMessageList` during data fetching.
 
 ## Key Components
 
 ### `ChatMessageSkeleton`
-Renders a single animated placeholder message with pulsing blocks for the avatar, sender name, timestamp, and multi-line message content.
+Single animated message row placeholder with:
+- Inline avatar pulse (assistant messages only, controlled via `showAvatar` + `isUser`)
+- Name + timestamp placeholder bars in the header row
+- Three body lines using percentage widths (`full`, `11/12`, `3/5`) for responsive reflow
+
+**Props:**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `className` | `string` | — | Additional CSS classes |
-| `showAvatar` | `boolean` | `true` | Whether to render the avatar skeleton |
-| `isUser` | `boolean` | `false` | Applies user-message styling (no card background, no avatar) |
-| `assistantType` | `'mingo' \| 'fae'` | `'fae'` | Controls avatar gradient — cyan for Mingo, pink for Fae |
+| `className` | `string` | — | Extra classes on the row wrapper |
+| `showAvatar` | `boolean` | `true` | Renders the circular avatar placeholder |
+| `isUser` | `boolean` | `false` | Suppresses avatar for user-side messages |
+
+---
 
 ### `ChatMessageListSkeleton`
-Renders a scrollable list of `ChatMessageSkeleton` items, mimicking a full chat viewport during initial load.
+Full scrollable list of `ChatMessageSkeleton` rows, matching `ChatMessageList` layout semantics.
+
+**Props:**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `messageCount` | `number` | `6` | Number of skeleton messages to render |
-| `showAvatars` | `boolean` | `true` | Passed through to each `ChatMessageSkeleton` |
-| `assistantType` | `'mingo' \| 'fae'` | `'fae'` | Applied to all assistant messages |
-| `contentClassName` | `string` | — | Overrides default horizontal padding on the content wrapper |
+| `className` | `string` | — | Extra classes on the scroll container |
+| `messageCount` | `number` | `6` | Number of skeleton rows to render |
+| `showAvatars` | `boolean` | `true` | Passed down to each row |
+| `fullWidth` | `boolean` | `false` | Drops `max-w-ods-content-narrow` to fill panel width |
+| `contentClassName` | `string` | — | Extra classes on the inner content column |
+
+Every 3rd message (`index % 3 === 0`) is treated as a user message, suppressing its avatar to simulate a realistic conversation pattern.
 
 ## Usage Example
 
 ```typescript
-// Single message skeleton (e.g. while streaming)
-<ChatMessageSkeleton assistantType="mingo" showAvatar />
-
-// Full chat list skeleton on initial page load
-<ChatMessageListSkeleton
-  messageCount={8}
-  assistantType="fae"
-  showAvatars={true}
-/>
-```
-
-> Every third message (`index % 3 === 0`) is rendered as a user bubble; the rest render as assistant messages with the appropriate Mingo/Fae avatar gradient.
\ No newline at end of file
+// Drop-in replacement while chat history loads
+import { ChatMessageListSkeleton } from "@/components/chat/chat-message-skeleton"
+
+function ChatPanel() {
+  if (isLoading) {
+    return (
+      <ChatMessageListSkeleton
+        messageCount={8}
+        fullWidth
+        showAvatars
+      />
+    )
+  }
+  return <ChatMessageList messages={messages} />
+}
+
+// Single row — useful inside virtualized lists or custom loading states
+import { ChatMessageSkeleton } from "@/components/chat/chat-message-skeleton"
+
+<ChatMessageSkeleton isUser={false} showAvatar />
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-panel-header-mobile.md b/openframe-frontend-core/src/components/chat/.chat-panel-header-mobile.md
new file mode 100644
index 000000000..1de92871f
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-panel-header-mobile.md
@@ -0,0 +1,39 @@
+<!-- source-hash: f1e4bc9ad27e1cac7b1ed52a57d43072 -->
+Mobile-optimized header component for the chat panel drawer, implementing the Figma node `7363:85532` layout with a back chevron, truncated `h2` title, and a collapsible `⋯` actions menu.
+
+## Key Components
+
+- **`ChatPanelHeaderMobileProps`** — Extends `ChatPanelHeaderProps` with an optional `className`; `onClose` is accepted for API parity but unused (drawer dismissal is handled externally)
+- **`menuItems`** — Dynamically built array of `ActionsMenuItem` entries based on view state (`isArchivedView`, `showBack`) and available callbacks; the `⋯` trigger is hidden entirely when the array is empty
+- **`ChatPanelHeaderMobile`** — Exported function component rendering the mobile header with bottom-border card surface, optional back chevron, and trailing actions menu
+
+## Usage Example
+
+```typescript
+<ChatPanelHeaderMobile
+  title="Support Chat — Acme Corp"
+  showBack={true}
+  backAriaLabel="Back to chat list"
+  isArchivedView={false}
+  onBack={handleBack}
+  onRename={handleRename}
+  onArchive={handleArchive}
+  onOpenArchive={handleOpenArchive}
+/>
+
+// Archived view — shows Unarchive instead of Rename/Archive
+<ChatPanelHeaderMobile
+  title="Archived: Printer Issue"
+  isArchivedView={true}
+  onRestore={handleRestore}
+/>
+```
+
+## Layout Notes
+
+| Element | Behavior |
+|---|---|
+| Surface | `ods-card` + bottom border, `l` horizontal/bottom padding, `xl` top padding on title block |
+| Title | `text-h2`, truncated with `title` tooltip |
+| Back button | 44px outlined icon; shown only when `showBack={true}` |
+| `⋯` menu | Hidden when no actions apply (e.g. archive list view) |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-panel-header.md b/openframe-frontend-core/src/components/chat/.chat-panel-header.md
new file mode 100644
index 000000000..c0079aca2
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-panel-header.md
@@ -0,0 +1,40 @@
+<!-- source-hash: b0e569b09a896e15fa8139a646bcb0cd -->
+Responsive chat panel top-navigation bar that renders different layouts for mobile and desktop, surfacing context-aware actions (back navigation, rename, archive, restore, close) based on the current view state.
+
+## Key Components
+
+**`ChatPanelHeader`** — Primary export. Renders a `ChatPanelHeaderMobile` for viewports below `md`, and a fixed-height (`h-14`) desktop bar at `md+`. Right-hand actions are conditionally mounted based on props:
+
+| Condition | Action rendered |
+|---|---|
+| `isArchivedView && onRestore` | Restore (refresh) button |
+| `showBack && !isArchivedView && menuItems.length > 0` | `⋯` dropdown (rename / archive) |
+| `!showBack && onOpenArchive` | Clock / archive-entry button |
+| Always | Close (`✕`) button |
+
+**`COMPACT_HEADER_BUTTON`** — Exported Tailwind class string for the borderless 32px back-chevron button used in the desktop layout.
+
+**`ChatPanelHeaderProps`** — Full prop interface covering all view states (list, active conversation, archived conversation, guide).
+
+## Usage Example
+
+```typescript
+<ChatPanelHeader
+  showBack={true}
+  title="Support ticket #1042"
+  backAriaLabel="Back to chats"
+  isArchivedView={false}
+  onBack={() => setView('list')}
+  onClose={() => setPanelOpen(false)}
+  onRename={() => openRenameDialog(chatId)}
+  onArchive={() => archiveChat(chatId)}
+/>
+
+// List view (no back chevron, shows archive entry button)
+<ChatPanelHeader
+  title="Mingo AI"
+  onBack={() => {}}
+  onClose={() => setPanelOpen(false)}
+  onOpenArchive={() => setView('archive')}
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.chat-quick-action-row.md b/openframe-frontend-core/src/components/chat/.chat-quick-action-row.md
new file mode 100644
index 000000000..f0bfef4f4
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.chat-quick-action-row.md
@@ -0,0 +1,37 @@
+<!-- source-hash: 8d5fd241ed0ccdfa4bed2f6017d3d644 -->
+A responsive single-line chip row for chat quick-actions that automatically collapses overflow chips into a "⋯" dropdown menu based on available container width.
+
+## Key Components
+
+**`ChatQuickActionRow`** — Main export. Renders a row with an optional pinned `leading` slot and a set of collapsible `chips`. Uses `useAutoLimitTags` to measure available width off-screen, rendering as many chips inline as fit and moving the rest into an `ActionsMenuDropdown`.
+
+**`ChipButton`** — Internal button wrapper around the `Tag` UI component, supporting `'primary'` (amber accent) and `'outline'` (bordered) variants with keyboard focus ring.
+
+**Interfaces:**
+- `QuickActionChip` — Shape of each chip: `id`, `label`, optional `icon`, `variant`, and `onSelect` callback.
+- `ChatQuickActionRowProps` — Row props: optional `leading` slot, `chips` array, and `className`.
+
+## Usage Example
+
+```typescript
+import { ChatQuickActionRow, QuickActionChip } from './chat-quick-action-row'
+import { SparklesIcon } from '../icons'
+
+const chips: QuickActionChip[] = [
+  { id: 'new-ticket', label: 'New Ticket', onSelect: () => createTicket() },
+  { id: 'run-script', label: 'Run Script', onSelect: () => runScript() },
+  { id: 'view-assets', label: 'View Assets', onSelect: () => viewAssets() },
+]
+
+<ChatQuickActionRow
+  leading={
+    <button onClick={startGuide}>
+      <Tag variant="primary" label="Start Guide Chat" icon={<SparklesIcon />} />
+    </button>
+  }
+  chips={chips}
+  className="px-3 py-2"
+/>
+```
+
+The `leading` slot (e.g. Mingo's primary CTA) is always visible. Chips that don't fit the container width collapse into the `⋯` overflow menu automatically.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.embeddable-chat.md b/openframe-frontend-core/src/components/chat/.embeddable-chat.md
index dfeb95642..1ad0679af 100644
--- a/openframe-frontend-core/src/components/chat/.embeddable-chat.md
+++ b/openframe-frontend-core/src/components/chat/.embeddable-chat.md
@@ -1,48 +1,64 @@
-<!-- source-hash: c87e4b417e41397ff1753b0ea0848f78 -->
-Portable, lib-safe port of the hub's `<GlobalAskAI>` chat panel component, decoupled from all hub-only imports by routing navigation, identity, and transport decisions through a `useRequiredChatRuntime()` context hook.
+<!-- source-hash: ff995eabd5386739e20848736aa70295 -->
+Brief description of the component's purpose and public API for the `EmbeddableChat` component — a library-portable, host-agnostic port of the hub's `<GlobalAskAI>` chat panel that delegates all navigation, identity, and source decisions through a runtime context.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `EmbeddableChat` | Component | Main embeddable chat panel with controlled/uncontrolled open state |
-| `EmbeddableChatProps` | Interface | Full prop surface for the component |
-| `dispatchSlashCommandAction` | Function | Maps slash-command action IDs (`browse`, `search`, `find`, `display`) to `ChatInputRef` mutations |
-| `resolveChipIcon` | Function | Resolves a `ChatSource` to a Lucide icon via the icon registry |
-| `SKELETON_ROW_VARIANTS` | Constant | Deterministic width palette for loading skeleton rows |
-| `FALLBACK_TOP_RETRIEVED` | Constant | Number of fallback source chips shown when the model cites no sources (default: `3`) |
+### `EmbeddableChat` (default export)
+The main chat panel component supporting two modes:
+- **Guide mode** — SSE-based RAG retrieval chat
+- **Mingo mode** — NATS-based AI agent chat
+
+### `EmbeddableChatProps`
+Full prop bundle controlling the chat panel behavior:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `open` / `onOpenChange` | `boolean` / `fn` | Controlled open state |
+| `shell` | `'drawer' \| 'none'` | Layout wrapper strategy |
+| `modes` | `UseUnifiedChatModes` | Per-mode transport config |
+| `mingoState` | `UnifiedChatState` | Host-injected Mingo state |
+| `extras` | `ChatCardDispatchExtras` | Host-supplied card builders |
+| `activeMode` / `onActiveModeChange` | `ChatMode` / `fn` | Controlled mode toggle |
+| `mingoWelcome` | `Partial<MingoWelcomeProps>` | Mingo empty-state overrides |
+| `guideWelcome` | `Partial<GuideWelcomeProps>` | Guide empty-state overrides |
+
+### Key Hooks Used
+- `useRequiredChatRuntime()` — reads user identity, source, and navigation from the host-provided runtime
+- `useUnifiedChat()` — orchestrates Guide + Mingo mode state
+- `useChatAttachments()` — manages file/entity attachment strips
+- `useSlashCommandRegistry()` — slash command lookup and dispatch
 
 ## Usage Example
 
 ```typescript
 // Host wires the runtime once at root
-<HubRuntimeProvider source="hub" user={currentUser}>
-  <EmbeddableChat
-    emptyStateGreeting="How can I help you today?"
-    suggestedQueries={['How do I reset a password?', 'Show open tickets']}
-    enabledRagTableIds={enabledTableIds}
-    modes={{
-      guide: { tableIdForDocumentType },
-      mingo: { agentId: 'mingo-agent' },
-    }}
-    defaultActiveMode="guide"
-    extras={{ buildProgramProps, buildProductReleaseProps }}
-  />
-</HubRuntimeProvider>
-
-// Controlled open state
-<EmbeddableChat
-  open={isOpen}
-  onOpenChange={setIsOpen}
-  showInternalTrigger={false}
-/>
+import { HubRuntimeProvider } from './hub-runtime-provider'
+import { EmbeddableChat } from '@flamingo/chat-lib'
+
+function App() {
+  return (
+    <HubRuntimeProvider>
+      <EmbeddableChat
+        shell="drawer"
+        modes={{
+          guide: { tableIdForDocumentType: (type) => tableMap[type] },
+          mingo: { agentId: 'mingo-v2' },
+        }}
+        mingoWelcome={{
+          title: 'Hi, I am Mingo',
+          subtitle: 'Your AI IT assistant',
+        }}
+        extras={{
+          buildProgramCardProps: (id) => programCardPropsMap[id],
+        }}
+      />
+    </HubRuntimeProvider>
+  )
+}
 ```
 
-## Runtime Substitutions
+## Architecture Notes
 
-| Hub Original | Lib Replacement |
-|---|---|
-| `useAuth()` | `useRequiredChatRuntime().user` |
-| `currentPlatform()` | `useRequiredChatRuntime().source` |
-| `useNavLink` / `NavLinkAnchor` | `handleChatNavClick` + `NavLinkAnchorViaRuntime` |
-| `useDocChat(source)` | `useSseChatAdapter()` (source from runtime) |
\ No newline at end of file
+- **No hub imports** — all hub-specific concerns (`useAuth`, `currentPlatform`, `NavLink`, etc.) are replaced by `useRequiredChatRuntime()`
+- **Shell modes** — `'drawer'` wraps in a Radix `<Drawer>` with iOS scroll-lock; `'none'` renders the bare chat body for embedding inside host containers
+- **Injected state** — when `mingoState` is provided, no internal NATS subscription is opened; the host owns the data lifecycle across panel unmounts
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.guide-mode-banner.md b/openframe-frontend-core/src/components/chat/.guide-mode-banner.md
new file mode 100644
index 000000000..74cac34fc
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.guide-mode-banner.md
@@ -0,0 +1,36 @@
+<!-- source-hash: 2df823f019c629ff7f91356377ab1d22 -->
+A full-bleed accent banner component that indicates when the chat interface is operating in Guide Mode, displaying a compass icon, label, and optional help tooltip.
+
+## Key Components
+
+- **`GuideModeBanner`** — Main exported component rendering the yellow accent strip
+- **`GuideModeBannerProps`** — Interface with three optional props: `label`, `tooltip`, and `className`
+- **Default label** — `'Guide Mode Chat'` (rendered uppercase via `text-h5` style)
+- **Default tooltip** — Explains Guide Mode's read-only, exploration-only constraints (no device actions or script execution)
+
+## Usage Example
+
+```typescript
+// Default usage — uses built-in label and tooltip
+<GuideModeBanner />
+
+// Custom label and tooltip
+<GuideModeBanner
+  label="Explore Mode"
+  tooltip="This session is for exploration only."
+/>
+
+// Hide the help icon entirely
+<GuideModeBanner tooltip={null} />
+
+// With additional className
+<GuideModeBanner className="border-b border-ods-border" />
+```
+
+## Behavior Notes
+
+- **Tooltip** is suppressed when `tooltip` prop is explicitly set to `null`
+- **`TooltipProvider`** uses `delayDuration={0}` for immediate display
+- Tooltip is anchored `bottom/end` with a max-width of `280px`
+- The help button includes `aria-label="About Guide Mode"` and a visible `focus-visible` ring for accessibility
+- Layout is a fixed `h-8` flex row with `shrink-0` on icons to prevent compression of the label
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.guide-welcome.md b/openframe-frontend-core/src/components/chat/.guide-welcome.md
new file mode 100644
index 000000000..086e46c0d
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.guide-welcome.md
@@ -0,0 +1,40 @@
+<!-- source-hash: be4f83bf100684f48bec5e8bc5719294 -->
+Guide-mode chat empty state component that renders a centered greeting, a scrollable content region with edge-fade affordances, and a pinned quick-action chip row above the composer.
+
+## Key Components
+
+**`GuideWelcome`** — Main component (Figma node `7532:328214`) mirroring `MingoWelcome` for guide-mode sessions. Features:
+- Vertically centered `MingoIcon` greeting with configurable title/subtitle
+- Shared scroll region for greeting + slash-command onboarding list (`children`), with top/bottom gradient fades that activate dynamically via `ResizeObserver`
+- Pinned quick-action chip row: first `maxVisibleQuickActions` (default `3`) render as `Tag` chips; overflow actions collapse into an `ActionsMenuDropdown` triggered by an `⋯` chip
+
+**`GuideQuickAction`** — Interface describing a chip: `id`, `label`, and optional `prompt` (seeded into the composer on click).
+
+**`GuideWelcomeProps`** — Full props interface with overridable `title`, `subtitle`, `quickActions`, `maxVisibleQuickActions`, `onQuickAction`, `children`, and `className`.
+
+## Usage Example
+
+```typescript
+import { GuideWelcome, GuideQuickAction } from './guide-welcome'
+
+const actions: GuideQuickAction[] = [
+  { id: 'tickets', label: 'View open tickets', prompt: 'Show my open tickets' },
+  { id: 'docs',    label: 'Search docs',        prompt: 'Search OpenFrame docs for...' },
+  { id: 'issues',  label: 'Known issues' },
+  { id: 'start',   label: 'How to start' }, // overflows into ⋯ menu
+]
+
+function GuideChatPage() {
+  return (
+    <GuideWelcome
+      title="Ask Mingo"
+      subtitle="Temporary session — nothing is saved."
+      quickActions={actions}
+      maxVisibleQuickActions={3}
+      onQuickAction={(action) => composer.seed(action.prompt ?? action.label)}
+    >
+      <SlashCommandList />
+    </GuideWelcome>
+  )
+}
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.index.md b/openframe-frontend-core/src/components/chat/.index.md
index f998ca827..c48f8048a 100644
--- a/openframe-frontend-core/src/components/chat/.index.md
+++ b/openframe-frontend-core/src/components/chat/.index.md
@@ -1,42 +1,54 @@
-<!-- source-hash: 4f91f1efeb0b18cbf93d3b4ed385c331 -->
-Central barrel export for the `chat` UI package — re-exports every public component, hook, utility, type, and constant from the chat feature module, making the entire surface area available via a single import path.
+<!-- source-hash: 5c1bfd72517f2b60b8fd64c33b8c9950 -->
+Central barrel export file for the `chat` UI library, re-exporting all public components, hooks, types, and utilities from the chat module as a single entry point.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `EmbeddableChat` | Top-level chat orchestrator; mount once at the app root inside a `ChatRuntimeContext.Provider` |
-| `ChatRef` | Type for imperative chat handle refs |
-| `remarkCardLinks` | Remark plugin for rendering card-style links in chat messages |
-| `NavLinkAnchorViaRuntime` | Runtime-aware navigation anchor component |
-| `SourceActionButton` | Action button with configurable density for source references |
-| `ChatAttachmentAddButton` / `ChatAttachmentChipStrip` | Attachment UI with MIME type constants and upload concurrency limits |
-| `entity-cards` | Suite of 12+ refactored entity card components |
-| `hooks` | All chat-related React hooks |
-| `utils` | Chat utility functions |
-| `types` | Shared chat types and constants |
+**Chat UI Components**
+- `ChatContainer`, `ChatInput`, `ChatComposer` — Core chat layout and input primitives
+- `ChatMessageEnhanced`, `ChatMessageList`, `ChatMessageRow` — Message rendering pipeline
+- `ChatPanelHeader`, `ChatHeaderIconButton`, `ChatSidebar` — Chat chrome and navigation
+- `ChatTypingIndicator`, `ToolExecutionDisplay`, `ToolCallBlocks` — Real-time feedback components
+
+**Approval & Display**
+- `ApprovalRequestMessage`, `ApprovalBatchMessage` — AI action approval flows
+- `ThinkingDisplay`, `ContextCompactionDisplay`, `ErrorMessageDisplay` — Status/state displays
+
+**Mingo AI Specific**
+- `MingoOnboardingCard`, `MingoWelcome`, `MingoChatHistory`, `MingoChatModals` — Mingo AI onboarding and session management
+- `GuideModeBanner`, `GuideWelcome` — Guide mode UI
+
+**Attachments & Suggestions**
+- `ChatAttachmentAddButton`, `ChatAttachmentChipStrip` — File attachment handling with `CHAT_ATTACHMENT_MIME_TYPES` and `CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER` constants
+- `SlashCommandSuggestions` — Slash command autocomplete
+
+**Orchestration**
+- `EmbeddableChat` — Full chat orchestrator; mount once at the root inside a `<ChatRuntimeContext.Provider>`
+
+**Supporting Exports**
+- `ChatRef` — Ref type for programmatic chat control
+- `remarkCardLinks` — Remark plugin for card-style link rendering
+- `NavLinkAnchorViaRuntime`, `SourceActionButton` — Shared UI primitives migrated from hub
 
 ## Usage Example
 
 ```typescript
-// Import anything from the chat package via this single entry point
 import {
   EmbeddableChat,
+  ChatInput,
+  ChatMessageList,
   ChatAttachmentAddButton,
   CHAT_ATTACHMENT_MIME_TYPES,
   type ChatRef,
-  type EmbeddableChatProps,
 } from '@flamingo/chat'
 
-function AppRoot() {
+// Mount the full chat orchestrator
+export function AppRoot() {
   const chatRef = useRef<ChatRef>(null)
 
   return (
     <ChatRuntimeContext.Provider value={runtime}>
-      <EmbeddableChat ref={chatRef} />
+      <EmbeddableChat ref={chatRef} agentId="mingo" />
     </ChatRuntimeContext.Provider>
   )
 }
-```
-
-> **Note:** This file is marked `'use client'` — all exports are React Client Components or client-safe utilities, intended for browser rendering in Next.js App Router environments.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.mingo-chat-history.md b/openframe-frontend-core/src/components/chat/.mingo-chat-history.md
new file mode 100644
index 000000000..01769e172
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.mingo-chat-history.md
@@ -0,0 +1,38 @@
+<!-- source-hash: 204951df6ea83ada00c547b070c07550 -->
+Scrollable chat history panel for the Mingo AI interface that renders past dialogs grouped by recency (Today / Yesterday / Older) with unread badges, rename/archive actions, infinite scroll, and a skeleton loading state.
+
+## Key Components
+
+- **`MingoChatHistory`** — Main export. Renders grouped dialog rows with scroll-fade affordances and an IntersectionObserver-based infinite-scroll sentinel.
+- **`MingoChatHistorySkeleton`** — Pulse-animated loading placeholder that mirrors the grouped row layout to prevent layout flicker on first load.
+- **`MingoChatHistoryRow`** *(internal)* — Individual dialog row with unread badge, truncated title, and a `⋯` actions dropdown (Rename / Archive).
+- **`groupDialogs`** *(internal)* — Partitions dialogs into Today / Yesterday / Older buckets based on wall-clock time.
+- **`MingoChatHistoryProps`** — Full prop interface including cursor-pagination controls (`hasMore`, `isLoadingMore`, `onLoadMore`).
+
+## Usage Example
+
+```typescript
+import {
+  MingoChatHistory,
+  MingoChatHistorySkeleton,
+} from './mingo-chat-history'
+
+// Show skeleton while first page loads
+if (isLoading) return <MingoChatHistorySkeleton />
+
+// Render history once data arrives
+return (
+  <MingoChatHistory
+    dialogs={dialogs}
+    activeDialogId={currentDialogId}
+    onSelectDialog={(id) => router.push(`/mingo/${id}`)}
+    onRequestRename={(dialog) => openRenameModal(dialog)}
+    onRequestArchive={(dialog) => openArchiveModal(dialog)}
+    hasMore={pagination.hasNextPage}
+    isLoadingMore={isFetchingMore}
+    onLoadMore={fetchNextPage}
+  />
+)
+```
+
+> **Note:** Dialogs should be pre-sorted newest-first by the host. The component only handles grouping, not sorting. The `onRequestRename` / `onRequestArchive` callbacks are **request signals** — the host is responsible for opening the appropriate confirmation/rename modal.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.mingo-chat-modals.md b/openframe-frontend-core/src/components/chat/.mingo-chat-modals.md
new file mode 100644
index 000000000..d5fc22c98
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.mingo-chat-modals.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 84980ba72f1825d869b36d8a7a15c4e7 -->
+Modal components for chat management actions (rename, archive, unarchive) used within the Mingo AI chat interface.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `RenameChatModal` | Component | Input modal to rename an existing chat; reseeds on each open |
+| `ArchiveChatModal` | Component | Destructive confirmation modal to hide a chat from current view |
+| `UnarchiveChatModal` | Component | Confirmation modal to restore an archived chat |
+| `ChatDialogModals` | Component | Composite wrapper rendering all three modals from a single prop shape |
+| `RenameChatModalProps` | Interface | Props for `RenameChatModal` |
+| `ArchiveChatModalProps` | Interface | Props for `ArchiveChatModal` |
+| `UnarchiveChatModalProps` | Interface | Props for `UnarchiveChatModal` |
+| `ChatDialogModalsProps` | Interface | Props for `ChatDialogModals` |
+
+## Usage Example
+
+```typescript
+// Pair ChatDialogModals with useChatDialogManager for full dialog state management
+const {
+  renameTarget, setRenameTarget, onConfirmRename,
+  archiveTarget, setArchiveTarget, onConfirmArchive,
+  restoreTarget, setRestoreTarget, onConfirmRestore,
+} = useChatDialogManager()
+
+return (
+  <ChatDialogModals
+    renameTarget={renameTarget}
+    setRenameTarget={setRenameTarget}
+    onConfirmRename={onConfirmRename}
+    archiveTarget={archiveTarget}
+    setArchiveTarget={setArchiveTarget}
+    onConfirmArchive={onConfirmArchive}
+    restoreTarget={restoreTarget}
+    setRestoreTarget={setRestoreTarget}
+    onConfirmRestore={onConfirmRestore}
+  />
+)
+```
+
+## Notes
+
+- All modals share consistent ODS-token button styling (`footerBtn`, `cancelBtn`, `saveBtn`, `dangerBtn`) matching the Figma `button-full` spec
+- `RenameChatModal` auto-focuses the input and supports `Enter` to save; the Save button is disabled when the trimmed value is empty
+- `ArchiveChatModal` uses the `dangerBtn` (error/red) style to signal a destructive action
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.mingo-info-card.md b/openframe-frontend-core/src/components/chat/.mingo-info-card.md
new file mode 100644
index 000000000..3feacabca
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.mingo-info-card.md
@@ -0,0 +1,51 @@
+<!-- source-hash: da97535f738c30618509444138373d55 -->
+A reusable info card component for the Mingo AI interface that displays an entity (user, device, service, etc.) with a leading avatar/icon, title, description, optional status pill, and overflow actions menu.
+
+## Key Components
+
+**`MingoInfoCard`** — Primary export. Renders a horizontally-laid-out card with:
+- Leading 40px media (image with initials fallback, or boxed icon)
+- Title + optional description text column
+- Optional coloured status `Tag` pill
+- Optional `ActionsMenuDropdown` triggered by a `⋯` button
+
+**`CardMedia`** *(internal)* — Handles the leading avatar slot. Shows an image with an initials fallback on load error, or a boxed glyph icon.
+
+**`MingoInfoCardStatus`** — Interface for the status pill (`label` + `variant`).
+
+**`MingoInfoCardAnchorProps`** — Interface for turning the content region into an `<a>` tag (`href`, `target`, `rel`, `onClick`).
+
+> **Note:** All elements use `<span>`/`<a>`/`<button>` (no `<div>`) so the card renders safely inside chat `<p>` elements via the `[card://]` inline replacement pattern.
+
+## Usage Example
+
+```typescript
+import { MingoInfoCard } from './mingo-info-card'
+import { ServerIcon } from '../icons-v2-generated'
+
+// Basic card with icon and status
+<MingoInfoCard
+  title="web-server-01"
+  description="192.168.1.10 — Ubuntu 22.04"
+  icon={<ServerIcon size={24} />}
+  status={{ label: 'Online', variant: 'success' }}
+  menuGroups={[
+    {
+      items: [
+        { label: 'View details', onClick: () => navigate('/device/1') },
+        { label: 'Restart', onClick: handleRestart },
+      ],
+    },
+  ]}
+/>
+
+// Navigable card with avatar image
+<MingoInfoCard
+  title="Jane Smith"
+  description="jane@company.com"
+  imageSrc="/avatars/jane.jpg"
+  imageAlt="Jane Smith"
+  status={{ label: 'Away', variant: 'warning' }}
+  anchorProps={{ href: '/users/jane', target: '_blank' }}
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.mingo-onboarding-card.md b/openframe-frontend-core/src/components/chat/.mingo-onboarding-card.md
index 51aa16c30..f617c2651 100644
--- a/openframe-frontend-core/src/components/chat/.mingo-onboarding-card.md
+++ b/openframe-frontend-core/src/components/chat/.mingo-onboarding-card.md
@@ -1,62 +1,47 @@
-<!-- source-hash: 86ac59c4c1438a33b694f4b3fbba9291 -->
-A chat empty-state onboarding card component that renders a single slash-command or feature row, supporting optional action buttons, icons, and interactive/non-interactive modes.
+<!-- source-hash: 5c7bea0689601e74e88dd84bfa270626 -->
+A single onboarding/slash-command row card used in Mingo's chat empty-state list. Renders as an interactive `<button>` when a click handler is provided (and no actions exist), or as a static `<div>` with inline action buttons otherwise.
 
 ## Key Components
 
-### Interfaces
+**`MingoOnboardingCard`** — Main component (Figma node `7363:205939`)
+Displays an icon, title, optional slash-command label, description, and an optional row of action buttons. Stacks cleanly in a column container using `border-b` dividers, with `last:border-b-0` to trim the final card.
 
-- **`MingoOnboardingCardAction`** — Defines a single action button with `id`, `label`, and `onClick` handler
-- **`MingoOnboardingCardProps`** — Full card configuration including `icon`, `title`, `slashCommand`, `description`, `actions`, `onClick`, and `className`
+**`MingoOnboardingCardProps`** — Component props interface
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `ReactNode` | 16×16 leading icon, inherits `ods-text-secondary` color |
+| `title` | `ReactNode` | Card title (DM Sans Medium 14px, `ods-text-primary`) |
+| `slashCommand` | `ReactNode` | Right-aligned label (e.g. `/roadmap`) |
+| `description` | `ReactNode` | Optional subtitle below the title row |
+| `actions` | `ReadonlyArray<MingoOnboardingCardAction>` | Outline chip buttons; disables card-level `onClick` |
+| `onClick` | `() => void` | Makes card interactive when no `actions` present |
+| `className` | `string` | Appended to root element |
 
-### Component
-
-- **`MingoOnboardingCard`** — Root component that conditionally renders as a `<button>` (when `onClick` is set and no `actions`) or a `<div>` (when `actions` are present or no `onClick`)
-
-### Behavior Logic
-
-| Condition | Rendered Element |
-|-----------|-----------------|
-| `onClick` set, no `actions` | `<button>` with hover/focus styles |
-| `actions` present | `<div>` with per-action `<button>` chips |
-| Neither | Static `<div>` |
+**`MingoOnboardingCardAction`** — Action button descriptor
+Each action exposes `id`, `label`, and `onClick` (receives `MouseEvent`); click events are auto-stopped from propagating to the card.
 
 ## Usage Example
 
 ```typescript
-import {
-  MingoOnboardingCard,
-  MingoOnboardingCardAction,
-} from './mingo-onboarding-card'
+import { MingoOnboardingCard } from './mingo-onboarding-card'
+import { SearchIcon } from '../icons'
 
-// Static card with slash command
+// Interactive card (no actions)
 <MingoOnboardingCard
   icon={<SearchIcon />}
-  title="Search Knowledge Base"
+  title="Search knowledge base"
   slashCommand="/search"
-  description="Find articles, runbooks, and past tickets"
+  description="Find articles, tickets, and docs"
+  onClick={() => console.log('card clicked')}
 />
 
-// Interactive card (renders as <button>)
+// Static card with inline action buttons
 <MingoOnboardingCard
-  icon={<RoadmapIcon />}
-  title="View Roadmap"
+  title="Recent tickets"
   slashCommand="/roadmap"
-  onClick={() => router.push('/roadmap')}
-/>
-
-// Card with action chips (renders as <div>)
-const actions: MingoOnboardingCardAction[] = [
-  { id: 'recent', label: 'Recent', onClick: () => fetchRecent() },
-  { id: 'search', label: 'Search', onClick: (e) => { e.stopPropagation(); openSearch() } },
-]
-
-<MingoOnboardingCard
-  icon={<TicketIcon />}
-  title="Tickets"
-  slashCommand="/tickets"
-  description="Browse and manage open tickets"
-  actions={actions}
+  actions={[
+    { id: 'recent', label: 'Recent', onClick: () => fetchRecent() },
+    { id: 'search', label: 'Search', onClick: (e) => { e.stopPropagation(); openSearch() } },
+  ]}
 />
-```
-
-> **Note:** Stack multiple cards inside a `rounded-md` container — the `last:border-b-0` rule automatically removes the bottom divider from the final card, keeping the visual frame clean.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.mingo-welcome.md b/openframe-frontend-core/src/components/chat/.mingo-welcome.md
new file mode 100644
index 000000000..aaec27c44
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/.mingo-welcome.md
@@ -0,0 +1,69 @@
+<!-- source-hash: 4b7cfd6d117eeb1fd557cdd7ff13a47a -->
+Renders the Mingo AI chat empty state, including a personalized greeting, capability feature grid, optional one-time onboarding promo notification, and quick-action chips — with distinct states for new users, returning users (chat history), loading, and load errors.
+
+## Key Components
+
+### Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `MingoFeatureCard` | Single cell in the 2-up capability grid (icon + text) |
+| `MingoWelcomePromo` | "New to OpenFrame?" one-time notification config |
+| `MingoQuickAction` | Extra quick-action chip appended after "Start Guide Chat" |
+| `MingoWelcomeProps` | Full props surface for `MingoWelcome` |
+
+### Component
+
+**`MingoWelcome`** — Main export. Figma node `7532:222444`.
+
+Renders one of four states depending on props:
+
+```mermaid
+graph TD
+    A["MingoWelcome"] --> B{"dialogHistory\nprovided?"}
+    B -->|"Yes"| C["Chat History View"]
+    B -->|"No"| D{"loadError?"}
+    D -->|"Yes"| E["Error + Retry Block"]
+    D -->|"No"| F{"isLoadingHistory?"}
+    F -->|"Yes"| G["MingoChatHistorySkeleton"]
+    F -->|"No"| H["Greeting + Feature Grid"]
+```
+
+### Internal Behaviors
+- **Promo dismissal** — persisted to `localStorage` or `sessionStorage` (SSR-safe, storage-error-tolerant)
+- **Scroll fade affordances** — top/bottom gradient via `ResizeObserver` on the scroll container
+- **Heading resolution** — `title` prop → `"Hey {userName}, I'm Mingo"` → `"Hey, I'm Mingo"`
+
+## Usage Example
+
+```typescript
+import { MingoWelcome } from './mingo-welcome'
+
+// New user — show greeting, feature grid, and Guide Chat promo
+<MingoWelcome
+  userName="Alex"
+  onStartGuideChat={() => switchToGuideMode()}
+/>
+
+// Returning user — replace greeting with chat history
+<MingoWelcome
+  userName="Alex"
+  hasExistingChats
+  dialogHistory={<MingoChatHistory dialogs={dialogs} />}
+  isLoadingHistory={isLoading}
+  loadError={hasFailed}
+  onRetry={refetch}
+  onStartGuideChat={() => switchToGuideMode()}
+  quickActions={[
+    { id: 'explore', label: 'Explore', icon: <CompassIcon />, onClick: openExplorer },
+  ]}
+/>
+
+// Custom branding — suppress OpenFrame defaults
+<MingoWelcome
+  title="Hey, I'm your AI assistant"
+  subtitle="Ask me anything."
+  featureCards={myCards}
+  promo={null}
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/.nav-link-anchor-via-runtime.md b/openframe-frontend-core/src/components/chat/.nav-link-anchor-via-runtime.md
index c8059053d..725bee910 100644
--- a/openframe-frontend-core/src/components/chat/.nav-link-anchor-via-runtime.md
+++ b/openframe-frontend-core/src/components/chat/.nav-link-anchor-via-runtime.md
@@ -1,40 +1,36 @@
-<!-- source-hash: 7bb7ab52d16e8c26a26fa5ab1feba948 -->
-A client-side `<a>` wrapper used within the chat tree to handle link navigation by reading the active `ChatRuntime` and routing clicks through the shared `handleChatNavClick` utility.
+<!-- source-hash: 83b227b8e0df5ad60d3358b3d5e15409 -->
+Chat-tree `<a>` wrapper that routes link clicks through the active `ChatRuntime`, applying new-tab logic, relay attributes, and panel close behavior for same-tab navigation.
 
 ## Key Components
 
 ### `NavLinkAnchorViaRuntimeProps`
 | Prop | Type | Description |
 |------|------|-------------|
-| `href` | `string` | Raw href to resolve |
-| `path` | `string \| null` | Optional internal path hint |
-| `targetPlatform` | `string \| null` | Platform target override |
-| `className` | `string` | Optional CSS class |
-| `children` | `ReactNode` | Optional child content |
+| `href` | `string` | Raw href, resolved against the runtime before use |
+| `path` | `string \| null` | Optional internal path for same-tab routing |
+| `targetPlatform` | `string \| null` | Hints the new-tab decision logic |
+| `className` | `string` | Forwarded to the `<a>` tag |
+| `children` | `ReactNode` | Optional — empty anchors are valid |
 
 ### `NavLinkAnchorViaRuntime`
-The main exported component. Orchestrates four responsibilities:
-1. **Resolves `href`** via `resolveHrefForRuntime` (runtime-aware URL normalization)
-2. **Decides new-tab vs. same-tab** via `computeIsNewTab` (embed-mode short-circuit → `runtime.navigation.decideNewTab` → lib fallback)
-3. **Sets `target`/`rel`** attributes via `newTabAnchorAttrs`
-4. **Closes the chat panel** on same-tab navigation via `ChatPanelContext.closeChat`
-
-> **⚠️ Chat-tree only:** Uses `useRequiredChatRuntime`, which **throws** when mounted outside a `<ChatRuntimeContext.Provider>`. This is intentional — no silent fallback. For surfaces outside the chat tree (header chrome, marketing pages), use the hub's `useNavLink`-based anchor instead.
+The exported component. On each render it:
+1. Reads the `ChatRuntime` via `useRequiredChatRuntime` — **throws** if mounted outside a `<ChatRuntimeContext.Provider>`
+2. Resolves the final href via `resolveHrefForRuntime`
+3. Determines new-tab behavior via `computeIsNewTab` (embed-mode short-circuit → `runtime.navigation.decideNewTab` → lib fallback)
+4. On click, delegates to `handleChatNavClick`; if handled in the same tab, calls `panel.closeChat()`
 
 ## Usage Example
 
 ```typescript
-// Used in markdown-rendered chat bodies or source-chip drill-ins
+// Inside a chat markdown body or source-chip drill-in
 <NavLinkAnchorViaRuntime
-  href="https://example.com/docs/setup"
-  path="/docs/setup"
+  href="https://docs.example.com/guide"
+  path="/guide"
   targetPlatform="web"
   className="chat-link"
 >
-  View Setup Guide
+  View Documentation
 </NavLinkAnchorViaRuntime>
 ```
 
-At runtime:
-- **Same-tab click** → navigates and calls `panel.closeChat()` to dismiss the chat panel
-- **New-tab click** → opens in a new tab, leaving the chat panel open
\ No newline at end of file
+> **Chat-only contract:** This component is intentionally restricted to the chat tree. For navigation outside the chat context (header chrome, marketing pages), use the hub's `useNavLink`-based anchor instead.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.blog-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.blog-card.md
index f76b7ded6..cb234204a 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.blog-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.blog-card.md
@@ -1,52 +1,51 @@
-<!-- source-hash: 84fe8c9e8dffcbf0ae0ec8ff163a67e2 -->
-Pure presentation component for rendering blog post cards in two density modes (`default` and `sm`), with no built-in click/navigation logic — callers supply the resolved `href` and wrap with their own anchor strategy.
+<!-- source-hash: 2a6f62770b5cb54f63fadad603b51ac0 -->
+Pure presentation component for rendering blog post cards in two density modes: full vertical (`default`) and compact horizontal (`sm`) for chat-inline contexts.
 
 ## Key Components
 
 ### `BlogCard`
-Main card component supporting two layouts:
-- **`default`**: Full vertical card with cover image, title, summary, author avatar, date, and view count
-- **`sm`**: Compact horizontal card (~80px tall) designed for chat-inline rendering, showing a thumbnail, title, category, and summary
+Main card component. Renders a fully clickable card with cover image, title, summary, and author/date footer. Delegates link behavior to `useEntityCardLink` and image fallback to `useEntityCardPlaceholder`.
 
 ### `BlogCardSkeleton`
-Loading placeholder matching both `default` and `sm` density layouts using animated pulse styles.
+Loading placeholder that mirrors the layout of each size variant using animated pulse styles.
 
 ### `BlogCardProps`
 | Prop | Type | Description |
-|---|---|---|
-| `post` | `BlogPostSummary` | Post data (title, image, author, etc.) |
-| `href` | `string` | Resolved detail URL from caller |
-| `target` | `'_blank'` | Opens in new tab (set by chat dispatch) |
-| `placeholderUrl` | `string \| null` | Fallback image when `featured_image` is missing |
+|------|------|-------------|
+| `post` | `BlogPostSummary` | Post data to render |
+| `href` | `string` | Resolved detail URL (caller-provided) |
 | `size` | `'default' \| 'sm'` | Card density mode |
-| `hasEmbeddedVideo` | `boolean` | Surfaces a "Video" badge in compact mode |
+| `placeholderUrl` | `string \| null` | Fallback image (e.g. from `useOgPlaceholder`) |
+| `hasEmbeddedVideo` | `boolean` | Shows a "Video" badge in `sm` mode |
 | `priority` | `boolean` | Passes LCP priority hint to the cover image |
-
-**Image fallback chain:** `post.featured_image` → `placeholderUrl` → `bg-ods-bg` background slot
+| `target` / `rel` | string | Tab behavior, set by chat dispatch |
 
 ## Usage Example
 
 ```typescript
-// Default full card — caller wraps with navigation anchor
+import { BlogCard, BlogCardSkeleton } from './blog-card'
+
+// Full card (default density)
 <BlogCard
-  post={blogPostSummary}
+  post={post}
   href={buildContentURL(post.slug)}
-  placeholderUrl={useOgPlaceholder(post)}
+  placeholderUrl={useOgPlaceholder(post.title)}
   size="default"
-  priority={true}
+  priority={isAboveFold}
 />
 
-// Compact card for chat-inline rendering
+// Compact card for chat inline rendering
 <BlogCard
-  post={blogPostSummary}
+  post={post}
   href={detailUrl}
   target="_blank"
   rel="noopener noreferrer"
   size="sm"
   hasEmbeddedVideo={true}
-  placeholderUrl={staticFallbackUrl}
 />
 
-// Skeleton while loading
-<BlogCardSkeleton size="sm" />
-```
\ No newline at end of file
+// Loading state
+<BlogCardSkeleton size="default" />
+```
+
+> **No click logic lives inside this component.** Callers are responsible for wrapping with an anchor or passing a resolved `href`. The image fallback chain is: `post.featured_image` → `placeholderUrl` → `bg-ods-bg` background slot.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.case-study-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.case-study-card.md
index 3cfafec76..eb84da5bd 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.case-study-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.case-study-card.md
@@ -1,30 +1,13 @@
-<!-- source-hash: 02a29dbf8a78be028a2e952b979247a7 -->
-Pure presentation component for displaying MSP case studies in two density modes — `default` (vertical detail card) and `sm` (compact horizontal for chat-inline rendering).
+<!-- source-hash: 0ed09cf8a23d351b215d1f076dfd655b -->
+Pure presentation component for rendering MSP case study cards in two density modes (`default` for vertical detail layouts and `sm` for compact horizontal chat-inline display).
 
 ## Key Components
 
-### `CaseStudyCard`
-Main card component. Renders a linked, non-interactive card (no click logic — callers wrap with their own anchor and pass a resolved `href`). Supports:
-- **`default` size**: Full vertical layout with OG-ratio cover image (`1200×630`), title, and author/MSP attribution with avatar stack.
-- **`sm` size**: Compact horizontal layout for embedding in chat threads.
+- **`CaseStudyCard`** — Main card component. Renders a full vertical card (`default`) or compact horizontal card (`sm`). Delegates link behavior to `useEntityCardLink` and image placeholder generation to `useEntityCardPlaceholder`. Contains no internal click logic — callers provide `href`.
+- **`CaseStudyCardSkeleton`** — Matching loading skeleton for both size variants, preserving layout dimensions (OG 1200×630 aspect ratio for `default`, compact slot for `sm`).
+- **`CaseStudyCardProps`** — Interface defining `study`, `href`, optional `target`/`rel`, `placeholderUrl`, `size`, and `className`.
 
-### `CaseStudyCardSkeleton`
-Loading placeholder that mirrors the exact layout and aspect ratios of `CaseStudyCard` for both size variants, using `animate-pulse`.
-
-### Image Fallback Chain
-```text
-study.featured_image → placeholderUrl (from useOgPlaceholder) → bg-ods-bg background
-```
-
-## Key Props (`CaseStudyCardProps`)
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `study` | `CaseStudy` | Case study data object |
-| `href` | `string` | Resolved detail URL (caller-provided) |
-| `target` | `'_blank'` | Opens in new tab (set by chat dispatch) |
-| `placeholderUrl` | `string \| null` | OG fallback image when `featured_image` is missing |
-| `size` | `'default' \| 'sm'` | Card density mode |
+**Image fallback chain:** `study.featured_image` → `placeholderUrl` (caller-provided OG placeholder) → `bg-ods-bg` background.
 
 ## Usage Example
 
@@ -32,27 +15,23 @@ study.featured_image → placeholderUrl (from useOgPlaceholder) → bg-ods-bg ba
 import { CaseStudyCard, CaseStudyCardSkeleton } from './case-study-card'
 import { useOgPlaceholder } from '../hooks/use-og-placeholder'
 
-function CaseStudyGrid({ studies }: { studies: CaseStudy[] }) {
-  const placeholderUrl = useOgPlaceholder(study.id)
-
-  if (!studies) return <CaseStudyCardSkeleton size="default" />
-
-  return (
-    <CaseStudyCard
-      study={study}
-      href={`/case-studies/${study.slug}`}
-      placeholderUrl={placeholderUrl}
-      size="default"
-    />
-  )
-}
+// Default full card
+<CaseStudyCard
+  study={caseStudy}
+  href={`/case-studies/${caseStudy.slug}`}
+  placeholderUrl={useOgPlaceholder(caseStudy.title)}
+  size="default"
+/>
 
-// Chat-inline compact variant
+// Compact variant for chat inline rendering
 <CaseStudyCard
-  study={study}
-  href={`/case-studies/${study.slug}`}
+  study={caseStudy}
+  href={`/case-studies/${caseStudy.slug}`}
   target="_blank"
   rel="noopener noreferrer"
   size="sm"
 />
+
+// Loading state
+<CaseStudyCardSkeleton size="default" />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.chat-ticket-item.md b/openframe-frontend-core/src/components/chat/entity-cards/.chat-ticket-item.md
index 9bd9e47d6..842e8e9de 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.chat-ticket-item.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.chat-ticket-item.md
@@ -1,40 +1,49 @@
-<!-- source-hash: 88aa76a71f078b18928be54e60fe0a71 -->
-A clickable ticket row component for chat interfaces, rendering ticket details (title, number, category, time), a status tag, an optional linked-work chip, and a chevron affordance.
+<!-- source-hash: 2234bf294ebd64547722d9c33ac211cf -->
+A chat UI row component that renders a single support ticket as a clickable button, displaying the ticket title, metadata subtitle, status badge, and an optional linked-work chip.
 
 ## Key Components
 
 ### `ChatTicketItemData`
-Data interface for the ticket row:
+Data interface for ticket row content:
 - `id`, `title`, `ticketNumber` — core identifiers
 - `status` — accepts any known format (`ACTIVE`, `active`, `ACTION_REQUIRED`, etc.)
-- `statusLabel?` — overrides the badge text while preserving status variant/icon (e.g. HubSpot pipeline stage labels)
-- `linkedTaskLabel?` — when set, renders a wrench-icon "linked work" chip indicating an in-flight delivery task
-- `category?`, `timeAgo?` — optional subtitle fields joined with `•`
+- `statusLabel?` — overrides the badge display text while preserving variant/icon from canonical status
+- `statusKind?` / `statusColor?` — drives custom-status lifecycle styling
+- `linkedTaskLabel?` — when set, renders a wrench icon chip showing linked delivery task progress
+- `category?`, `timeAgo?` — appended to the subtitle dot-separated string
 
 ### `ChatTicketItemProps`
-Extends `ButtonHTMLAttributes` (omitting `onClick`) with a typed `onClick?: (ticketId: string) => void` callback.
+Extends `ButtonHTMLAttributes<HTMLButtonElement>` (minus `onClick`), adding:
+- `ticket: ChatTicketItemData`
+- `onClick?: (ticketId: string) => void` — receives the ticket's `id` string
 
 ### `ChatTicketItem`
-A `forwardRef` button component that:
-- Dims the title (`text-ods-text-secondary`) when the ticket is resolved
-- Builds a dot-separated subtitle from `ticketNumber`, `category`, and `timeAgo`
-- Renders `Tag` with `WrenchIcon` (hidden on `sm` screens) when `linkedTaskLabel` is present
-- Handles focus ring via `focus-visible` to prevent stray white borders after click in jsdom/Chromium
+A `forwardRef` button component rendering:
+- **Title** — truncated, dimmed when `status` resolves to `RESOLVED`
+- **Subtitle** — `ticketNumber • category • timeAgo` joined with bullet separator
+- **Linked-work chip** — `Tag` with `WrenchIcon`, hidden on `xs` screens (`sm:inline-flex`)
+- **Status tag** — `TicketStatusTag` resolved via `resolveStatusTagProps`
+- **Chevron button** — right-side navigation affordance
 
 ## Usage Example
 
 ```typescript
+import { ChatTicketItem, ChatTicketItemData } from './chat-ticket-item'
+
+const ticket: ChatTicketItemData = {
+  id: 'tkt_01',
+  title: 'VPN not connecting after update',
+  ticketNumber: '#1042',
+  status: 'ACTION_REQUIRED',
+  statusLabel: 'Waiting on contact',
+  statusKind: 'ACTIVE',
+  category: 'Network',
+  timeAgo: '2h ago',
+  linkedTaskLabel: 'Waiting on version release',
+}
+
 <ChatTicketItem
-  ticket={{
-    id: 'tkt-001',
-    title: 'Email not syncing after password reset',
-    ticketNumber: '#1042',
-    status: 'ACTION_REQUIRED',
-    statusLabel: 'Waiting on contact',
-    category: 'Email',
-    timeAgo: '2h ago',
-    linkedTaskLabel: 'Waiting on version release',
-  }}
-  onClick={(ticketId) => router.push(`/tickets/${ticketId}`)}
+  ticket={ticket}
+  onClick={(id) => router.push(`/tickets/${id}`)}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.customer-interview-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.customer-interview-card.md
index f80f2d27c..cb8a41ae1 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.customer-interview-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.customer-interview-card.md
@@ -1,53 +1,54 @@
-<!-- source-hash: 13f9305f5b11a7a8a688986630bbf7d1 -->
-Pure presentation component for displaying customer interview data in two density variants (`default` and `sm`), with no embedded click logic — navigation is handled entirely by the caller via `href`.
+<!-- source-hash: 141cf2ed1eae96038f028a1e81abaf11 -->
+Pure presentation component for displaying a `CustomerInterview` entity as a card, supporting two density modes: `default` (full vertical layout) and `sm` (compact horizontal for chat-inline use).
 
 ## Key Components
 
 ### `CustomerInterviewCard`
-Main card component rendering interview metadata, thumbnail, video indicator, and author/MSP attribution. Accepts an `href` prop for navigation and delegates all routing concerns to the caller.
+Main card component. Renders a clickable `<a>` wrapper with no internal click logic — callers provide the resolved `href`. Supports:
+- `default` size: thumbnail (1200×630 aspect), title, summary, and author/MSP avatar row
+- `sm` size: compact horizontal layout using shared `COMPACT_CARD_*` class constants
+- Video play overlay when `interview.main_video_url` is present
+- Fallback placeholder image via `useEntityCardPlaceholder`
+- New-tab behavior resolved via `useEntityCardLink`
 
 ### `CustomerInterviewCardSkeleton`
-Animated loading placeholder that mirrors the layout of `CustomerInterviewCard` for both size variants, preventing layout shift during data fetching.
-
-### `CustomerInterviewCardProps`
-```typescript
-interface CustomerInterviewCardProps {
-  interview: CustomerInterview   // Core interview data
-  href: string                   // Resolved detail URL (caller-provided)
-  target?: '_blank'              // Opens in new tab when set
-  rel?: 'noopener noreferrer'
-  placeholderUrl?: string | null // Fallback OG image when featured_image is absent
-  size?: 'default' | 'sm'       // 'sm' = compact horizontal (chat-inline)
-  className?: string
-}
-```
+Animated loading placeholder matching the layout of each size variant.
 
 ## Usage Example
 
 ```typescript
-// Default card — standalone page listing
+import { CustomerInterviewCard, CustomerInterviewCardSkeleton } from './customer-interview-card'
+
+// Default card (e.g. in a grid)
 <CustomerInterviewCard
-  interview={interviewData}
-  href={`/interviews/${interviewData.slug}`}
-  placeholderUrl="/assets/interview-placeholder.jpg"
+  interview={interview}
+  href={`/interviews/${interview.slug}`}
+  size="default"
 />
 
-// Compact variant — inline within chat/AI responses
+// Compact card for chat inline rendering
 <CustomerInterviewCard
-  interview={interviewData}
-  href={`/interviews/${interviewData.slug}`}
+  interview={interview}
+  href={`/interviews/${interview.slug}`}
   target="_blank"
   rel="noopener noreferrer"
   size="sm"
+  placeholderUrl={ogImageUrl}
 />
 
-// Skeleton while fetching
+// Loading state
 <CustomerInterviewCardSkeleton size="sm" />
 ```
 
-## Size Variants
-
-| Variant | Layout | Use Case |
-|---------|--------|----------|
-| `default` | Vertical card with 1200×630 aspect image, summary, and author row | Grid/list pages |
-| `sm` | Compact horizontal row with thumbnail + text column | Chat-inline embeds (Mingo AI / Fae) |
\ No newline at end of file
+## Props (`CustomerInterviewCardProps`)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `interview` | `CustomerInterview` | Entity data to render |
+| `href` | `string` | Resolved detail URL (required) |
+| `target` | `'_blank'` | Opens in new tab when set |
+| `rel` | `'noopener noreferrer'` | Link rel attribute |
+| `targetPlatform` | `string \| null` | Passed to `useEntityCardLink` for tab resolution |
+| `placeholderUrl` | `string \| null` | OG image fallback when `featured_image` is absent |
+| `size` | `'default' \| 'sm'` | Card density; defaults to `'default'` |
+| `className` | `string` | Additional CSS classes |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.dispatch.md b/openframe-frontend-core/src/components/chat/entity-cards/.dispatch.md
index 12175b418..70f2cd787 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.dispatch.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.dispatch.md
@@ -1,39 +1,38 @@
-<!-- source-hash: 32d71d29579661580177180e5a23c34d -->
-Renders the correct compact card component for a given `ChatRef` by dispatching on document type, handling fetch/skeleton states, and wiring navigation props for the chat shell.
+<!-- source-hash: c7143a7b50302d2fa94af1db6cab0b6c -->
+Renders inline entity cards within the Flamingo chat interface by dispatching `ChatRef` objects to their corresponding card components based on document type.
 
 ## Key Components
 
-### Types
-- **`ChatCardDispatchExtras`** — Host-supplied builders for hub-specific derived props (program configs, product-release prop builder, OG placeholder URL generator)
-- **`ChatCardRenderOptions`** — Per-render options including `baseRoute`, `chipBasePlatform`, `extras`, and the pre-computed `isNewTab` flag
+### Types & Interfaces
 
-### Internal Card Wrappers
-- **`GitHubChatCard`** — Renders a compact `GitHubActivityCard` from a `ChatRef`
-- **`HubspotTicketChatCard`** — Extracts ticket metadata (status, priority, customer) from `chatRef.metadata` and renders `HubspotTicketCard`
-- **`SlackChatCard`** — Maps channel name from metadata and renders `SlackMessageCard`
-- **`DataRoomDocChatCard`** — Renders `DataRoomDocCard` with provenance badge resolved via `getSourceLabel`; intentionally falls back to `"Document"` (never `"Data room"`) to avoid false sensitivity labeling
-- **`GenericFinancialChatCard`** — Renders `GenericEntityCard` with badge, color scheme, optional facts list, and subtitle
-- **`ChatInlineVideoPill`** — Inline pill span for video references (non-block contexts)
+- **`ChatCardDispatchExtras`** — Host-supplied builders for hub-side derived props (`programConfigs`, `buildProductReleaseCardProps`, `buildOgPlaceholderUrl`)
+- **`ChatCardRenderOptions`** — Per-render options threaded from the chat shell (`baseRoute`, `isNewTab`, `discuss`, `extras`)
 
-### Utilities Used
-- `buildAnchorProps` / `computeIsNewTab` / `newTabAnchorAttrs` — Anchor attribute construction
-- `resolveHrefForRuntime` / `handleChatNavClick` — Runtime-aware navigation
-- `resolveSourceRowCTA` / `resolveSourceIcon` / `getSourceLabel` — Source chip metadata
+### Internal Components
+
+- **`GitHubChatCard`** — Renders GitHub activity cards (commits, PRs, reviews) using `MingoInfoCard` with review-state status pills
+- **`githubKindIcon(kind)`** — Maps `GitHubActivityKind` to the appropriate icon component
+- **`reviewStateToVariant(state)`** — Maps `PrReviewState` to a `MingoInfoCardStatus` variant string
+
+### Public Entry Points
+
+- **`renderChatInlineEntityCard(ref, opts)`** — Top-level dispatch; hoists video refs to block cards, otherwise routes to compact inline cards
+- **`<ChatCardLoader />`** — Handles fetch, skeleton, and render lifecycle for fetch-mode card entries
 
 ## Usage Example
 
 ```typescript
-// In the chat shell — dispatch a compact inline card
+// Rendering an inline entity card inside the chat shell
+import { renderChatInlineEntityCard } from './dispatch'
+
 const card = renderChatInlineEntityCard(chatRef, {
-  isNewTab: computeIsNewTab(chatRef.url, runtime.source),
-  baseRoute: '/app',
-  chipBasePlatform: 'hub',
+  isNewTab: computeIsNewTab(chatRef.url, runtime),
   extras: {
-    programConfigs: { podcast: myPodcastConfig },
-    buildProductReleaseCardProps: (release) => ({ iconUrl: release.icon }),
-    buildOgPlaceholderUrl: (title) => `/og?title=${encodeURIComponent(title)}`,
+    programConfigs: { podcast: podcastConfig },
+    buildProductReleaseCardProps: (release) => buildProductReleaseCardProps(release),
+    buildOgPlaceholderUrl: (title) => buildOgPlaceholderUrl(title),
   },
 })
 ```
 
-> **Adding a new card type:** Implement the `size='sm'` branch in `./<card>.tsx`, then register one entry in the `CHAT_CARD_REGISTRY` switch inside this file.
\ No newline at end of file
+> **Note:** Hub-only concerns (URL building, platform detection, table ID resolution) are intentionally excluded. Pre-composed URLs arrive via `ref.url` from the server's RAG mapper, and host-side extras are injected at the shell boundary via `ChatCardRenderOptions.extras`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.github-activity-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.github-activity-card.md
index af7662718..069fde9e2 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.github-activity-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.github-activity-card.md
@@ -1,61 +1,51 @@
-<!-- source-hash: c0769109de52014dbb4d350262e4d01d -->
-A pure-presentation React component that renders GitHub activity items (commits, pull requests, and PR reviews) in two layout variants: a list row and a compact inline card.
+<!-- source-hash: 6b0afa744715c35f3d6368d2cbbeb082 -->
+Unified presentation card for GitHub activity items (commits, pull requests, and PR reviews), supporting both row and compact display variants. Pure presentational component with no internal data fetching or navigation logic.
 
 ## Key Components
 
-### Exports
+### `GitHubActivityCard`
+Main card component accepting a `GitHubActivityItem` and rendering in two layouts:
+- **`variant="row"`** — horizontal list row for employee detail views
+- **`variant="compact"`** — inline card for chat `[card://github_commit:<sha>]` markers
 
-| Name | Type | Description |
-|------|------|-------------|
-| `GitHubActivityCard` | Component | Main card renderer supporting `row` and `compact` variants |
-| `GitHubActivityCardSkeleton` | Component | Animated loading placeholder matching both variants |
-| `GitHubActivityCardAnchorProps` | Interface | Pre-composed `<a>` prop bundle passed from caller navigation hooks |
-| `GitHubActivityCardProps` | Interface | Full props shape for `GitHubActivityCard` |
+Navigation is handled externally via the `anchorProps` prop bundle (typically composed by a `useNavLink` hook in the consumer).
 
-### Internal Helpers
+### `GitHubActivityCardSkeleton`
+Loading placeholder matching both `row` and `compact` variants with animated pulse.
 
-| Name | Description |
-|------|-------------|
-| `parseRepoFromUrl` | Extracts `owner/repo` string from a GitHub URL |
-| `kindIcon` | Returns the appropriate Lucide/GitHub icon for `commit`, `pull_request`, or `pr_review` |
-| `kindLabel` | Maps `GitHubActivityKind` to a short display string |
-| `formatActivityId` | Shortens commit SHAs to 7 chars; prefixes PR/review IDs with `#` |
-| `parseGithubTitle` | Parses bracket-prefixed tags (e.g. `[Review:APPROVED]`) from titles without regex backtracking |
-| `ReviewStateBadge` | Renders a color-coded badge for PR review states (`APPROVED`, `CHANGES_REQUESTED`, etc.) |
+### Exported Helpers
+
+| Export | Description |
+|--------|-------------|
+| `kindLabel(kind)` | Maps `GitHubActivityKind` → display string (`"Commit"`, `"PR"`, `"Review"`) |
+| `formatActivityId(id, kind)` | Formats SHA to 7-char short hash or PR number to `#123` |
+| `parseGithubTitle(title, kind)` | Strips prefix tags (e.g. `[Review:APPROVED]`), extracts `PrReviewState` |
+| `reviewStateLabel(state)` | Maps `PrReviewState` → short label for shared use with `MingoInfoCard` |
 
 ## Usage Example
 
 ```typescript
-import { GitHubActivityCard, GitHubActivityCardSkeleton } from './github-activity-card'
+import { GitHubActivityCard } from './github-activity-card'
+import type { GitHubActivityItem } from '../types/entities/github-activity'
 
-// Compact inline card (default) with external link
-<GitHubActivityCard
-  item={{
-    kind: 'pull_request',
-    id: '42',
-    title: 'Fix memory leak in worker pool',
-    url: 'https://github.com/org/repo/pull/42',
-    dateUpdated: '2024-11-01T10:00:00Z',
-  }}
-/>
+const item: GitHubActivityItem = {
+  kind: 'pull_request',
+  id: '42',
+  title: 'Fix memory leak in worker pool',
+  url: 'https://github.com/acme/core/pull/42',
+  dateUpdated: '2024-06-01T12:00:00Z',
+}
 
-// Row variant for activity lists, with caller-composed navigation
+// Compact (chat inline card) — external link fallback
+<GitHubActivityCard item={item} variant="compact" />
+
+// Row with caller-provided navigation
 <GitHubActivityCard
+  item={item}
   variant="row"
-  item={activityItem}
   anchorProps={{
-    href: '/activity/commit/abc1234',
-    onClick: (e) => handleNavigation(e),
+    href: '/internal/activity/42',
+    onClick: (e) => handleNav(e),
   }}
 />
-
-// Loading state
-<GitHubActivityCardSkeleton variant="row" />
-```
-
-## Variants
-
-| Variant | Use Case |
-|---------|----------|
-| `compact` | Chat inline markers (`[card://github_commit:<sha>]`) |
-| `row` | Activity list rows in employee detail views |
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.index.md b/openframe-frontend-core/src/components/chat/entity-cards/.index.md
index 0253f5fe4..d3422ee46 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.index.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.index.md
@@ -1,66 +1,66 @@
-<!-- source-hash: 153106e38c4d90f80e36ec34a77c2d0d -->
-Barrel export file that consolidates all chat-surface entity card components under a single import path, enabling consumers to access any presentation card without knowing its subdirectory location.
+<!-- source-hash: 5a9f5ab17b21a1f8ca178f7a585ef4a3 -->
+Barrel export file for all chat-surface entity cards, consolidating every pure-presentation card component into a single importable path.
 
 ## Key Components
 
 ### Supporting Primitives
-- **`EntityAuthorCard`** — Renders author metadata with `EMPTY_AUTHOR_PLACEHOLDER` fallback
+- **`EntityAuthorCard`** — Author metadata display with `EMPTY_AUTHOR_PLACEHOLDER` fallback
 - **`BlogImagePlaceholder`** — Placeholder image for blog content
 - **`AdminContentCard`** — Admin-facing content card
 
 ### Flat Cards
 - **`BlockCard`** — Generic block-level card
-- **`ChatTicketItem`** — Ticket representation within chat surfaces
-- **`ChatVideoEntityCard`** — Video entity display in chat
+- **`ChatTicketItem`** — Ticket entry for chat surfaces
+- **`ChatVideoEntityCard`** — Video entity card for chat
+- **`ProductReleaseCard`** / **`ProductReleaseCardSkeleton`** — Release notes card with size variants
 
-### Pure-Presentation Cards (with Skeleton variants)
+### Pure-Presentation Cards
 | Card | Skeleton | Notes |
-|------|----------|-------|
-| `BlogCard` | `BlogCardSkeleton` | — |
-| `CaseStudyCard` | `CaseStudyCardSkeleton` | — |
-| `CustomerInterviewCard` | `CustomerInterviewCardSkeleton` | — |
-| `InvestorUpdateCard` | `InvestorUpdateCardSkeleton` | — |
-| `OnboardingGuideCard` | `OnboardingGuideCardSkeleton` | — |
-| `RoadmapCard` | `RoadmapCardSkeleton` | Includes `VoteType` + `RoadmapVoteButton` |
-| `GitHubActivityCard` | `GitHubActivityCardSkeleton` | — |
-| `SlackMessageCard` | `SlackMessageCardSkeleton` | — |
-| `HubspotTicketCard` | `HubspotTicketCardSkeleton` | — |
-| `DataRoomDocCard` | `DataRoomDocCardSkeleton` | — |
-| `ProgramCard` | `ProgramCardSkeleton` | — |
-| `CampaignCardAdmin` | `CampaignCardAdminSkeleton` | — |
-| `GenericEntityCard` | `GenericEntityCardSkeleton` | Fallback catch-all |
+|---|---|---|
+| `BlogCard` | ✅ | — |
+| `CaseStudyCard` | ✅ | — |
+| `CustomerInterviewCard` | ✅ | — |
+| `InvestorUpdateCard` | ✅ | — |
+| `OnboardingGuideCard` | ✅ | — |
+| `RoadmapCard` | ✅ | Includes `VoteType` + `RoadmapVoteButton` |
+| `GitHubActivityCard` | ✅ | — |
+| `SlackMessageCard` | ✅ | — |
+| `HubspotTicketCard` | ✅ | — |
+| `DataRoomDocCard` | ✅ | — |
+| `ProgramCard` | ✅ | — |
+| `CampaignCardAdmin` | ✅ | — |
+| `GenericEntityCard` | ✅ | Catch-all fallback |
 
-### Dispatch Layer
-- **`renderChatInlineEntityCard`** — Renders the correct card given an entity type
-- **`ChatCardLoader`** — Async card loader; new card types registered in `./dispatch.tsx` via `CHAT_CARD_REGISTRY`
+### Dispatch
+- **`renderChatInlineEntityCard`** — Switch-based renderer over all registered card types
+- **`ChatCardLoader`** — Async card loader with registry lookup via `CHAT_CARD_REGISTRY`
+
+### Card-Prop Builders
+- **`defaultBuildProductReleaseCardProps`** — Small chat default builder
+- **`buildProductReleaseCardProps`** — Rich large-format builder with full metadata grid
 
 ## Usage Example
 
 ```typescript
-// Single import replaces per-directory imports
 import {
   BlogCard,
   BlogCardSkeleton,
-  RoadmapCard,
-  ChatCardLoader,
   renderChatInlineEntityCard,
   type BlogCardProps,
   type ChatCardRenderOptions,
 } from '@/components/entity-cards'
 
-// Pure-presentation: consumer owns the anchor
-function MyFeed({ post }: { post: BlogCardProps }) {
+// Pure-presentation usage — consumer owns the anchor
+function BlogCardWrapper({ post, href }: { post: BlogPost; href: string }) {
   return (
-    <NavLinkAnchor href={post.href}>
+    <NavLinkAnchor href={href}>
       <BlogCard {...post} />
     </NavLinkAnchor>
   )
 }
 
-// Dynamic dispatch — resolves card type at runtime
-function ChatEntity({ entity, options }: { entity: unknown; options: ChatCardRenderOptions }) {
-  return renderChatInlineEntityCard(entity, options)
-}
+// Dispatch-based rendering for chat surfaces
+const card = renderChatInlineEntityCard(entityType, data, options)
 ```
 
-> **Design contract:** All cards in this directory are **pure presentation** — they accept a pre-resolved `href` and entity data as props and contain no internal navigation logic. Click handling belongs to the consumer (`NavLinkAnchor` or `NavLinkAnchorViaRuntime`).
\ No newline at end of file
+> **Design contract:** All cards are pure-presentation — they accept a pre-resolved `href` and entity data as props and contain no internal navigation logic. Consumers are responsible for wrapping cards with their own anchor component (`NavLinkAnchor` or `NavLinkAnchorViaRuntime`).
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.investor-update-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.investor-update-card.md
index 3d401e6b2..2e2a21fae 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.investor-update-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.investor-update-card.md
@@ -1,47 +1,51 @@
-<!-- source-hash: 756619c21c965403499e06eb7fef94fa -->
-Pure presentation component for rendering investor update cards in two density modes (`default` and `sm`), with no internal click logic — callers supply the resolved `href`.
+<!-- source-hash: da923d2c26ea232de0e41409647020ff -->
+Pure presentation component for displaying investor updates in two density modes (`default` and `sm`), with no built-in click logic — navigation is handled by the caller via `href`.
 
 ## Key Components
 
 ### `InvestorUpdateCard`
-Main card component. Renders differently based on the `size` prop:
-- **`default`** — delegates to `AdminContentCard` with image, title, summary, badges, and period meta
-- **`sm`** — compact horizontal layout using shared `COMPACT_CARD_*` utility classes
+Main card component rendering an `InvestorUpdate` entity. Delegates link behavior to `useEntityCardLink` and image fallbacks to `useEntityCardPlaceholder`.
+
+- **`default` size** — full card using `AdminContentCard` with cover image, title, summary, update number badge, and period meta.
+- **`sm` size** — compact horizontal layout using shared `COMPACT_CARD_*` class tokens with a square thumbnail, title row, period subtitle, and truncated summary.
 
 ### `InvestorUpdateCardSkeleton`
-Loading placeholder matching the visual footprint of each density mode. Uses `animate-pulse` for the default size.
+Loading placeholder matching the visual footprint of both `default` and `sm` sizes using animated pulse styles.
 
-### `InvestorUpdateCardProps`
+## Props (`InvestorUpdateCardProps`)
 
 | Prop | Type | Description |
 |------|------|-------------|
 | `update` | `InvestorUpdate` | Entity data |
-| `href` | `string` | Resolved detail URL (caller-supplied) |
-| `target` | `'_blank'` | Optional new-tab behavior |
-| `placeholderUrl` | `string \| null` | OG fallback when `featured_image` is absent |
+| `href` | `string` | Resolved detail URL (caller-provided) |
+| `target` | `'_blank'` | Opens in new tab when set |
+| `rel` | `string` | Link rel attribute |
+| `targetPlatform` | `string \| null` | Platform hint for link resolution |
+| `placeholderUrl` | `string \| null` | OG fallback when `featured_image` is missing |
 | `size` | `'default' \| 'sm'` | Card density (defaults to `'default'`) |
+| `className` | `string` | Additional CSS classes |
 
 ## Usage Example
 
 ```typescript
-// Default density — full card
+import { InvestorUpdateCard, InvestorUpdateCardSkeleton } from './investor-update-card'
+
+// Default full card
 <InvestorUpdateCard
   update={investorUpdate}
-  href={`/investor-updates/${investorUpdate.slug}`}
-  placeholderUrl="/images/update-placeholder.png"
+  href={`/updates/${investorUpdate.id}`}
+  size="default"
 />
 
-// Compact horizontal — e.g. inside a chat dispatch or sidebar list
+// Compact card opened in new tab (e.g., chat dispatch)
 <InvestorUpdateCard
   update={investorUpdate}
-  href={`/investor-updates/${investorUpdate.slug}`}
+  href={`/updates/${investorUpdate.id}`}
   target="_blank"
   rel="noopener noreferrer"
   size="sm"
 />
 
-// Skeleton while data loads
+// Loading state
 <InvestorUpdateCardSkeleton size="sm" />
-```
-
-> **Design note:** The component intentionally owns zero click/navigation logic. Tab behavior (`target="_blank"`) is resolved externally (e.g. via `computeIsNewTab`) and passed in, keeping the component fully declarative.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.onboarding-guide-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.onboarding-guide-card.md
index 388247746..9511aa846 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.onboarding-guide-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.onboarding-guide-card.md
@@ -1,58 +1,45 @@
-<!-- source-hash: ecac941a52e178236e11d54fe42337ec -->
-Pure presentation component that renders an onboarding guide card in three layout variants — `catalog`, `default`, and `sm` — plus matching skeleton states for loading UI.
+<!-- source-hash: b9d985f58912b6d9d8f9210b7fd9a3d4 -->
+Brief description: Presentational card component for displaying onboarding guide entries in three layout variants (`catalog`, `default`, `sm`), with runtime-derived link attributes and placeholder image resolution via hub-wired context hooks.
 
 ## Key Components
 
 ### `OnboardingGuideCard`
-Main card component. Stateless and click-logic-free; the caller wraps with navigation and provides the resolved `href`.
+Main card component rendering one of three variants based on the `size` prop:
+- **`catalog`** — Rich detail card with hero image, author grid, step/section metadata, and video duration badge
+- **`default`** — Horizontal step-numbered card for "More in section" rails
+- **`sm`** — Compact inline card for chat-embedded rendering
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `guide` | `OnboardingGuide` | Guide entity data |
-| `href` | `string` | Detail URL resolved by caller |
-| `target` | `'_blank'` | Optional new-tab behavior |
-| `size` | `'catalog' \| 'default' \| 'sm'` | Layout variant (default: `'default'`) |
-| `placeholderUrl` | `string \| null` | OG fallback image for catalog/sm |
-| `className` | `string` | Additional CSS classes |
+Uses `useEntityCardLink` to derive `target`/`rel` from `ChatRuntime.navigation.decideNewTab` and `useEntityCardPlaceholder` for OG placeholder resolution. Explicit prop values always take precedence over runtime-derived ones.
 
 ### `OnboardingGuideCardSkeleton`
-Loading placeholder that mirrors each layout variant's structure with animated pulse states.
+Loading skeleton component matching each of the three size variants with pulse animation placeholders.
 
-### `HORIZONTAL_SIZE_TOKENS`
-Internal token map for spacing/typography in the `default` variant.
-
-## Variants
-
-| Variant | Layout | Use Case |
-|---------|--------|----------|
-| `catalog` | Hero image + author grid | Public catalog page |
-| `default` | Horizontal step-numbered | "More in section" rail |
-| `sm` | Compact horizontal | Chat-inline rendering |
+### `OnboardingGuideCardProps`
+TypeScript interface for all card props, including the `OnboardingGuide` entity, resolved `href`, optional link behavior overrides, and display variant.
 
 ## Usage Example
 
 ```typescript
-import { OnboardingGuideCard, OnboardingGuideCardSkeleton } from './onboarding-guide-card'
-
-// Loading state
-if (isLoading) {
-  return <OnboardingGuideCardSkeleton size="catalog" />
-}
-
-// Catalog variant (public listing)
+// Catalog variant (public guide listing page)
 <OnboardingGuideCard
   guide={guide}
   href={`/guides/${guide.slug}`}
   size="catalog"
-  placeholderUrl={ogImageUrl}
+  targetPlatform="hub"
 />
 
-// Chat inline (sm variant, new tab)
+// Compact variant (chat-inline rendering with pre-resolved props)
 <OnboardingGuideCard
   guide={guide}
   href={`/guides/${guide.slug}`}
   size="sm"
   target="_blank"
   rel="noopener noreferrer"
+  placeholderUrl="https://cdn.example.com/placeholder.jpg"
 />
-```
\ No newline at end of file
+
+// Loading state
+<OnboardingGuideCardSkeleton size="catalog" />
+```
+
+> **Note:** When no runtime is mounted (e.g. tests or SSR), the card defaults to same-tab navigation and omits placeholder images. Pass explicit `target`, `rel`, and `placeholderUrl` props to override.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.product-release-card-defaults.md b/openframe-frontend-core/src/components/chat/entity-cards/.product-release-card-defaults.md
index 088b0dc36..30706eaa5 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.product-release-card-defaults.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.product-release-card-defaults.md
@@ -1,31 +1,42 @@
-<!-- source-hash: 192500e77aad1a0a4024a9e7d8dfcfec -->
-Provides the lib-side default implementation of `buildProductReleaseCardProps` for chat dispatch, satisfying the three fields required by the compact (`size='sm'`) `<ProductReleaseCard>` variant without requiring hub-side extras.
+<!-- source-hash: 29cc203019f2ef9b57297e18679a37af -->
+Provides default prop-builder functions for `<ProductReleaseCard>`, covering both the compact `sm` chat variant (3 fields) and the full `lg` catalog variant (complete metadata grid).
 
 ## Key Components
 
-### Interfaces
-- **`ReleaseLike`** — Loosely typed shape for raw API row data, covering image URLs, video URLs, and release date fields
-- **`DerivedSmProps`** — Output shape containing only the three sm-relevant props: `coverImage`, `hasVideoCover`, and `formattedDate`
+**`defaultBuildProductReleaseCardProps(item)`**
+Lightweight builder for the `sm` card variant. Derives `coverImage`, `hasVideoCover`, and `formattedDate` from raw list-API row data. Used as the fallback when embedders don't supply a custom builder via `opts.extras.buildProductReleaseCardProps`.
 
-### Functions
-- **`pickCover(item)`** — Resolves the best cover image URL by mirroring the hub's `resolveReleaseCover` precedence: video thumbnails take priority when a video is set, falling back to `featured_image` then `og_image_url`
-- **`defaultBuildProductReleaseCardProps(item)`** — Main export; builds the `DerivedSmProps` bundle from an unknown API row, using `formatReleaseDate` for TZ-safe date formatting
+**`buildProductReleaseCardProps(item)`**
+Rich builder for the `lg` card variant. Populates the full `ProductReleaseCardDerivedProps` bundle including release type/status, badge color, view count, author, and changelog counts (`features`, `fixes`, `improvements`, `breaking`). This is the **default** builder for `<ProductReleasesView>`.
 
-## Usage Example
+**`pickCover(item)`** *(internal)*
+Selects the best cover image from a row's candidate fields. Prefers video thumbnails when a video URL is present, falling back to `featured_image` → `og_image_url`.
 
-```typescript
-import { defaultBuildProductReleaseCardProps } from './product-release-card-defaults'
+**`ProductReleaseCardDerivedProps`** *(exported interface)*
+Full type contract for the `lg` builder's return value.
 
-// Used as fallback when opts.extras.buildProductReleaseCardProps is not supplied
-const props = defaultBuildProductReleaseCardProps(apiRow)
-// → { coverImage: 'https://...', hasVideoCover: true, formattedDate: 'Jan 15, 2025' }
+## Usage Example
 
-// Hub-side embedders override with their richer builder via extras:
-const cardProps = (opts.extras?.buildProductReleaseCardProps ?? defaultBuildProductReleaseCardProps)(row)
+```typescript
+import {
+  defaultBuildProductReleaseCardProps,
+  buildProductReleaseCardProps,
+} from './product-release-card-defaults'
+
+// sm chat card — minimal fields only
+const smProps = defaultBuildProductReleaseCardProps(apiRow)
+// { coverImage, hasVideoCover, formattedDate }
+
+// lg catalog card — full metadata grid
+const lgProps = buildProductReleaseCardProps(apiRow)
+// { coverImage, hasVideoCover, formattedDate, releaseType,
+//   releaseStatus, releaseTypeBadgeColor, viewCount,
+//   author, changelogCounts }
+
+// Pass a custom builder via extras to override the default
+<ProductReleasesView
+  buildCardProps={buildProductReleaseCardProps}
+/>
 ```
 
-## Notes
-
-- Uses `formatReleaseDate` (not `new Date().toLocaleDateString`) to avoid UTC off-by-one day shifts on date-only `YYYY-MM-DD` strings
-- Produces an empty string for `formattedDate` when `release_date` is absent, rather than throwing
-- lg-only fields (`changelogCounts`, badge color, view count) are intentionally omitted — hub embedders supply those via `extras`
\ No newline at end of file
+> **TZ safety note:** `formattedDate` uses `formatReleaseDate` in both builders — it splits the `YYYY-MM-DD` string before constructing a `Date`, avoiding the off-by-one-day shift that `new Date(input).toLocaleDateString` produces for date-only inputs west of UTC.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.program-card.md b/openframe-frontend-core/src/components/chat/entity-cards/.program-card.md
index c379d0886..e64695398 100644
--- a/openframe-frontend-core/src/components/chat/entity-cards/.program-card.md
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.program-card.md
@@ -1,59 +1,54 @@
-<!-- source-hash: 882a2c614fa33ecfd7b3ef948ea40a94 -->
-Brief overview of the `program-card.tsx` component — a pure presentational card for displaying podcasts, webinars, and events with two density modes.
+<!-- source-hash: 41e83667a78de52ab1372d0688fe1bb8 -->
+Pure presentation card component for displaying program content (podcasts, webinars, events) in two density modes: `default` (vertical detail) and `sm` (compact horizontal for chat-inline use).
 
 ## Key Components
 
 ### Exports
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ProgramCardSkeleton` | Component | Loading placeholder supporting `default` and `sm` sizes |
-| `ProgramCard<T>` | Generic Component | Main card component, typed against `BaseProgramItem` |
-| `ProgramCardProps<T>` | Interface | Props contract for `ProgramCard` |
+- **`ProgramCard<T>`** — Generic card component accepting any `BaseProgramItem`. Renders full-detail or compact layout based on `size` prop. Contains no click logic; callers provide `href`.
+- **`ProgramCardSkeleton`** — Animated loading placeholder matching both `default` and `sm` card layouts.
 
 ### Internal Helpers
 
-- **`getHosts()`** — Normalizes host data from either a typed array or a JSON string
-- **`MediaGallery`** — Scrollable thumbnail strip with `ImageGalleryModal` lightbox integration
+- **`getHosts()`** — Normalizes `ProgramHost[]` (or JSON string fallback) into `{ name, avatar }` pairs.
+- **`MediaGallery`** — Horizontal scrollable thumbnail strip with lightbox support via `ImageGalleryModal`.
 
-### Card Sizes (`CardSize`)
+### Props (`ProgramCardProps<T>`)
 
-| Size | Layout | Use Case |
-|------|--------|----------|
-| `default` | Vertical, full detail | Standalone page/feed cards |
-| `sm` | Compact horizontal | Chat-inline embeds |
-
-### Type-Aware Metadata
-
-The card adapts displayed metadata based on `config.type`:
-
-- **`podcast`** → Duration via `formatDurationCompact`
-- **`event`** → Location name
-- **`webinar`** → Start time + duration via `formatTimeWithTimezone` / `formatDurationFromRange`
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `ProgramConfig<T>` | Program type (`podcast`, `webinar`, `event`) and labels |
+| `item` | `T extends BaseProgramItem` | The program item data |
+| `href` | `string` | Resolved detail URL (caller-provided) |
+| `size` | `'default' \| 'sm'` | Card density; defaults to `'default'` |
+| `target` | `'_blank'` | Opens in new tab (set by chat dispatch) |
+| `media` | `ProgramMedia[]` | Optional image gallery items |
+| `renderMeta` | `(item: T) => ReactNode` | Override default meta rendering |
 
 ## Usage Example
 
 ```typescript
-import { ProgramCard } from './program-card'
+import { ProgramCard, ProgramCardSkeleton } from './program-card'
+
+// Loading state
+<ProgramCardSkeleton size="sm" />
 
-// Default (vertical) layout
+// Compact inline (chat)
 <ProgramCard
   config={{ type: 'podcast', labels: { singular: 'Episode' } }}
-  item={episode}
-  href="/podcasts/ep-42"
-  size="default"
+  item={podcastEpisode}
+  href="/podcasts/episode-42"
+  target="_blank"
+  rel="noopener noreferrer"
+  size="sm"
 />
 
-// Compact inline variant (e.g., inside chat)
+// Full detail card
 <ProgramCard
   config={{ type: 'webinar', labels: { singular: 'Webinar' } }}
   item={webinarItem}
-  href="https://external.com/webinar"
-  target="_blank"
-  rel="noopener noreferrer"
-  size="sm"
-  placeholderUrl="https://cdn.example.com/og-fallback.png"
+  media={mediaAssets}
+  href="/webinars/intro-to-openframe"
+  size="default"
 />
-```
-
-> **Note:** `ProgramCard` is purely presentational — it owns no navigation logic. Callers are responsible for computing and passing `href` and `target`.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-link.md b/openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-link.md
new file mode 100644
index 000000000..70d3282a8
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-link.md
@@ -0,0 +1,40 @@
+<!-- source-hash: b340dcdf795a4dde839c90b56d635b69 -->
+Resolves `target` and `rel` link attributes for entity cards by delegating the same-tab vs. new-tab decision to the `ChatRuntime` navigation callback, eliminating the need for hub-side wrapper components.
+
+## Key Components
+
+### `useEntityCardLink(args)`
+Main hook that returns computed anchor attributes for entity card links.
+
+- **Explicit override priority** — if `target` or `rel` props are passed, they win immediately; `rel` is auto-paired with `noopener noreferrer` when `target="_blank"` is provided alone to prevent tabnabbing.
+- **Runtime delegation** — when no overrides exist, calls `computeIsNewTab(runtime, href, targetPlatform)` for a unified decision consistent with the click handler (`executeNavigation`).
+- **No-runtime fallback** — returns `{ target: undefined, rel: undefined }` (same-tab), matching the embed-shim documented behavior.
+
+### `UseEntityCardLinkArgs`
+Input interface with `href`, optional `targetPlatform`, and optional explicit `target`/`rel` overrides.
+
+### `EntityCardLinkProps`
+Output interface — `target: '_blank' | undefined` and `rel: 'noopener noreferrer' | undefined`.
+
+## Usage Example
+
+```typescript
+import { useEntityCardLink } from './use-entity-card-link'
+
+function BlogCard({ href, targetPlatform }) {
+  const { target, rel } = useEntityCardLink({ href, targetPlatform })
+
+  return (
+    <a href={href} target={target} rel={rel}>
+      Read more
+    </a>
+  )
+}
+
+// With explicit override (e.g. from chat dispatcher):
+const { target, rel } = useEntityCardLink({
+  href: 'https://example.com',
+  target: '_blank',
+  // rel auto-resolves to 'noopener noreferrer'
+})
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-placeholder.md b/openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-placeholder.md
new file mode 100644
index 000000000..bee689adf
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/entity-cards/.use-entity-card-placeholder.md
@@ -0,0 +1,49 @@
+<!-- source-hash: 47ff9647270510c7af9d156b173b78dd -->
+Resolves OG placeholder URLs for entity cards, consolidating placeholder logic inside the card rather than requiring callers to pre-compute it.
+
+## Key Components
+
+### `UseEntityCardPlaceholderArgs`
+Interface defining hook inputs:
+- `title` — entity label used in the placeholder image
+- `placeholderUrl` — explicit override; bypasses runtime resolution entirely
+- `siteName` — optional subtitle shown under the title
+- `aspect` — output ratio: `'wide'` (default, catalog cards) or `'square'` (compact chat-inline cards)
+
+### `useEntityCardPlaceholder(args)`
+Main hook that resolves a placeholder URL via the following priority chain:
+
+```mermaid
+graph TD
+    A["placeholderUrl prop provided?"] -->|"Yes (even null)"| B["Return explicit prop"]
+    A -->|"No (undefined)"| C["runtime.resolvePlaceholderUrl available?"]
+    C -->|"No"| D["Return null (empty-state)"]
+    C -->|"Yes"| E["useOgPlaceholder → derived URL"]
+    E --> F["Return derived URL"]
+```
+
+## Usage Example
+
+```typescript
+// Inside an entity card component
+const placeholderSrc = useEntityCardPlaceholder({
+  title: 'Acme Corp Firewall Policy',
+  siteName: 'Configurations',
+  aspect: 'wide',
+})
+
+// Explicit override — runtime resolver is skipped entirely
+const placeholderSrc = useEntityCardPlaceholder({
+  title: 'Device Report',
+  placeholderUrl: 'https://cdn.example.com/custom-thumb.png',
+})
+
+// Embedder without wired runtime → returns null → card shows empty-state
+const placeholderSrc = useEntityCardPlaceholder({ title: 'Orphaned Card' })
+// → null
+```
+
+## Notes
+
+- **Backwards compatible** — passing an explicit `placeholderUrl` (including `null`) always wins, so existing callers (chat dispatch, tests) are unaffected
+- Embedders that don't wire `ChatRuntime.resolvePlaceholderUrl` receive `null` and trigger the card's built-in empty-state fallback
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-chat-dialog-manager.md b/openframe-frontend-core/src/components/chat/hooks/.use-chat-dialog-manager.md
new file mode 100644
index 000000000..ee2e76ae0
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-chat-dialog-manager.md
@@ -0,0 +1,53 @@
+<!-- source-hash: 9233061d336994f3f55deffd0d58d4b1 -->
+Manages dialog history state for the chat panel, encapsulating archive navigation, read-only archived conversation mode, and confirmation modal logic so the parent `EmbeddableChat` component remains a thin orchestration layer.
+
+## Key Components
+
+### `UseChatDialogManagerArgs`
+Interface defining required and optional inputs:
+- `dialogs` — active (non-archived) dialog list
+- `activeDialogId`, `selectDialog`, `clearMessages` — conversation selection primitives
+- `renameDialog`, `archiveDialog` — adapter-wired mutations
+- `fetchArchivedDialogs?`, `unarchiveDialog?` — optional callbacks that gate archive/restore UI affordances
+
+### `useChatDialogManager`
+Primary hook returning grouped state and handlers:
+
+| Group | Fields |
+|---|---|
+| Archive page | `archiveOpen`, `archivedDialogs`, `archivedCursor`, `archivedLoading`, `openArchive`, `closeArchive`, `loadArchivedPage`, `handleArchivedSelect` |
+| Current-chat selection | `handleSelectDialog`, `isOpeningDialog` |
+| Archived conversation | `isViewingArchived`, `handleBack`, `activeDialog` |
+| Action modals | `renameTarget`, `archiveTarget`, `restoreTarget` + setters + confirm handlers |
+
+## Usage Example
+
+```typescript
+const dialogManager = useChatDialogManager({
+  dialogs,
+  activeDialogId,
+  selectDialog,
+  clearMessages,
+  renameDialog,
+  archiveDialog,
+  fetchArchivedDialogs,
+  unarchiveDialog,
+})
+
+// Open the archive page
+dialogManager.openArchive()
+
+// Select a dialog from the current-chats list (immediate panel flip)
+dialogManager.handleSelectDialog('dialog-id-123')
+
+// Select from archive (enters read-only mode + disables composer)
+dialogManager.handleArchivedSelect('archived-id-456')
+
+// Trigger rename confirmation modal
+dialogManager.setRenameTarget(someDialogItem)
+
+// Back-chevron: returns to archive page if viewing archived, otherwise list
+dialogManager.handleBack()
+```
+
+> **Note:** `isOpeningDialog` and `isViewingArchived` are synchronously set to avoid lag between panel flip and message load, ensuring immediate UI transitions regardless of data fetch timing.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-chat-identity.md b/openframe-frontend-core/src/components/chat/hooks/.use-chat-identity.md
index 6d133bee4..890af8ddc 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-chat-identity.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-chat-identity.md
@@ -1,45 +1,60 @@
-<!-- source-hash: b3bbee124a5b530f9a19e9b047eec040 -->
-Fetches and surfaces the current chat session's identity tier (`authTier`, `source`, `attachmentsEnabled`, `user`) via a lightweight `useEffect`/`useState` hook — no client-side cache by design.
+<!-- source-hash: 172718e1c803bb321ecd691327a7f8a5 -->
+Resolves and surfaces the current chat session's identity capability bag (`authTier`, `source`, `attachmentsEnabled`, `user`) so client components can gate UI elements without initiating a chat message first.
 
 ## Key Components
 
 ### Interfaces
 
-- **`ChatIdentityResponse`** — Wire shape mirroring the hub's `/api/auth/identity` route response. Includes `authTier` (`'session' | 'bearer-act-as' | 'anon'`), `source`, `attachmentsEnabled` (server-computed), and a nullable `user` object with optional `firstName`, `lastName`, and `avatarUrl`.
-- **`ChatIdentitySurface`** — Extends `ChatIdentityResponse` with an `isLoading` boolean for skeleton/spinner states.
+- **`ChatIdentityResponse`** — Wire-shape mirroring the hub's `/api/auth/identity` route response; includes `authTier`, `source`, `attachmentsEnabled`, and optional `user` fields (`name`, `email`, `firstName`, `lastName`, `avatarUrl`)
+- **`ChatIdentitySurface`** — Extends `ChatIdentityResponse` with `isLoading: boolean`; never throws — errors and loading states fall back to anonymous defaults
 
-### Hook
+### Functions & Components
 
-- **`useChatIdentity()`** — Reads the identity endpoint URL from `useRequiredChatRuntime()`, fires an authenticated fetch via `chatAuthedFetch`, and returns identity data merged with `isLoading`. Falls back to `ANON_DEFAULTS` on errors or non-OK responses — never throws.
-
-### Constants
-
-- **`ANON_DEFAULTS`** — Safe fallback (`authTier: 'anon'`, `attachmentsEnabled: false`, `user: null`) used during loading and on any fetch failure.
+- **`useResolveChatIdentity(enabled)`** — Internal `useEffect` + `useState` resolver; skips the fetch when `enabled = false` (provider present above); refetches automatically on proxy credential rotation via `proxyEmail` dep
+- **`ChatIdentityProvider`** — Optional context provider; resolves identity **once** for its entire subtree; ideal for independent React subtrees (e.g. a persistent chat widget + a tickets router outlet) that cannot share identity via props
+- **`useChatIdentity()`** — Public hook; reads from `ChatIdentityProvider` when present, otherwise self-fetches; always returns a `ChatIdentitySurface`, never suspends
 
 ## Usage Example
 
+### Standalone hook (default, no provider)
+
 ```typescript
 import { useChatIdentity } from './use-chat-identity'
 
 function AttachmentButton() {
   const { isLoading, attachmentsEnabled, user } = useChatIdentity()
 
-  if (isLoading) return <Spinner />
+  if (isLoading) return <Skeleton />
   if (!attachmentsEnabled) return null
 
+  return <button>Attach file ({user?.firstName ?? 'you'})</button>
+}
+```
+
+### Shared provider for independent subtrees
+
+```typescript
+import { ChatIdentityProvider, useChatIdentity } from './use-chat-identity'
+
+// Mount once inside your ChatRuntimeContext.Provider
+function EmbedRoot({ children }: { children: ReactNode }) {
   return (
-    <button>
-      Attach file {user?.firstName ? `(${user.firstName})` : ''}
-    </button>
+    <ChatRuntimeContext.Provider value={runtime}>
+      <ChatIdentityProvider>
+        {children}
+      </ChatIdentityProvider>
+    </ChatRuntimeContext.Provider>
   )
 }
-```
 
-## Design Notes
+// Both components share one /identity fetch
+function ChatWidget() {
+  const { user } = useChatIdentity() // reads provider
+}
+
+function TicketsPage() {
+  const { authTier } = useChatIdentity() // same resolution, no duplicate request
+}
+```
 
-| Concern | Decision |
-|---|---|
-| Caching | None — avoids stale identity across credential rotations |
-| Error handling | Falls back to anon defaults; never throws |
-| Credential changes | Re-fetches automatically when `proxyEmail` (from `localStorage`) changes |
-| `attachmentsEnabled` | Computed server-side; consumers read it directly without combining fields |
\ No newline at end of file
+> **No client-side cache by design.** Identity is always fetched fresh to prevent stale-identity flashes across credential rotations. The `ChatIdentityProvider` lifts the resolver to one shared fetch per subtree without persisting state beyond the component lifecycle.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-jetstream-dialog-subscription.md b/openframe-frontend-core/src/components/chat/hooks/.use-jetstream-dialog-subscription.md
index 934dd02f9..dd42a5839 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-jetstream-dialog-subscription.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-jetstream-dialog-subscription.md
@@ -1,40 +1,41 @@
-<!-- source-hash: dcf2e60dac262a108cfeb8aa720addd1 -->
-Subscribes a React component to a NATS JetStream ephemeral ordered consumer for a specific chat dialog, managing connection lifecycle, reconnection backoff, and sequence-aware resumption.
+<!-- source-hash: d8277c132011fa67f4fa789ab2bd64a0 -->
+React hook for subscribing to a NATS JetStream chat dialog stream via an ephemeral `OrderedConsumer`, with automatic reconnection and sequence tracking.
 
 ## Key Components
 
-- **`useJetStreamDialogSubscription`** — Primary hook export. Manages a shared NATS WebSocket connection (ref-counted singleton) and an ephemeral JetStream `OrderedConsumer` scoped to `chat.{dialogId}.{topic}`.
-- **`SharedConnection`** — Module-level singleton tracking the active NATS client, ref count, and deferred close/retry timers to avoid redundant reconnects across component instances.
-- **`acquireClient`** — Increments the shared connection ref count (or creates a new client if the URL changed), cancelling any pending close timer.
-- **`releaseClient`** — Decrements the ref count and schedules a deferred close (`SHARED_CLOSE_DELAY_MS`) when the last consumer releases the connection.
-- **Connection effect** — Drives `connect()` / status-listener lifecycle; implements jittered exponential backoff with optional fast-retry leading attempts via `reconnectionBackoff`.
-- **Subscription effect** — Recreates the ephemeral consumer on each `isConnected` transition, resuming from `highestStreamSeq + 1` to avoid replaying or skipping chunks.
+- **`useJetStreamDialogSubscription`** — Primary export. Manages the full lifecycle of a NATS WebSocket connection and JetStream consumer for a given `dialogId`.
+- **Connection lifecycle** — Delegates to `startConnectionLifecycle` from the shared NATS client pool (`acquireClient` / `releaseClient`). Reconnects only on `closed` or `disconnected` states; protocol-level `-ERR` responses are surfaced separately.
+- **Sequence tracking** — Tracks the highest observed `streamSequence` in `highestStreamSeqRef`. On reconnect, resumes at `highestStreamSeq + 1` to avoid replaying or skipping chunks.
+- **`DeliverPolicy`** — Uses `byStartSequence` when `optStartSeq` or a resume point is known, otherwise falls back to `new` (live-tail).
+- **Stable callback refs** — All callbacks (`onEvent`, `onConnect`, `onDisconnect`, `onSubscribed`, `onBeforeReconnect`) and options (`getNatsWsUrl`, `reconnectionBackoff`, `inactiveThresholdMs`) are stored in refs to prevent spurious effect re-runs on inline function identity changes.
+- **URL-based reconnect guard** — Resolves `getNatsWsUrl()` synchronously each render so the connection effect depends on the resolved URL string, not the callback identity, avoiding unnecessary teardowns during token rotations.
 
 ## Usage Example
 
 ```typescript
 const { isConnected, isSubscribed, reconnectionCount, currentStreamSeq } =
   useJetStreamDialogSubscription({
-    enabled: true,
-    dialogId: 'dialog-abc123',
-    topic: 'events',
-    optStartSeq: lastKnownSeq,         // null → live-tail (DeliverPolicy.New)
-    getNatsWsUrl: () => 'wss://nats.example.com',
-    onEvent: (data) => console.log('chunk received', data),
-    onConnect: () => console.log('connected'),
-    onDisconnect: () => console.log('disconnected'),
-    reconnectionBackoff: {
-      fastRetries: 3,
-      fastRetryDelayMs: 200,
-      initialDelayMs: 500,
-      maxDelayMs: 30_000,
-      multiplier: 2,
+    enabled: !!dialogId,
+    dialogId: 'dialog-abc-123',
+    topic: 'stream',
+    optStartSeq: lastKnownSeq ?? null,
+    streamName: 'CHAT_CHUNKS',              // optional, default
+    inactiveThresholdMs: 5 * 60_000,        // optional, default
+    getNatsWsUrl: () => buildWsUrl(token),
+    onEvent: (payload, topic) => {
+      appendChunk(payload)
     },
-    inactiveThresholdMs: 5 * 60_000,
+    onConnect: () => console.log('NATS connected'),
+    onDisconnect: () => console.log('NATS disconnected'),
+    onSubscribed: () => console.log('Consumer ready'),
   })
 ```
 
-## Notes
+## Return Values
 
-- Protocol-level `-ERR` events (e.g. ACL violations) are logged as warnings but do **not** trigger reconnect, preventing auth-refresh loops.
-- The shared connection singleton is module-scoped, so multiple hook instances sharing the same WebSocket URL reuse one NATS client.
\ No newline at end of file
+| Field | Type | Description |
+|---|---|---|
+| `isConnected` | `boolean` | WebSocket/NATS connection is live |
+| `isSubscribed` | `boolean` | JetStream consumer is active |
+| `reconnectionCount` | `number` | Increments on each successful reconnect |
+| `currentStreamSeq` | `number \| null` | Highest stream sequence received so far |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-nats-chat-adapter.md b/openframe-frontend-core/src/components/chat/hooks/.use-nats-chat-adapter.md
index 286a195fa..6554b4504 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-nats-chat-adapter.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-nats-chat-adapter.md
@@ -1,52 +1,72 @@
-<!-- source-hash: 6c5780e92306ea381bac35aaf97c435f -->
-Provides the NATS/Mingo-mode transport adapter for the unified chat surface, implementing the `UnifiedChatState` contract so the `useChat({ mode })` dispatcher can switch between NATS and SSE adapters without shell-side branching.
+<!-- source-hash: b9d69cbad30b3255bb4a2e431b361bcd -->
+Provides a NATS/WebSocket transport adapter for Flamingo's unified chat surface, implementing the `UnifiedChatState` contract for Mingo-mode streaming. It manages live NATS event subscriptions, real-time chunk processing, chunk catchup, and optional dialog lifecycle (list, select, create, delete, archive) so the host `useChat({ mode })` dispatcher requires zero branching logic.
 
 ## Key Components
 
-### `UseNatsChatAdapterConfig`
-Consumer-supplied configuration interface covering:
-- `dialogId` — active conversation identifier
-- `getNatsWsUrl` — factory returning the NATS WebSocket URL
-- `publishUserMessage` — consumer-owned send callback (HTTP POST or NATS publish)
-- `fetchChunks` — optional historical chunk fetcher for catchup
-- `clientConfig` — optional NATS auth credentials
-- `enableThinking` / `batchApprovalsEnabled` — processor feature flags
-
-### `UseNatsChatAdapterOptions`
-- `active` — gates the live subscription; keeps message state alive while the mode is hidden
-
-### `useNatsChatAdapter(config, options)`
-Main hook. Composes three internal hooks:
-
-```text
-useNatsDialogSubscription  →  live NATS event tail
-         ↓
-useRealtimeChunkProcessor  →  chunk → MessageSegment[]
-         ↓
-useChunkCatchup            →  back-fills missed chunks on reconnect/activation
+### Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `UseNatsChatAdapterConfig` | Consumer-supplied configuration; only `getNatsWsUrl` + `publishUserMessage` are required |
+| `FetchDialogsParams` / `FetchDialogsResult` | Paginated dialog list fetch contract |
+| `FetchDialogMessagesParams` / `FetchDialogMessagesResult` | Paginated message history fetch contract |
+
+### Operating Modes
+
+```mermaid
+graph TD
+    A["useNatsChatAdapter"] --> B{"fetchDialogs\nprovided?"}
+    B -->|"No"| C["Bare-transport mode\n(Tauri Fae Chat)\nConsumer owns dialogId"]
+    B -->|"Yes"| D["Managed-dialog mode\n(EmbeddableChat / OpenFrame)\nAdapter owns dialog state"]
+    C --> E["useNatsDialogSubscription"]
+    D --> E
+    E --> F["useRealtimeChunkProcessor"]
+    F --> G["useChunkCatchup\n(backfill missed chunks)"]
 ```
 
-Returns a full `UnifiedChatState` object including `messages`, `isLoading`, `streamingPhase`, `sendMessage`, `stopMessage`, and `clearMessages`.
+### Key Config Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `getNatsWsUrl` | ✅ | Returns NATS WebSocket URL or `null` to pause subscription |
+| `publishUserMessage` | ✅ | Consumer-owned send; adapter only updates local state + calls this |
+| `topics` | ❌ | NATS subjects to tail; use `['admin-message']` for Mingo/admin chat |
+| `fetchDialogs` | ❌ | Enables managed-dialog mode with sidebar pagination |
+| `fetchDialogMessages` | ❌ | Loads history on dialog switch |
+| `createDialog` / `deleteDialog` | ❌ | Dialog lifecycle; omitting hides affordances |
+| `approveRequest` / `rejectRequest` | ❌ | Tool-call approval cards; omitting disables buttons |
+| `stopGeneration` | ❌ | Backend cancellation; omitting makes stop UI-only |
 
 ## Usage Example
 
 ```typescript
-const chatState = useNatsChatAdapter(
-  {
-    dialogId: 'dialog-abc123',
-    getNatsWsUrl: () => `wss://nats.example.com`,
-    publishUserMessage: async (text, { dialogId }) => {
-      await fetch('/api/chat', {
-        method: 'POST',
-        body: JSON.stringify({ text, dialogId }),
-      })
-    },
-    fetchChunks: ({ dialogId, after }) =>
-      fetch(`/api/chunks?dialogId=${dialogId}&after=${after}`).then(r => r.json()),
-    batchApprovalsEnabled: true,
+// Bare-transport mode (Tauri Fae Chat / v0 consumers)
+const chatState = useNatsChatAdapter({
+  dialogId: 'dialog-abc123',
+  getNatsWsUrl: () => 'wss://nats.example.com',
+  publishUserMessage: async (text, { dialogId }) => {
+    await fetch('/api/chat/send', {
+      method: 'POST',
+      body: JSON.stringify({ text, dialogId }),
+    })
   },
-  { active: isNatsModeVisible },
-)
+  topics: ['admin-message'], // Required for Mingo/admin agent replies
+})
+
+// Managed-dialog mode (OpenFrame EmbeddableChat)
+const chatState = useNatsChatAdapter({
+  getNatsWsUrl: () => wsUrl,
+  publishUserMessage: sendToBackend,
+  topics: ['admin-message'],
+  fetchDialogs: async ({ cursor, limit }) =>
+    api.getDialogs({ cursor, limit }),
+  fetchDialogMessages: async ({ dialogId, cursor }) =>
+    api.getMessages({ dialogId, cursor }),
+  createDialog: async () => api.newDialog(),
+  deleteDialog: async (id) => api.deleteDialog(id),
+  approveRequest: async (requestId) => api.approve(requestId),
+  stopGeneration: async (dialogId) => api.cancelStream(dialogId),
+})
 ```
 
-> **Note:** `publishUserMessage` is intentionally consumer-owned — the adapter only handles optimistic UI updates and phase transitions; the actual transport is wired externally.
\ No newline at end of file
+> **Note:** Always set `topics: ['admin-message']` for Mingo/admin deployments. Using the default `['message']` topic will cause assistant responses to never arrive, leaving the UI in the `thinking` phase indefinitely.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-nats-dialog-subscription.md b/openframe-frontend-core/src/components/chat/hooks/.use-nats-dialog-subscription.md
index 4f39288da..9f8367e77 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-nats-dialog-subscription.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-nats-dialog-subscription.md
@@ -1,65 +1,65 @@
-<!-- source-hash: 9e073aef3e517df1b4ab46b93212f4cb -->
-Provides a React hook for managing NATS WebSocket dialog subscriptions with shared connection pooling, automatic reconnection with exponential backoff, and multi-topic support.
+<!-- source-hash: 068b7438be4275aa679400dda3917ca7 -->
+React hook for managing NATS WebSocket subscriptions scoped to a specific dialog, handling connection lifecycle, automatic reconnection, and multi-topic message routing.
 
 ## Key Components
 
 ### `useNatsDialogSubscription(options)`
-The primary exported hook that manages the full lifecycle of a NATS dialog subscription.
+Primary hook that manages the full NATS connection and subscription lifecycle for a dialog.
 
 **Parameters (`UseNatsDialogSubscriptionOptions`):**
+- `enabled` — toggles the connection on/off
+- `dialogId` — the dialog to subscribe to (maps to `chat.<dialogId>.<topic>`)
+- `topics` — array of `NatsMessageType` topics (default: `['message']`)
+- `onEvent` — callback fired with parsed message payload and topic type
+- `onConnect` / `onDisconnect` / `onSubscribed` / `onBeforeReconnect` — lifecycle callbacks
+- `getNatsWsUrl` — function returning the WebSocket URL (resolved each render to avoid unnecessary reconnects on callback identity changes)
+- `clientConfig` — NATS client credentials (`name`, `user`, `pass`)
+- `reconnectionBackoff` — custom backoff strategy
 
-| Option | Description |
-|--------|-------------|
-| `enabled` | Toggles the connection/subscription on or off |
-| `dialogId` | The dialog ID to subscribe to (e.g., `chat.<dialogId>.<topic>`) |
-| `topics` | Array of `NatsMessageType` values to subscribe to (default: `['message']`) |
-| `onEvent` | Callback fired when a NATS message is received |
-| `onConnect` / `onDisconnect` | Lifecycle callbacks for connection state changes |
-| `onSubscribed` | Fired when subscriptions are successfully established |
-| `onBeforeReconnect` | Async hook called before each reconnection attempt (e.g., token refresh) |
-| `getNatsWsUrl` | Factory function returning the WebSocket URL |
-| `clientConfig` | Optional NATS client config overrides (`name`, `user`, `pass`) |
-| `reconnectionBackoff` | Configures retry delays: `fastRetries`, `initialDelayMs`, `maxDelayMs`, `multiplier` |
+**Returns (`UseNatsDialogSubscriptionReturn`):**
+- `isConnected` — current WebSocket connection state
+- `isSubscribed` — whether topic subscriptions are active
+- `reconnectionCount` — number of reconnections since mount
 
-**Returns (`UseNatsDialogSubscriptionReturn`):** `{ isConnected, isSubscribed, reconnectionCount }`
+### `buildNatsWsUrl(apiBaseUrl, options?)`
+Utility to construct a NATS WebSocket URL from an HTTP/HTTPS base URL.
 
-### `SharedConnection` (module-level singleton)
-A module-scoped singleton that reference-counts active consumers sharing the same WebSocket URL, with a deferred close delay (`SHARED_CLOSE_DELAY_MS`) to avoid reconnect churn during component remounts.
+**Parameters:**
+- `source: 'dashboard'` routes to `/ws/nats-api`, otherwise `/ws/nats`
+- `includeAuthParam` + `token` — appends `?authorization=<token>` to the URL
 
 ## Usage Example
 
 ```typescript
-import { useNatsDialogSubscription } from './use-nats-dialog-subscription'
+import {
+  useNatsDialogSubscription,
+  buildNatsWsUrl,
+} from './use-nats-dialog-subscription'
 
-function DialogListener({ dialogId }: { dialogId: string }) {
+function DialogListener({ dialogId, token }: { dialogId: string; token: string }) {
   const { isConnected, isSubscribed, reconnectionCount } = useNatsDialogSubscription({
     enabled: true,
     dialogId,
-    topics: ['message', 'admin-message'],
-    getNatsWsUrl: () => 'ws://nats.example.com:4223',
-    onEvent: (event, messageType) => {
-      console.log(`[${messageType}]`, event)
+    topics: ['message', 'typing'],
+    getNatsWsUrl: () =>
+      buildNatsWsUrl('https://api.example.com', {
+        token,
+        includeAuthParam: true,
+        source: 'dashboard',
+      }),
+    onEvent: (payload, topic) => {
+      console.log(`[${topic}]`, payload)
     },
     onConnect: () => console.log('NATS connected'),
     onDisconnect: () => console.log('NATS disconnected'),
-    onBeforeReconnect: async () => {
-      await refreshAuthToken() // e.g., refresh JWT before retry
-    },
-    reconnectionBackoff: {
-      fastRetries: 3,
-      fastRetryDelayMs: 500,
-      initialDelayMs: 1000,
-      maxDelayMs: 30000,
-      multiplier: 2,
-    },
   })
 
-  return <div>Connected: {isConnected ? 'Yes' : 'No'} | Reconnects: {reconnectionCount}</div>
+  return (
+    <span>
+      {isConnected ? '🟢' : '🔴'} Subscribed: {String(isSubscribed)} | Reconnects: {reconnectionCount}
+    </span>
+  )
 }
 ```
 
-## Notes
-
-- Reconnection uses **jittered exponential backoff** (`delay * (0.5 + random * 0.5)`) to avoid thundering herd scenarios.
-- Callbacks (`onEvent`, `onConnect`, etc.) are stored in stable refs, so they never trigger reconnection when their identity changes.
-- The shared connection is scoped per WebSocket URL — switching URLs tears down the old connection before establishing a new one.
\ No newline at end of file
+> **Note:** The `getNatsWsUrl` function is resolved on every render and compared by URL string value — not by callback identity — to prevent spurious reconnects during token rotation.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-slash-commands.md b/openframe-frontend-core/src/components/chat/hooks/.use-slash-commands.md
index a47a8eb50..70fc44980 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-slash-commands.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-slash-commands.md
@@ -1,46 +1,46 @@
-<!-- source-hash: 433665c60d11f92235ffb1f5227d3b44 -->
-Debounced React hook and stateless fetch helper for slash-command autocomplete suggestions in the OpenFrame chat interface.
+<!-- source-hash: 9e1425674b337ae5672526173d8975eb -->
+Provides slash-command autocomplete functionality for the OpenFrame chat interface, including a stateless fetch helper, a debounced React hook, and a session-cached registry hook.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `fetchSlashCommands` | `async function` | Stateless fetch wrapper; resolves suggestions from a caller-supplied `commandsUrl`, returns empty array on any non-2xx response |
-| `useSlashCommands` | React hook | Debounced (150ms), cancellable hook returning `{ commands, loading }` |
-| `SlashCommandSummary` | Re-exported type | Canonical summary shape for a slash command |
-| `SlashCommandSummaryAction` | Re-exported type | Action payload within a summary |
-| `SlashCommandActionId` | Re-exported type | Identifier type for actions |
+| `fetchSlashCommands` | `async function` | Stateless fetch wrapper; resolves commands from a caller-supplied URL, returns empty array on non-2xx responses |
+| `useSlashCommands` | React hook | Debounced (150ms), cancellable hook returning `{ commands, loading }` for live prefix-based autocomplete |
+| `useSlashCommandRegistry` | React hook | Full registry fetch via `react-query`; session-cached (`staleTime`/`gcTime: Infinity`), deduplicated across consumers |
+| `SlashCommandSummary` | Re-exported type | Canonical type from `component.types`; shared by the dropdown UI and chat runtime |
+| `SlashCommandSummaryAction` | Re-exported type | Action descriptor attached to each command |
+| `SlashCommandActionId` | Re-exported type | Identifier type for command actions |
 
 ## Usage Example
 
 ```typescript
 import {
   useSlashCommands,
+  useSlashCommandRegistry,
   fetchSlashCommands,
 } from "@flamingo-stack/openframe-frontend-core/components/chat/hooks";
-import { useChatRuntime } from "./chat-runtime";
 
-// Hook usage (preferred in React components)
-function SlashCommandDropdown({ prefix }: { prefix: string | null }) {
-  const { endpoints } = useChatRuntime();
-  const { commands, loading } = useSlashCommands(prefix, endpoints.commandsUrl);
+// Live autocomplete as user types (debounced, cancellable)
+function SlashMenu({ prefix }: { prefix: string | null }) {
+  const { commandsUrl } = useChatRuntime().endpoints;
+  const { commands, loading } = useSlashCommands(prefix, commandsUrl);
 
-  if (loading) return <Spinner />;
-  return <CommandList items={commands} />;
+  return loading ? <Spinner /> : <CommandList items={commands} />;
 }
 
-// Stateless usage (e.g. outside React, in a server action test)
-const ctrl = new AbortController();
-const suggestions = await fetchSlashCommands(
-  "res",
-  ctrl.signal,
-  "/api/mingo-guide/commands",
-);
-```
+// Session-wide registry — one network request, shared across consumers
+function ChatPanel({ mode }: { mode: "guide" | "mingo" }) {
+  const { commandsUrl } = useChatRuntime().endpoints;
+  const { commands, loaded } = useSlashCommandRegistry(commandsUrl, {
+    enabled: mode === "guide",
+  });
+
+  return loaded ? <OnboardingCard commands={commands} /> : null;
+}
 
-## Notes
+// Stateless imperative fetch (e.g. SSE adapter, server actions)
+const results = await fetchSlashCommands("dep", undefined, commandsUrl);
+```
 
-- `commandsUrl` has **no default** — always supply via `useChatRuntime().endpoints.commandsUrl`
-- URL resolution uses `new URL(commandsUrl, window.location.origin)`, supporting both relative and absolute URLs
-- Non-2xx responses (401, 403, 429) return `[]` silently — no error toasts
-- `AbortError` on unmount/dependency change is swallowed; other errors emit a `console.warn`
\ No newline at end of file
+> **Auth note:** All fetches ride on `embedAuthedFetch`, inheriting bearer/act-as credentials and 401 self-healing automatically — no host-side `window.fetch` patching required.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-sse-chat-adapter.md b/openframe-frontend-core/src/components/chat/hooks/.use-sse-chat-adapter.md
index 53e0da486..ec337717a 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-sse-chat-adapter.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-sse-chat-adapter.md
@@ -1,34 +1,48 @@
-<!-- source-hash: c000c5cabcd81a500ce236944b8c4464 -->
-Provides the SSE/Guide-mode transport adapter for the unified chat surface, implementing `UnifiedChatState` by consuming server-sent events from the chat stream endpoint and mapping them into structured `DocChatMessage` segments, sources, refs, and per-turn metadata.
+<!-- source-hash: b64329bea22eab16802f8dbf5b7a58c5 -->
+Adapter hook that bridges the unified chat surface to an SSE (Server-Sent Events) transport layer for Guide mode, handling message streaming, source tracking, metadata extraction, and turn lifecycle management.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `useSseChatAdapter` | Hook | Primary hook — reads `source` from runtime context, manages SSE stream lifecycle, slash commands, and turn metadata |
-| `DocChatMessage` | Interface | Full message shape including `segments`, `sources`, `chatRefs`, and `scrollAnchor` |
-| `ChatSource` | Interface | Per-citation source descriptor with support for single-row and grouped chips |
-| `ChatTurnMeta` | Interface | Per-turn LLM metadata (provider, token counts, cache hit rate, routing decision) |
-| `UseSseChatAdapterOptions` | Interface | DI options — primarily `tableIdForDocumentType` override for non-standard RAG table configs |
-| `StreamingPhase` | Type (re-export) | Streaming lifecycle phase, re-exported from `unified-chat-state.types` for backward compatibility |
-| `createDocStreamFn` | Internal factory | Builds the per-call async generator that POSTs to the SSE endpoint and yields `MessageSegment` chunks |
+**`useSseChatAdapter(options?, runtimeOptions?)`**
+Main hook returning a `UnifiedChatState` object. Wraps `useChat` with SSE-specific streaming logic, slash-command hydration, and per-turn metadata tracking.
+
+**`createDocStreamFn(...)`**
+Factory that produces a per-call async generator consuming the SSE stream. Handles message history filtering, approval-action routing, and incremental segment yielding. Decoder/buffer are scoped per-call to prevent cross-stream contamination on rapid send-stop-send sequences.
+
+**Types**
+| Type | Purpose |
+|------|---------|
+| `DocChatMessage` | Full message shape including segments, sources, refs, and scroll anchors |
+| `ChatSource` | RAG source metadata with grouped-chip support |
+| `ChatTurnMeta` | Per-turn provider/model/token/routing metadata extracted from stream frames |
+| `UseSseChatAdapterOptions` | DI slot for `tableIdForDocumentType` override |
+| `StreamingPhase` | Re-exported from `unified-chat-state.types` for backward-compatible imports |
+
+**Key behavioral contracts**
+- `source` is read from runtime, never sent on the wire (server resolves via `currentPlatform()`)
+- Falls back to `defaultTableIdForDocumentType` when no override is injected
+- Navigation is delegated to `handleChatNavClick`, not internal router calls
+- Hidden messages are filtered from the API history before each send
 
 ## Usage Example
 
 ```typescript
 import { useSseChatAdapter } from './use-sse-chat-adapter'
 
-// Basic — tableIdForDocumentType defaults to the lib-baked map
-const chatState = useSseChatAdapter()
-
-// With custom document type registry (per-tenant override)
-const chatState = useSseChatAdapter({
-  tableIdForDocumentType: (docType) =>
-    myTenantRegistry[docType] ?? null,
-})
-
-// Consume the returned UnifiedChatState
-const { messages, sendMessage, isStreaming, streamingPhase } = chatState
+function GuidePanel() {
+  const chat = useSseChatAdapter(
+    { tableIdForDocumentType: myTenantLookup },
+    { active: true }
+  )
+
+  return (
+    <ChatSurface
+      messages={chat.messages}
+      onSend={(text) => chat.sendMessage(text)}
+      streamingPhase={chat.streamingPhase}
+    />
+  )
+}
 ```
 
-> **Note:** `source` is read automatically from `ChatRuntimeContext` — no parameter needed. It is optional: an empty `source` falls back to a stable constant (`DEFAULT_CHAT_SOURCE`) for the localStorage history namespace and is never sent on the wire (the hub resolves source server-side).
\ No newline at end of file
+> **Backward compatibility:** The legacy name `useEmbeddedChat` is re-exported as an alias from `./use-embedded-chat`. Internal code should import `useSseChatAdapter` directly.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/hooks/.use-unified-chat.md b/openframe-frontend-core/src/components/chat/hooks/.use-unified-chat.md
index 2a9089da9..fea300c51 100644
--- a/openframe-frontend-core/src/components/chat/hooks/.use-unified-chat.md
+++ b/openframe-frontend-core/src/components/chat/hooks/.use-unified-chat.md
@@ -1,57 +1,47 @@
-<!-- source-hash: 5f44f9c9a190ae929c177b9308e2bf01 -->
-Single public entry-point hook that dispatches chat state and actions to either the SSE/Guide or NATS/Mingo transport adapter based on the active mode, while always satisfying React's rules of hooks by keeping both adapters mounted.
+<!-- source-hash: 85b3231051f776772bf5b1a768f9b8f4 -->
+Unified entry-point hook that routes between SSE/Guide (`useSseChatAdapter`) and NATS/Mingo (`useNatsChatAdapter`) transports based on the `activeMode` flag, always calling both hooks to satisfy React rules while keeping the inactive adapter idle.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `useUnifiedChat` | Hook | Primary hook — returns a stable `UnifiedChatState` for the active transport |
-| `ChatMode` | Type | `'guide'` (SSE) or `'mingo'` (NATS) |
-| `UseUnifiedChatModes` | Interface | Per-mode config slots; each is optional |
-| `UseUnifiedChatOptions` | Interface | `{ modes, activeMode }` passed to the hook |
-
-## Architecture
-
-```mermaid
-graph TD
-    Consumer["Consumer Component"] --> UUC["useUnifiedChat"]
-    UUC --> SSE["useSseChatAdapter\n(guide mode)"]
-    UUC --> NATS["useNatsChatAdapter\n(mingo mode)"]
-    SSE -->|"active when guide"| ActiveState["UnifiedChatState\n(returned)"]
-    NATS -->|"active when mingo"| ActiveState
-    SSE -.->|"idle / buffered"| Inactive["Inactive Adapter\n(state preserved)"]
-    NATS -.->|"idle / buffered"| Inactive
-```
+- **`ChatMode`** — `'guide' | 'mingo'` discriminator selecting the active transport
+- **`UseUnifiedChatModes`** — per-mode config slots; each is optional so single-mode consumers only populate what they need
+- **`UseUnifiedChatOptions`** — full hook config: `modes`, `activeMode`, and optional `mingoStateOverride` for host-managed Mingo state that survives panel unmounts
+- **`useUnifiedChat(options)`** — the exported hook; returns a stable `UnifiedChatState` with forwarded actions for messaging, dialog management, approvals, and token usage
 
 ## Usage Example
 
 ```typescript
 // Guide-only consumer
-const chat = useUnifiedChat({
+const chatState = useUnifiedChat({
   activeMode: 'guide',
   modes: {
     guide: { /* UseSseChatAdapterOptions */ },
   },
 })
 
-// Dual-mode consumer (mode toggle lives in the shell component)
-const chat = useUnifiedChat({
+// Dual-mode consumer (user toggles between guide and mingo)
+const chatState = useUnifiedChat({
   activeMode: currentMode, // 'guide' | 'mingo'
   modes: {
     guide: {},
     mingo: {
-      dialogId: 'dialog-abc',
-      getNatsWsUrl: () => 'wss://nats.example.com',
-      publishUserMessage: async (msg) => publishToNats(msg),
+      dialogId: activeDialogId,
+      getNatsWsUrl: (token) => `wss://nats.example.com?token=${token}`,
+      publishUserMessage: async (msg) => await api.publish(msg),
     },
   },
 })
 
-chat.sendMessage('How do I reset a password?')
+// Host-owned Mingo state (persists across panel unmounts)
+const chatState = useUnifiedChat({
+  activeMode: 'mingo',
+  modes: { guide: {} }, // no modes.mingo — internal NATS adapter stays idle
+  mingoStateOverride: storeBackedMingoState,
+})
 ```
 
-## Key Behaviours
+## Notes
 
-- **Both adapters always mount** — inactive adapter holds its message buffer, so flipping `activeMode` restores the user to exactly where they left off in each conversation.
-- **Disabled fallback** — if a mode's config slot is `undefined`, a stable no-op default is injected (ref-stabilised for NATS, constant for SSE) to prevent hook churn.
-- **Stable return identity** — all callbacks are `useCallback`-wrapped and the final object is `useMemo`-stabilised; consumers receive a referentially stable `UnifiedChatState` on every render.
\ No newline at end of file
+- Inactive adapter retains its local message buffer — flipping `activeMode` restores the user to exactly where they left off with no data loss
+- `mingoStateOverride` is the seam for hosts that own their Mingo state in an external store or cache
+- All returned action callbacks are individually `useCallback`-stabilised; the final object is `useMemo`-ed to prevent spurious downstream re-renders
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/types/.chat.types.md b/openframe-frontend-core/src/components/chat/types/.chat.types.md
index 6147eb540..1901238f9 100644
--- a/openframe-frontend-core/src/components/chat/types/.chat.types.md
+++ b/openframe-frontend-core/src/components/chat/types/.chat.types.md
@@ -1,23 +1,23 @@
-<!-- source-hash: 38493d239449552957a80bb746221c21 -->
-Defines core constants, enums, types, and utility functions for the Flamingo chat system, covering chat participants, message roles, connection states, and SSE wire shapes.
+<!-- source-hash: 77e51952e56dd12de580ec264a6a3586 -->
+Defines core constants, enums, interfaces, and utility functions for the Flamingo chat system, covering chat types, message roles, connection states, and SSE event shapes.
 
 ## Key Components
 
-| Export | Kind | Description |
+| Export | Type | Description |
 |--------|------|-------------|
-| `CHAT_TYPE` / `ChatType` | Const + Type | Distinguishes `CLIENT_CHAT` from `ADMIN_AI_CHAT` contexts |
-| `OWNER_TYPE` / `OwnerType` | Const + Type | Message ownership: `CLIENT`, `ADMIN`, or `ASSISTANT` |
-| `MESSAGE_ROLE` / `MessageRole` | Const + Type | Conversation roles: `user`, `assistant`, `error`, `system` |
-| `ASSISTANT_TYPE` / `AssistantType` | Const + Type | AI assistants: `fae` (client-facing) and `mingo` (technician-facing) |
-| `AUTHOR_TYPE` / `AuthorType` | Const + Type | Full author roster including `user`, `admin`, `fae`, `mingo`, `system` |
-| `APPROVAL_STATUS` / `ChatApprovalStatus` | Const + Type | Approval workflow states: `pending`, `approved`, `rejected` |
-| `CONNECTION_STATUS` / `ConnectionStatus` | Const + Type | WebSocket/SSE lifecycle states |
-| `MessageOwner` | Interface | Identifies who owns a message, with optional user profile fields |
-| `buildChatRefKey` | Function | Builds canonical `docType:externalId` keys for `chatRefs` map lookups |
-| `isStructuredContent` | Function | Type guard — checks if `MessageContent` is a `MessageSegment[]` |
-| `normalizeContent` | Function | Coerces string or segment array to a uniform `MessageSegment[]` |
-| `TextEventData` / `ToolExecutionEventData` / `SSEEventData` | Interfaces + Union | Wire shapes for SSE streaming events |
-| `QuickAction` | Interface | Shape for quick-reply chip components (`id` + `text`) |
+| `CHAT_TYPE` | Const | Chat contexts: `CLIENT_CHAT`, `ADMIN_AI_CHAT` |
+| `OWNER_TYPE` | Const | Message ownership: `CLIENT`, `ADMIN`, `ASSISTANT` |
+| `MESSAGE_ROLE` | Const | Conversation roles: `user`, `assistant`, `error`, `system` |
+| `ASSISTANT_TYPE` | Const | AI assistants: `fae` (client-facing) and `mingo` (technician) |
+| `AUTHOR_TYPE` | Const | Extended authorship including `user`, `admin`, `fae`, `mingo`, `system` |
+| `APPROVAL_STATUS` | Const | Workflow states: `pending`, `approved`, `rejected` |
+| `CONNECTION_STATUS` | Const | WebSocket/SSE lifecycle: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
+| `MessageOwner` | Interface | Owner identity with optional user profile and avatar resolution |
+| `buildChatRefKey` | Function | Constructs canonical `docType:externalId` lookup keys for inline card markers |
+| `isStructuredContent` | Function | Type guard distinguishing segment arrays from plain strings |
+| `normalizeContent` | Function | Normalizes `string \| MessageSegment[]` into a uniform segment array |
+| `SSEEventData` | Union type | Wire shapes for `TEXT` and tool execution SSE events |
+| `QuickAction` | Interface | Quick-reply chip shape with `id` and `text` |
 
 ## Usage Example
 
@@ -26,31 +26,54 @@ import {
   CHAT_TYPE,
   MESSAGE_ROLE,
   ASSISTANT_TYPE,
-  APPROVAL_STATUS,
   CONNECTION_STATUS,
+  APPROVAL_STATUS,
   buildChatRefKey,
   isStructuredContent,
   normalizeContent,
+  type ChatType,
+  type MessageOwner,
+  type SSEEventData,
 } from './chat.types'
 
-// Route to the correct AI assistant based on chat context
-const assistant =
-  chatType === CHAT_TYPE.CLIENT ? ASSISTANT_TYPE.FAE : ASSISTANT_TYPE.MINGO
+// Distinguish chat context
+const chatType: ChatType = CHAT_TYPE.ADMIN // 'ADMIN_AI_CHAT'
+
+// Identify the active AI assistant
+const assistant = ASSISTANT_TYPE.MINGO // technician-facing
 
-// Build a chatRefs lookup key matching inline [card://ticket:42] markers
-const refKey = buildChatRefKey('ticket', '42') // → "ticket:42"
+// Build a card reference key for inline rendering
+const refKey = buildChatRefKey('ticket', 'TKT-1042') // 'ticket:TKT-1042'
 
-// Normalize incoming content before rendering
-const segments = normalizeContent(message.content)
-// → always MessageSegment[], safe to iterate
+// Normalize incoming message content to segments
+const segments = normalizeContent('Hello, how can I help?')
+// → [{ type: 'text', text: 'Hello, how can I help?' }]
 
-// Check approval before displaying an action
-if (approval === APPROVAL_STATUS.PENDING) {
-  showApprovalBanner()
+// Type-guard for structured content
+if (isStructuredContent(segments)) {
+  console.log('Segment count:', segments.length)
 }
 
-// Handle SSE connection lifecycle
-if (status === CONNECTION_STATUS.RECONNECTING) {
-  showReconnectingSpinner()
+// Handle SSE events from the AI stream
+function handleSSE(event: SSEEventData) {
+  if (event.type === 'TEXT') {
+    console.log('Stream text:', event.text)
+  } else if (event.type === 'EXECUTED_TOOL') {
+    console.log(`Tool "${event.toolFunction}" success:`, event.success)
+  }
+}
+
+// Check connection lifecycle
+const status = CONNECTION_STATUS.RECONNECTING
+
+// Build a MessageOwner for an authenticated user
+const owner: MessageOwner = {
+  type: 'CLIENT',
+  userId: 'usr_abc123',
+  user: {
+    id: 'usr_abc123',
+    firstName: 'Jane',
+    image: { imageUrl: '/avatars/jane.png' },
+  },
 }
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/types/.component.types.md b/openframe-frontend-core/src/components/chat/types/.component.types.md
index 4f13d3fb3..545f94f39 100644
--- a/openframe-frontend-core/src/components/chat/types/.component.types.md
+++ b/openframe-frontend-core/src/components/chat/types/.component.types.md
@@ -1,60 +1,51 @@
-<!-- source-hash: 141d208f153f42ac4e3acd48496b0621 -->
-Defines all TypeScript prop and ref types for the chat UI component library, covering containers, headers, messages, message lists, inputs, and slash command affordances.
+<!-- source-hash: e8dab3cd93e364cef98a07b0d74e0a05 -->
+Defines all TypeScript prop and configuration types used by the Flamingo chat UI component library, covering containers, headers, messages, inputs, and slash commands.
 
 ## Key Components
 
-### Core Component Props
-- **`ChatContainerProps`** — Extends `HTMLAttributes<HTMLDivElement>` for the root chat wrapper
-- **`ChatHeaderProps`** — Full header configuration including user info, connection status, ticket info, `fullWidth`, and `bare` display modes
-- **`ChatMessageEnhancedProps`** — Per-message props including role, content (`string | MessageSegment[]`), entity card rendering, and markdown link routing
-- **`ChatMessageListProps`** — Message list with infinite scroll, approval handling, avatar display, and forwarded `renderEntityCard`/`NavLinkAnchor` props
-- **`ChatMessageListRef`** — Imperative handle exposing `scrollToBottom`, `getScrollPosition`, and `setScrollPosition`
-- **`ConnectionIndicatorProps`** — Wraps `ConnectionStatus` for the connection state badge
-
-### Slash Commands
-- **`SlashCommandsProp`** — Consumer-supplied `fetchCommands` callback and optional `resolveSourceIcon` for autocomplete
-- **`SlashCommandSummary`** — Server-resolved command descriptor with `actions`, `argumentHint`, `label`, `displayOrder`, and `iconName`
-- **`SlashCommandActionId`** — String-literal union: `'browse' | 'search' | 'find' | 'display'`
-- **`SlashCommandSourceMeta`** — Icon component + label pair returned by `resolveSourceIcon`
-
-### Routing
-- **`NavLinkAnchorComponent`** — Host-supplied anchor component for markdown links, enabling unified routing (soft same-origin nav, new-tab cross-origin)
+- **`NavLinkAnchorComponent`** — Component type for custom anchor rendering in markdown links, allowing host apps to inject their own routing logic
+- **`ChatContainerProps`** — Base div wrapper props for the chat layout
+- **`ChatHeaderProps`** — Full header configuration including user info, connection status, ticket metadata, and layout modifiers (`fullWidth`, `bare`)
+- **`ChatHeaderTicketInfo`** — Ticket display metadata (title, status, lifecycle color/kind)
+- **`ConnectionIndicatorProps`** — Connection status indicator props
+- **`ChatMessageEnhancedProps`** — Rich message row props supporting roles, content segments, approval callbacks, inline entity cards (`chatRefs`, `renderEntityCard`), and custom anchor routing (`NavLinkAnchor`)
+- **`ChatMessageListProps`** — Scrollable message list props with infinite scroll, avatar control, approval forwarding, and full-width layout
+- **`ChatMessageListRef`** — Imperative ref handle for programmatic scroll control
+- **`SlashCommandSummary`** — Autocomplete command descriptor including actions, icons, labels, and display ordering
+- **`SlashCommandsProp`** — Slash command integration contract (`fetchCommands`, `resolveSourceIcon`)
+- **`SlashCommandActionId`** — `'browse' | 'search' | 'find' | 'display'` action dispatch union
 
 ## Usage Example
 
 ```typescript
 import type {
-  ChatMessageListProps,
   ChatHeaderProps,
+  ChatMessageEnhancedProps,
   NavLinkAnchorComponent,
-  SlashCommandsProp,
+  SlashCommandSummary,
 } from './component.types'
 
-// Host-supplied anchor delegates routing to app router
-const NavLinkAnchor: NavLinkAnchorComponent = ({ href, className, children }) => (
+const MyAnchor: NavLinkAnchorComponent = ({ href, className, children }) => (
   <a href={href} className={className}>{children}</a>
 )
 
 const headerProps: ChatHeaderProps = {
   userName: 'Mingo AI',
   connectionStatus: 'connected',
-  fullWidth: true,   // fills narrow side panel
-  bare: true,        // no card chrome inside Drawer
-}
-
-const listProps: ChatMessageListProps = {
-  messages,
   fullWidth: true,
-  hasNextPage: true,
-  isFetchingNextPage: false,
-  onLoadMore: fetchOlderMessages,
-  renderEntityCard: (ref) => <EntityCard reference={ref} />,
-  NavLinkAnchor,
+  bare: false,
+  ticketInfo: {
+    title: 'Ticket #1042',
+    statusName: 'In Progress',
+    statusColor: '#FFC008',
+    statusKind: 'active',
+  },
 }
 
-const slashCommands: SlashCommandsProp = {
-  fetchCommands: async (prefix, signal) =>
-    fetch(`/api/docs/commands?q=${prefix}`, { signal }).then(r => r.json()),
-  resolveSourceIcon: (sourceId) => iconRegistry[sourceId],
+const messageProps: ChatMessageEnhancedProps = {
+  role: 'assistant',
+  content: 'How can I help?',
+  NavLinkAnchor: MyAnchor,
+  renderEntityCard: (ref) => <EntityCard ref={ref} />,
 }
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/types/.unified-chat-state.types.md b/openframe-frontend-core/src/components/chat/types/.unified-chat-state.types.md
index 90311aff9..bcd89d748 100644
--- a/openframe-frontend-core/src/components/chat/types/.unified-chat-state.types.md
+++ b/openframe-frontend-core/src/components/chat/types/.unified-chat-state.types.md
@@ -1,41 +1,47 @@
-<!-- source-hash: 5419513463f6ad2b09f3c013740a3568 -->
-Shared TypeScript contract defining the unified state shape and supporting types that all chat transport hooks (SSE and NATS) must satisfy, enabling transport-agnostic consumption by UI components.
+<!-- source-hash: f889a7ec32c0a046d8e463b4d4f2d7c0 -->
+Defines the unified contract (`UnifiedChatState`) that both SSE (Guide mode) and NATS (Mingo mode) transport hooks must satisfy, enabling consumers to work against a single interface regardless of the underlying transport.
 
 ## Key Components
 
 | Export | Kind | Description |
 |--------|------|-------------|
-| `StreamingPhase` | Type | `'idle' \| 'thinking' \| 'streaming'` — granular in-flight status for the streaming indicator UI |
-| `UnifiedUsageBreakdown` | Interface | SSE-only per-turn LLM telemetry (Haiku pipeline costs + routed answer metadata); always `null` in Mingo/NATS mode |
-| `UnifiedChatMessage` | Interface | Transport-agnostic message shape; SSE-only fields (`sources`, `chatRefs`) are optional, Mingo-safe |
-| `UnifiedSendMessageOptions` | Interface | Options for `sendMessage` — `hidden` (suppress UI render) and `attachments` (SSE-only image uploads) |
-| `UnifiedChatState` | Interface | The primary contract: full return shape every transport hook must implement, covering messages, actions, loading state, and SSE-only LLM metadata |
+| `UnifiedChatState` | `interface` | Primary return shape all transport hooks must implement |
+| `UnifiedChatMessage` | `interface` | Generic message shape shared across Guide and Mingo modes |
+| `UnifiedSendMessageOptions` | `interface` | Options passed to `sendMessage` (attachments, hidden flag) |
+| `UnifiedUsageBreakdown` | `interface` | SSE-only per-call token telemetry (Haiku pipeline costs) |
+| `DialogTokenUsage` | `interface` | Mingo backend token usage snapshot per active dialog |
+| `ChatConnectionState` | `type` | Transport-level connection status: `'connected' \| 'connecting' \| 'disconnected'` |
+| `StreamingPhase` | `type` | Granular streaming status: `'idle' \| 'thinking' \| 'streaming'` |
 
 ## Usage Example
 
 ```typescript
-// Consumer component — works identically for SSE (Guide) or NATS (Mingo)
-import type { UnifiedChatState, UnifiedSendMessageOptions } from './unified-chat-state.types'
+import type {
+  UnifiedChatState,
+  UnifiedChatMessage,
+  StreamingPhase,
+} from './unified-chat-state.types'
 
+// Consuming the unified contract — works for both SSE and NATS transports
 function ChatShell({ chat }: { chat: UnifiedChatState }) {
-  const { messages, isLoading, streamingPhase, sendMessage, stopMessage } = chat
+  const { messages, isLoading, streamingPhase, sendMessage } = chat
 
-  async function handleSubmit(text: string, attachments?: ChatAttachment[]) {
-    const options: UnifiedSendMessageOptions = { attachments }
-    await sendMessage(text, options)
+  const statusLabel: Record<StreamingPhase, string> = {
+    idle: '',
+    thinking: 'Thinking...',
+    streaming: 'Streaming...',
   }
 
-  return (
-    <>
-      {/* SSE-only metadata — safely null in Mingo mode */}
-      {chat.currentModelLabel && <ModelDisplay label={chat.currentModelLabel} />}
-      {streamingPhase === 'thinking' && <span>Thinking...</span>}
-      {streamingPhase === 'streaming' && <span>Streaming...</span>}
-      <MessageList messages={messages.filter(m => !m.hidden)} />
-      <ChatInput onSubmit={handleSubmit} disabled={isLoading} onStop={stopMessage} />
-    </>
-  )
+  return {
+    status: statusLabel[streamingPhase],
+    messageCount: messages.length,
+    // SSE-only fields gracefully degrade to null in Mingo mode
+    modelLabel: chat.currentModelLabel ?? 'Unknown model',
+    cacheHit: chat.currentCacheHitRatePct ?? 0,
+    onSubmit: (text: string) =>
+      sendMessage(text, { hidden: false, attachments: [] }),
+  }
 }
 ```
 
-> **Transport isolation:** `currentProvider`, `currentModelLabel`, `currentUsageBreakdown`, and related token fields are `null` in Mingo/NATS mode. Always guard with a null check before rendering LLM metadata.
\ No newline at end of file
+> **Transport transparency:** Fields exclusive to one transport (e.g. `currentProvider`, `currentUsageBreakdown` for SSE; `dialogs`, `activeDialogId` for Mingo) are typed as `null` or `undefined` in the off-mode — consumers never need to branch on `mode` directly.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/utils/.execute-navigation.md b/openframe-frontend-core/src/components/chat/utils/.execute-navigation.md
new file mode 100644
index 000000000..bb0947fcd
--- /dev/null
+++ b/openframe-frontend-core/src/components/chat/utils/.execute-navigation.md
@@ -0,0 +1,63 @@
+<!-- source-hash: 372bccd2d9bf52ce138aef0ee5708d07 -->
+Unified navigation execution primitive that encodes all navigation decisions — new-tab vs. same-tab, internal vs. external, embed vs. host, and runtime/router/window fallback chain — into a single execution point for the entire library.
+
+## Key Components
+
+### Interfaces
+
+- **`NavClickEvent`** — Minimal structural mouse-event surface, allowing chip buttons and tiles to call navigation without casting `React.MouseEvent`
+- **`ExecuteNavigationClickArgs`** — Arguments for click-handler form, including event, runtime, href, path, targetPlatform, and optional router fallback
+- **`ExecuteNavigationImperativeArgs`** — Streamlined arguments for programmatic navigation (no event handling)
+
+### Functions
+
+- **`runNavigation`** *(internal)* — Core decision engine: resolves `computeIsNewTab`, dispatches to `runtime.navigation.openExternal`, `runtime.navigation.navigate`, `fallbackNavigate`, or `window.location.assign` in priority order
+- **`executeNavigation`** — Click-handler form; guards against modifier keys and non-primary buttons, returns `true` if it consumed the event
+- **`executeNavigationImperative`** — Programmatic form for buttons, list rows, and post-action redirects; same decision tree without event/modifier logic
+
+## Usage Example
+
+```typescript
+// Click-handler form (anchor / chip / markdown link)
+import { executeNavigation } from './execute-navigation'
+
+function handleClick(event: React.MouseEvent) {
+  executeNavigation({
+    event,
+    runtime,           // ChatRuntime | null
+    href: 'https://example.com/tickets/123',
+    path: '/tickets/123',
+    targetPlatform: 'web',
+    fallbackNavigate: router.push,  // useRouter().push
+  })
+}
+
+// Imperative form (button action / post-form redirect)
+import { executeNavigationImperative } from './execute-navigation'
+
+executeNavigationImperative({
+  runtime,
+  href: 'https://example.com/tickets/123',
+  targetPlatform: 'web',
+  fallbackNavigate: router.push,
+})
+```
+
+## Decision Tree
+
+```mermaid
+flowchart TD
+    A["Navigation Request"] --> B{"href empty?"}
+    B -->|"Yes"| C["No-op / preventDefault"]
+    B -->|"No"| D{"Click form: modifier\nor non-primary button?"}
+    D -->|"Yes"| E["Return false\n(browser native)"]
+    D -->|"No"| F{"runtime present\n& isNewTab?"}
+    F -->|"Yes"| G{"openExternal\navailable?"}
+    G -->|"Yes"| H["runtime.navigation.openExternal"]
+    G -->|"No"| I["window.open _blank"]
+    F -->|"No"| J{"runtime.navigation\n.navigate handled?"}
+    J -->|"Yes"| K["Runtime handles navigation"]
+    J -->|"No"| L{"fallbackNavigate\nprovided?"}
+    L -->|"Yes"| M["fallbackNavigate(strippedPath)"]
+    L -->|"No"| N["window.location.assign"]
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/utils/.index.md b/openframe-frontend-core/src/components/chat/utils/.index.md
index d902ea73e..2caf9f385 100644
--- a/openframe-frontend-core/src/components/chat/utils/.index.md
+++ b/openframe-frontend-core/src/components/chat/utils/.index.md
@@ -1,53 +1,54 @@
-<!-- source-hash: 85c0af6cd361347beeabcd097260378a -->
-Barrel export module that consolidates and re-exports all message processing, chat navigation, UI styling, and content utility functions for chat interfaces.
+<!-- source-hash: 50053b1e5fa2dd33b064dfeef7a34264 -->
+Barrel/index file for the `message-processing` utilities package, re-exporting all public APIs from the module's sub-files.
 
 ## Key Components
 
-| Category | Exports |
-|----------|---------|
-| **Chunk Parsing** | `parseChunkToAction`, `isControlChunk`, `isErrorChunk`, `isMetadataChunk`, `extractTextFromChunk` |
-| **Message Accumulation** | `MessageSegmentAccumulator`, `createMessageSegmentAccumulator`, `AccumulatorCallbacks` |
-| **Historical Messages** | `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` |
-| **Chat Navigation** | `handleChatNavClick`, `resolveExternalNavigation`, `decideNewTab`, `computeIsNewTab`, `buildAnchorProps` |
-| **Proxy Auth** | `getChatProxyAuth`, `setChatProxyAuth`, `clearChatProxyAuth`, `applyProxyAuth`, `chatAuthedFetch` |
-| **Attachments** | `formatChatAttachmentMarkdownForBubble`, `stripChatAttachmentMarkdown`, `buildChatAttachmentViewUrl` |
-| **UI / Styling** | `chatChipClass`, compact card class constants (`COMPACT_CARD_*`), `getStatusColorScheme` |
-| **Icon Registry** | `ICON_REGISTRY`, `getIconComponent`, `normalizeIconKey`, `getDynamicIcon` |
-| **Source Utilities** | `getSourceIconName`, `getSourceLabel`, `resolveSourceRowCTA`, `resolveSourceIcon` |
-| **Slash Commands** | `parseWireCommandOverride`, `sanitizeTitleForChat`, `buildDiscussAddendum` |
+**Chunk Processing**
+- `parseChunkToAction`, `isControlChunk`, `isErrorChunk`, `isMetadataChunk`, `extractTextFromChunk` — stream chunk classification and parsing
+
+**Message Accumulation**
+- `MessageSegmentAccumulator`, `createMessageSegmentAccumulator` — stateful accumulator for assembling streaming message segments
+
+**Historical Messages**
+- `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` — replay and error extraction from past messages
+
+**Navigation & Routing**
+- `executeNavigation`, `executeNavigationImperative` — unified navigation primitive handling new-tab/same-tab, internal/external, embed/host, and fallback chains
+- `handleChatNavClick`, `computeIsNewTab`, `buildAnchorProps`, `decideNewTab` — click-event helpers and anchor attribute builders
+
+**Chat Proxy Auth**
+- `getChatProxyAuth`, `setChatProxyAuth`, `clearChatProxyAuth`, `applyProxyAuth`, `chatAuthedFetch` — localStorage adapter and authenticated fetch wrapper
+
+**Content Helpers**
+- `flattenAssistantContent`, `parseScrollAnchor`, `buildAutoContinuationDirective` — pure content transformation utilities
+
+**Slash Commands**
+- `parseWireCommandOverride`, `sanitizeTitleForChat`, `buildDiscussAddendum` — command dispatch utilities
+
+**Attachments**
+- `formatChatAttachmentMarkdownForBubble`, `stripChatAttachmentMarkdown`, `buildChatAttachmentViewUrl` — chat attachment markdown formatting and parsing
+
+**UI Primitives**
+- `ICON_REGISTRY`, `getIconComponent`, `normalizeIconKey` — single source of truth for icon-name → React component lookup
+- `COMPACT_CARD_*` constants, `safeHref` — compact card CSS class tokens and safe URL guard
 
 ## Usage Example
 
 ```typescript
 import {
+  executeNavigation,
   parseChunkToAction,
-  createMessageSegmentAccumulator,
-  handleChatNavClick,
   getChatProxyAuth,
-  getIconComponent,
-  formatChatAttachmentMarkdownForBubble,
-  decideNewTab,
-  getStatusColorScheme,
-} from '@flamingo/chat-utils'
-
-// Parse a streaming chunk from the AI response
-const action = parseChunkToAction(rawChunk)
-
-// Accumulate streamed message segments
-const accumulator = createMessageSegmentAccumulator({
-  onSegmentComplete: (segment) => console.log('Segment:', segment),
-})
-
-// Resolve navigation target for a chat link
-const { openInNewTab } = decideNewTab({
-  href: 'https://app.example.com/tickets/123',
-  surface: 'chat-bubble',
-  mode: 'web',
-})
-
-// Look up a registered icon by kebab-case key
-const Icon = getIconComponent('clickup')
-
-// Apply agent status color scheme to UI
-const colors = getStatusColorScheme('running')
+  MessageSegmentAccumulator,
+} from '@flamingo/message-processing'
+
+// Navigate with unified primitive
+executeNavigation({ href: '/tickets/123', event: clickEvent })
+
+// Parse a streaming chunk
+const action = parseChunkToAction(chunk)
+
+// Accumulate streamed segments
+const accumulator = new MessageSegmentAccumulator(callbacks)
+accumulator.push(chunk)
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/utils/.nav-click-handler.md b/openframe-frontend-core/src/components/chat/utils/.nav-click-handler.md
index ea2d42613..e5fb14e5c 100644
--- a/openframe-frontend-core/src/components/chat/utils/.nav-click-handler.md
+++ b/openframe-frontend-core/src/components/chat/utils/.nav-click-handler.md
@@ -1,47 +1,35 @@
-<!-- source-hash: 52e6bfa6e916758ef4a95f83d0eb97da -->
-Unified click-handler for chat-rendered navigation links. Centralizes the routing decision logic (same-tab vs. new-tab, embed vs. host, modifier-key pass-through) so callers like chip blocks, entity-card wrappers, and markdown anchor wrappers share a single implementation.
+<!-- source-hash: dd19b1c249728537a01b0a89f3b94541 -->
+Thin compatibility wrapper that forwards chat navigation clicks to the unified `executeNavigation` primitive, preserving the existing call signature used by chip blocks, `<ChatCardNavWrap>`, and `<NavLinkAnchorViaRuntime>`.
 
 ## Key Components
 
 ### `ChatNavClickInput`
-Input interface describing the navigation target:
-- `href` — destination URL (required)
-- `path` — optional internal route path
+Input shape describing the navigation target:
+- `href` — raw anchor href
+- `path` — optional resolved internal path
 - `targetPlatform` — optional platform hint for routing decisions
 
-### `NavClickEvent`
-Structural mouse-event interface (subset of `React.MouseEvent`) that keeps the handler callable from non-anchor surfaces without requiring a cast.
-
-### `handleChatNavClick(e, runtime, input): boolean`
-The core export. Processes a click event against a `ChatRuntime` and returns:
-- `true` — handler took action and called `preventDefault()`
-- `false` — modifier-click or non-primary button; browser default applies
-
-**Routing rules in priority order:**
-1. Empty `href` → `preventDefault` + no-op
-2. Non-primary button or any modifier key (`meta`, `ctrl`, `shift`, `alt`) → pass through to browser
-3. New-tab decision via `computeIsNewTab` → `runtime.navigation.openExternal` or `window.open`
-4. Same-tab → `runtime.navigation.navigate?.()` → fallback to `window.location.assign`
+### `handleChatNavClick(e, runtime, input, fallbackNavigate?)`
+Delegates entirely to `executeNavigation`. Returns `boolean` indicating whether the event was handled. The `fallbackNavigate` parameter accepts `useRouter().push` for same-origin soft navigation when the runtime does not wire `navigation.navigate`.
 
 ## Usage Example
 
 ```typescript
 import { handleChatNavClick } from './nav-click-handler'
-import { useChatRuntime } from '../../../contexts/chat-runtime-context'
-
-function NavChip({ href, path, targetPlatform }) {
-  const runtime = useChatRuntime()
-
-  return (
-    <button
-      onClick={(e) =>
-        handleChatNavClick(e, runtime, { href, path, targetPlatform })
-      }
-    >
-      {label}
-    </button>
+import { useRouter } from 'next/navigation'
+
+const router = useRouter()
+
+function onAnchorClick(e: React.MouseEvent<HTMLAnchorElement>) {
+  handleChatNavClick(
+    e,
+    runtime,
+    { href: '/dashboard', path: '/dashboard', targetPlatform: null },
+    router.push,
   )
 }
 ```
 
-> **Note:** Pass-through (`return false`) preserves native `<a>` semantics for modifier-clicks (e.g., Cmd+Click opens a new tab), so wrapping anchor elements still behave correctly without extra logic in the caller.
\ No newline at end of file
+## Notes
+
+> **Deprecated.** New code should call `executeNavigation` directly from `execute-navigation.ts`. This file exists solely for backward compatibility — the full decision tree (empty-href no-op, modifier/non-primary passthrough, new-tab via `openExternal`/`window.open`, same-tab via `navigate` → fallback → `window.location`) lives in `executeNavigation`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/utils/.process-historical-messages.md b/openframe-frontend-core/src/components/chat/utils/.process-historical-messages.md
index 33e721e16..15ee391b9 100644
--- a/openframe-frontend-core/src/components/chat/utils/.process-historical-messages.md
+++ b/openframe-frontend-core/src/components/chat/utils/.process-historical-messages.md
@@ -1,57 +1,44 @@
-<!-- source-hash: abb044a6e8d133979dfd31cca4044960 -->
-Transforms raw `HistoricalMessage` arrays from GraphQL/API responses into display-ready `ProcessedMessage` objects, handling message grouping, approval state resolution, and tool call rendering.
+<!-- source-hash: 8e807e8531e842395c409ccea50b76b5 -->
+Converts raw `HistoricalMessage` arrays from GraphQL/API responses into display-ready `ProcessedMessage` objects, handling message grouping, assistant segment accumulation, and approval request lifecycle tracking.
 
 ## Key Components
 
 ### `processHistoricalMessages(messages, options)`
-Main export. Iterates over historical messages, groups consecutive assistant turns into single display messages, and returns a `ProcessHistoricalMessagesResult` containing:
-- `messages` — fully rendered `ProcessedMessage[]` ready for UI consumption
-- `escalatedApprovals` — approvals filtered out by `displayApprovalTypes` that the consumer handles separately (e.g., admin-side approvals in a client-facing view)
+Main export. Iterates over historical messages, groups consecutive assistant messages into batched segments via `MessageSegmentAccumulator`, and flushes them at user-message boundaries or end-of-array. Returns both the processed message list and a map of escalated approvals filtered out by `displayApprovalTypes`.
 
-### `processMessageData(data, accumulator, approvalStatuses, options, escalatedApprovals)`
-Internal dispatcher. Routes each `MessageData` item by `MESSAGE_TYPE` to the correct accumulator method:
-
-| Type | Action |
-|---|---|
-| `TEXT` | `appendText` |
-| `THINKING` | `appendThinking` |
-| `EXECUTING_TOOL` / `EXECUTED_TOOL` | `addToolExecution` |
-| `APPROVAL_REQUEST` | Batch or legacy approval card, or escalate |
-| `APPROVAL_RESULT` | Resolves pending/escalated approvals |
+### `ProcessHistoricalMessagesResult`
+Return type containing:
+- `messages` — `ProcessedMessage[]` ready for rendering
+- `escalatedApprovals` — `Map` of approval requests excluded from the current chat view (e.g. admin-only approvals surfaced to a different UI layer)
 
-### `flushAssistantMessage()` *(internal closure)*
-Drains the segment accumulator into a single assistant `ProcessedMessage`. Uses the **last** message ID in the group as the React key for stable pagination behavior.
+### `processMessageData(data, accumulator, approvalStatuses, options, escalatedApprovals)`
+Private dispatcher that routes each `MessageData` item by type:
+- `TEXT` / `THINKING` → appends to accumulator
+- `EXECUTING_TOOL` / `EXECUTED_TOOL` → adds tool execution segments
+- `APPROVAL_REQUEST` → resolves batch vs. single, pending vs. resolved, and honors `batchApprovalsEnabled` flag
+- `APPROVAL_RESULT` → materializes deferred approvals stored in `escalatedApprovals`
 
-### `ProcessHistoricalMessagesResult`
-```typescript
-export interface ProcessHistoricalMessagesResult {
-  messages: ProcessedMessage[]
-  escalatedApprovals: Map<
-    string,
-    { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
-  >
-}
-```
+### Helper Functions
+- `getOwnerDisplayName(owner)` — resolves display name for admin or client owners
+- `getOwnerAvatar(owner)` — extracts optional avatar URL from owner profile
+- `pushStandaloneMessages(...)` — handles `SYSTEM` type messages as standalone entries
 
 ## Usage Example
 
 ```typescript
 import { processHistoricalMessages } from './process-historical-messages'
 
-const { messages, escalatedApprovals } = processHistoricalMessages(
-  rawMessages,
-  {
-    assistantName: 'Fae',
-    assistantType: 'fae',
-    approvalStatuses: { 'req-123': 'approved' },
-    displayApprovalTypes: ['CLIENT'],
-    batchApprovalsEnabled: true,
-    onApprove: (id) => handleApprove(id),
-    onReject: (id) => handleReject(id),
-  }
-)
-
-// escalatedApprovals contains ADMIN-type approvals for separate rendering
-```
-
-> **Note on `batchApprovalsEnabled`:** Defaults to `true`. Pass `false` to unfold batch approval requests into individual legacy approval cards — useful when the consuming UI has not yet adopted the batch approval component.
\ No newline at end of file
+const { messages, escalatedApprovals } = processHistoricalMessages(rawMessages, {
+  assistantName: 'Fae',
+  assistantType: 'fae',
+  assistantAvatar: '/avatars/fae.png',
+  approvalStatuses: { 'req-123': 'approved' },
+  displayApprovalTypes: ['CLIENT'],
+  batchApprovalsEnabled: true,
+  onApprove: (id) => handleApprove(id),
+  onReject: (id) => handleReject(id),
+})
+
+// escalatedApprovals contains admin-level requests excluded from CLIENT view
+console.log(escalatedApprovals.get('req-456')?.approvalType) // 'ADMIN'
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/chat/utils/.source-row-cta.md b/openframe-frontend-core/src/components/chat/utils/.source-row-cta.md
index 0d607fde6..b1b4eba61 100644
--- a/openframe-frontend-core/src/components/chat/utils/.source-row-cta.md
+++ b/openframe-frontend-core/src/components/chat/utils/.source-row-cta.md
@@ -1,54 +1,48 @@
-<!-- source-hash: e259d6e958fa331a13973e9d2749ffbc -->
-Resolves the "what does clicking this row do?" CTA contract for source rows across chat-adjacent surfaces (chips, inline cards, search results). Pure function — no DOM, no fetch, no side effects.
+<!-- source-hash: 6609067763f343156daece1351c3881a -->
+Resolves the click-action contract (icon, href, targetPlatform, askability, chatRef) for source rows across chat-adjacent surfaces like chips, inline cards, and search results.
 
 ## Key Components
 
-### Interfaces
+**`resolveSourceRowCTA(row, ctx)`** — Core pure function. Accepts a `SourceRowInput` and `SourceRowContext`, returns a `SourceRowCTA` with resolved icon, href, targetPlatform, askable flag, and chatRef.
 
-| Interface | Purpose |
-|---|---|
-| `SourceRowInput` | Row data — `sourceRepo`, `documentType`, `id`, `title`, `externalUrl`, `path` |
-| `SourceRowContext` | Host-injected context — `baseRoute`, `chipBasePlatform`, `currentPlatform`, `tableIdForDocumentType` |
-| `SourceRowCTA` | Resolved contract — `icon`, `iconLabel`, `href`, `targetPlatform`, `askable`, `chatRef` |
+**`sourceRowCtxFromRuntime(runtime, surface)`** — Factory that builds a `SourceRowContext` from a `ChatRuntime` instance and surface config, centralizing wiring of `currentPlatform`, `composeContentUrl`, and `docPlatformTargets`.
 
-### Exports
+**`SourceRowInput`** — Row data shape: `sourceRepo`, `documentType`, `id`, `title`, `externalUrl`, `targetPlatform`, `path`.
 
-- **`resolveSourceRowCTA(row, ctx)`** — Primary resolver. Returns the full CTA contract for a row. Handles icon resolution, URL safety (`safeHref`), path sanitization, and Ask drill-in viability.
-- **`resolveSourceIcon(input, ctx)`** — Lightweight helper for surfaces that only need the icon + label (inline cards, search dropdown). Accepts `{ sourceRepo, documentType }` or a bare `string` (treated as `documentType`) for backward compatibility.
+**`SourceRowContext`** — Host-injected dependencies: `baseRoute`, `chipBasePlatform`, `currentPlatform`, `tableIdForDocumentType`, `composeContentUrl`, `docPlatformTargets`.
 
-### Internal Helpers
+**`SourceRowCTA`** — Output contract: `icon`, `iconLabel`, `href` (safe, nullable), `targetPlatform`, `askable`, `chatRef`.
 
-- **`sanitizePath(path)`** — Strips non-alphanumeric characters except `/`, `-`, `.`, `_` to prevent path traversal or query injection.
-- **`shouldFallbackToPathNav(row)`** — Limits in-app path fallback to `markdown` and `data_room_doc` document types only.
-- **`pickSourceIcon(sourceRepo, documentType)`** — Maps `sourceRepo` → icon name → React component via `SOURCE_ICON_NAMES` + `ICON_REGISTRY`; falls back to `FileText`.
+**`DOC_TABLE_TYPES`** — Constant tuple `['markdown', 'data_room_doc']` identifying doc-table rows that use path-based navigation instead of `externalUrl`.
 
 ## Usage Example
 
 ```typescript
-import { resolveSourceRowCTA, resolveSourceIcon } from './source-row-cta'
+import { resolveSourceRowCTA, sourceRowCtxFromRuntime } from './source-row-cta'
+
+const ctx = sourceRowCtxFromRuntime(runtime, {
+  baseRoute: '/knowledge-base',
+  chipBasePlatform: 'flamingo',
+})
 
-// Full CTA resolution for a chip or search result
 const cta = resolveSourceRowCTA(
   {
     sourceRepo: 'blog-posts',
     documentType: 'blog_post',
-    id: 'post-42',
-    title: 'Series A Playbook',
-    externalUrl: 'https://example.com/posts/42',
-    targetPlatform: 'hub',
-  },
-  {
-    baseRoute: '/knowledge-base',
-    currentPlatform: 'hub',
-    tableIdForDocumentType: (type) => type === 'blog_post' ? 'blog-posts' : null,
+    id: 'abc-123',
+    title: 'Getting Started',
+    externalUrl: 'https://example.com/posts/abc-123',
   },
+  ctx,
 )
-// cta.href       → 'https://example.com/posts/42'  (safeHref-validated)
-// cta.askable   → true
-// cta.chatRef   → { type: 'blog_post', sourceRepo: 'blog-posts', id: 'post-42', ... }
 
-// Icon-only resolution for an inline card tracking strip
-const { Icon, label } = resolveSourceIcon({ documentType: 'cap_table' }, { tableIdForDocumentType })
+// cta.href      → sanitized destination URL
+// cta.icon      → React icon component
+// cta.askable   → true (has id + documentType)
+// cta.chatRef   → pre-built ChatRef for Ask handler
 ```
 
-> `href` is always `safeHref()`-sanitized — a hostile RAG row cannot inject `javascript:` or `data:` URIs into the DOM. Ask drill-in (`askable`) requires both a non-empty `id` and a `documentType`.
\ No newline at end of file
+**href resolution priority:**
+1. Doc-table row (no `externalUrl`) → `docPlatformTargets` → `chipBasePlatform` → `baseRoute` → `null`
+2. Entity row with `composeContentUrl` + `externalUrl` → unified content-href seam
+3. Entity row without composer → `externalUrl` verbatim (legacy)
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.captions-url.md b/openframe-frontend-core/src/components/features/.captions-url.md
new file mode 100644
index 000000000..0550324c1
--- /dev/null
+++ b/openframe-frontend-core/src/components/features/.captions-url.md
@@ -0,0 +1,28 @@
+<!-- source-hash: 91af97ee03e3f4fa98e259bed1e212df -->
+Builds the captions API URL for a video entity, returning the HTTPS endpoint path to `/api/captions/[entityType]/[entityId]` with a cache-busting hash. Returns `undefined` if the entity has no SRT content.
+
+## Key Components
+
+- **`getCaptionsUrl(entityType, entityId, srtContent?)`** — Constructs a versioned captions URL for VTT subtitle delivery. Accepts any string entity type discriminator (widened from the hub's `VideoEnabledEntityType` enum), making it usable across reverse-proxied embedder routes.
+
+The cache-busting `?v=` hash is derived from the `srtContent` length and first 8 non-whitespace characters, ensuring iOS Safari re-fetches VTT files when subtitles are regenerated (Safari aggressively caches `<track>` src URLs regardless of `Cache-Control` headers).
+
+## Usage Example
+
+```typescript
+import { getCaptionsUrl } from './captions-url'
+
+// Standard usage
+const url = getCaptionsUrl('video', 42, srtContent)
+// → "/api/captions/video/42?v=1024-1BrianWas"
+
+// Returns undefined when no subtitles exist
+const noUrl = getCaptionsUrl('video', 42, null)
+// → undefined
+
+// Custom entity type for embedder routes
+const embedUrl = getCaptionsUrl('lesson', 'abc-123', srtContent)
+// → "/api/captions/lesson/abc-123?v=512-1BrianWas"
+```
+
+> **Note:** Ported from hub `lib/utils/captions-url.ts`. The entity type is intentionally typed as `string` rather than a closed enum so downstream embedders can pass whatever discriminator their proxied `/api/captions/...` route expects.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.changelog-manager.md b/openframe-frontend-core/src/components/features/.changelog-manager.md
index fcfeb2923..125462326 100644
--- a/openframe-frontend-core/src/components/features/.changelog-manager.md
+++ b/openframe-frontend-core/src/components/features/.changelog-manager.md
@@ -1,59 +1,55 @@
-<!-- source-hash: 2cb028936365715865c9571d3df0261e -->
-A reusable React component for managing a dynamic list of changelog entries, supporting add, remove, expand/collapse, and optional per-entry visibility toggling.
+<!-- source-hash: 6569b7629f1bf2ea3fba9bd791c7fd0e -->
+A reusable React component for managing a dynamic list of changelog entries with collapsible cards, optional per-entry visibility toggling, and support for bulk expansion (e.g., after AI enrichment).
 
 ## Key Components
 
-### `ChangelogManager` (default export)
-
-A controlled list manager rendered as a collapsible accordion of `ChangelogEntry` items.
+**`ChangelogManager`** — Primary export. Renders a controlled list of `ChangelogEntry` items with add/remove/edit capabilities.
 
 **Props (`ChangelogManagerProps`):**
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `title` | `string` | Section label displayed above the entry list |
+| `title` | `string` | Section label displayed above the list |
 | `entries` | `ChangelogEntry[]` | Controlled array of changelog entries |
-| `onChange` | `(entries: ChangelogEntry[]) => void` | Callback fired on any mutation |
-| `className` | `string?` | Optional wrapper class override |
-| `expandAll` | `boolean?` | When `true`, expands all items (e.g. post-AI enrichment) |
-| `showVisibilityToggle` | `boolean?` | Renders a per-entry `Eye`/`EyeOff` toggle; used by investor updates |
+| `onChange` | `(entries: ChangelogEntry[]) => void` | Called on any mutation |
+| `expandAll` | `boolean` | Expands all cards (e.g., post-AI enrichment) |
+| `showVisibilityToggle` | `boolean` | Enables public/internal toggle per entry (investor updates use case) |
 
 **Internal state:**
-- `expandedIndices` — `Set<number>` tracking which accordion items are open
-
-**Key functions:**
-
-| Function | Behavior |
-|----------|----------|
-| `addEntry()` | Appends a blank entry and auto-expands it |
-| `removeEntry(index)` | Removes entry and adjusts the expanded indices set |
-| `updateEntry(index, field, value)` | Immutably updates a single field on an entry |
-| `toggleExpanded(index)` | Toggles accordion open/close state |
-| `toggleVisibility(index)` | Flips `visibility` between `'public'` and `'internal'` |
+- `expandedIndices` — `Set<number>` tracking which cards are open; automatically adjusted on add/remove to keep indices consistent.
 
 ## Usage Example
 
 ```typescript
 import { ChangelogManager } from './changelog-manager';
+import { useState } from 'react';
 import type { ChangelogEntry } from '../../types/product-release';
 
-const [entries, setEntries] = useState<ChangelogEntry[]>([]);
+export function ReleaseForm() {
+  const [features, setFeatures] = useState<ChangelogEntry[]>([]);
+
+  return (
+    <ChangelogManager
+      title="New Features"
+      entries={features}
+      onChange={setFeatures}
+      expandAll={false}
+      showVisibilityToggle={false}
+    />
+  );
+}
+```
 
-// Basic product release changelog
-<ChangelogManager
-  title="What's New"
-  entries={entries}
-  onChange={setEntries}
-/>
+For investor update forms, enable the visibility toggle:
 
-// Investor update with visibility control + auto-expand after AI fill
+```typescript
 <ChangelogManager
-  title="Highlights"
-  entries={entries}
-  onChange={setEntries}
-  showVisibilityToggle
+  title="Investor Highlights"
+  entries={highlights}
+  onChange={setHighlights}
+  showVisibilityToggle={true}
   expandAll={aiEnrichmentComplete}
 />
 ```
 
-> **Note:** `showVisibilityToggle` is intended for investor update flows. Leave it unset for standard product release changelogs to preserve their default UX. New entries default to `visibility: 'public'` when the toggle is enabled.
\ No newline at end of file
+> **Note:** `showVisibilityToggle` defaults new entries to `'public'`. Omit it for standard product release forms to preserve their existing UX.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.highlight-config-section.md b/openframe-frontend-core/src/components/features/.highlight-config-section.md
index 8e667b9eb..a92b33fa5 100644
--- a/openframe-frontend-core/src/components/features/.highlight-config-section.md
+++ b/openframe-frontend-core/src/components/features/.highlight-config-section.md
@@ -1,31 +1,26 @@
-<!-- source-hash: d7af9befa8736257f5fa1a7169b8bc9d -->
+<!-- source-hash: fb9ab3145c75efd2253c874e3544e7a9 -->
 Reusable configuration section component for highlight video generation settings, providing duration selection and subtitle burning controls in a unified horizontal layout.
 
 ## Key Components
 
-### `HighlightConfigSection`
-A client-side React component used across `CustomerInterview` and `ProductRelease` entity workflows to configure highlight video output options.
+**`HighlightConfigSection`** — Client-side React component used across `CustomerInterview` and `ProductRelease` entities to configure highlight video output.
 
-### `HighlightConfigSectionProps`
-| Prop | Type | Description |
-|------|------|-------------|
-| `targetDurationSeconds` | `number` | Current selected duration in seconds |
-| `onTargetDurationChange` | `(seconds: number) => void` | Callback fired on duration change |
-| `skipSubtitleBurning` | `boolean` | Whether subtitle burning is skipped |
-| `onSkipSubtitleBurningChange` | `(skip: boolean) => void` | Callback fired on subtitle toggle |
-| `disabled` | `boolean?` | Disables all controls (default: `false`) |
-| `className` | `string?` | Additional CSS class override |
-
-**Duration options:** 60s, 120s, 180s *(recommended)*, 240s, 300s
+**`HighlightConfigSectionProps`** — Interface defining:
+- `targetDurationSeconds` — Current duration value (in seconds)
+- `onTargetDurationChange` — Handler called with new duration in seconds
+- `skipSubtitleBurning` — Boolean toggle for subtitle burn-in
+- `onSkipSubtitleBurningChange` — Handler called with updated checkbox state
+- `disabled?` — Disables all controls (default: `false`)
+- `className?` — Optional Tailwind class override
 
 ## Usage Example
 
 ```typescript
-import { HighlightConfigSection } from './highlight-config-section';
+import { HighlightConfigSection } from '@/components/highlight-config-section';
 
-function VideoEditor() {
-  const [duration, setDuration] = useState(180);
-  const [skipSubs, setSkipSubs] = useState(false);
+function MyForm() {
+  const [duration, setDuration] = React.useState(180);
+  const [skipSubs, setSkipSubs] = React.useState(false);
 
   return (
     <HighlightConfigSection
@@ -39,4 +34,12 @@ function VideoEditor() {
 }
 ```
 
-> **Note:** Renders as a dark-themed panel (`bg-[#1a1a1a]`) with a `Select` dropdown for duration and a checkbox for subtitle burning, laid out horizontally via flexbox.
\ No newline at end of file
+## Duration Options
+
+| Value | Label |
+|-------|-------|
+| `60` | 1 minute |
+| `120` | 2 minutes |
+| `180` | 3 minutes *(Recommended)* |
+| `240` | 4 minutes |
+| `300` | 5 minutes |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.index.md b/openframe-frontend-core/src/components/features/.index.md
index 9fbb13145..4a6f491bf 100644
--- a/openframe-frontend-core/src/components/features/.index.md
+++ b/openframe-frontend-core/src/components/features/.index.md
@@ -1,50 +1,53 @@
-<!-- source-hash: 14a224c533f658697e4039f0850c87ac -->
-Central barrel export file for the feature components library, re-exporting all UI components, providers, and utilities from their respective modules into a single public API surface.
+<!-- source-hash: d08a88b94315ea42c38279ecf97cbab7 -->
+Central barrel export file for the feature components library, re-exporting all public UI components, hooks, providers, and utilities used across the Flamingo/OpenFrame platform.
 
 ## Key Components
 
-### Theme System
-- `ThemeProvider` / `useTheme` / `useThemeToggle` — Canonical ODS theme system wrapping `next-themes` with manual light/dark switching, default dark, and no-flash support
-- `DynamicThemeProvider` / `useDynamicTheme` — Dynamic theme provider variant
-- `THEME_STORAGE_KEY`, `THEME_ATTRIBUTE`, `DEFAULT_THEME` — Theme configuration constants
-- `Theme`, `ThemeProviderProps`, `UseThemeToggleResult` — TypeScript types
-
-### Video Primitives
-- `video` — Unified `<Video>` component replacing legacy `VideoPlayer` + `YouTubeEmbed`
-- `entity-video-section` / `video-bites-display` — Public detail-page wrappers
-- `video-ratio-tabs` — Aspect-ratio grouping primitives for bites grid and admin editors
-- `highlight-video-*` / `transcript-summary-editor` / `video-clips-section` — Video processing and display utilities
-
-### UI Components
-- `command-box`, `filters-dropdown`, `tags-selector`, `select-button`, `view-toggle`
-- `os-type-badge`, `platform-badge`, `platform-filter` — Platform/OS display components
-- `error-boundary`, `loading-provider` — App infrastructure components
-- `seo-editor-preview`, `social-links-manager`, `knowledge-base-links-manager`
-- `board`, `notifications`, `waitlist-form`, `ai-enrich`, `policy-configuration-panel`
-
-### Manager Components
-- `array-entry-manager`, `changelog-manager`, `changelog-sections-manager`
-- `clickup-tasks-manager`, `github-releases-manager`, `media-gallery-manager`
-- `release-media-manager`
+**Theme System**
+- `DynamicThemeProvider`, `useDynamicTheme` — runtime theme switching
+- `ThemeProvider`, `useTheme`, `useThemeToggle` — canonical ODS theme layer (wraps `next-themes`), headless by design; includes `THEME_STORAGE_KEY`, `THEME_ATTRIBUTE`, `DEFAULT_THEME` constants and related types
+
+**Video Primitives**
+- `video` — unified `<Video>` component replacing legacy `<VideoPlayer>` + `<YouTubeEmbed>`
+- `entity-video-section`, `video-bites-display`, `video-ratio-tabs` — public detail-page wrappers and aspect-ratio grouping
+- `video-clips-section`, `highlight-video-section`, `highlight-video-combined-section` — clip and highlight management
+- `transcript-summary-editor`, `transcribe-summarize-section` — AI transcription/summarization editors
+
+**UI Managers & Selectors**
+- `array-entry-manager`, `changelog-manager`, `media-gallery-manager`, `social-links-manager` — CRUD-style list managers
+- `filters-dropdown`, `platform-filter`, `status-filter-component`, `tags-selector` — filtering primitives
+- `command-box`, `section-selector`, `select-button`, `push-button-selector` — input/selection controls
+
+**Platform & Integration**
+- `os-type-badge`, `os-type-badge-group`, `platform-badge` — OS/platform labeling
+- `auth-providers-list`, `provider-button` — authentication UI
+- `github-releases-manager`, `clickup-tasks-manager` — third-party integrations
+- `ai-enrich`, `policy-configuration-panel` — AI enrichment controls
+- `notifications`, `board`, `ticket-status-config-list` — MSP operational UI
 
 ## Usage Example
 
 ```typescript
-// Import theme system
-import { ThemeProvider, useThemeToggle } from '@/features'
-
-function App({ children }) {
-  return <ThemeProvider>{children}</ThemeProvider>
+import {
+  ThemeProvider,
+  useThemeToggle,
+  Video,
+  FiltersDropdown,
+  CommandBox,
+  AiEnrich,
+} from '@your-org/feature-components'
+
+function App() {
+  return (
+    <ThemeProvider defaultTheme="dark" attribute="class">
+      <CommandBox />
+      <Video src="https://example.com/video.mp4" />
+    </ThemeProvider>
+  )
 }
 
 function ThemeToggle() {
   const { toggle, theme } = useThemeToggle()
-  return <Button onClick={toggle}>Mode: {theme}</Button>
+  return <button onClick={toggle}>Current: {theme}</button>
 }
-
-// Import video primitives
-import { Video, EntityVideoSection, VideoBitesDisplay } from '@/features'
-
-// Import UI components
-import { CommandBox, FiltersDropdown, OsTypeBadge } from '@/features'
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.mux-origins.md b/openframe-frontend-core/src/components/features/.mux-origins.md
new file mode 100644
index 000000000..38039e2f8
--- /dev/null
+++ b/openframe-frontend-core/src/components/features/.mux-origins.md
@@ -0,0 +1,28 @@
+<!-- source-hash: 2aaba76277d80ac2391985adc68e212d -->
+Defines the canonical Mux CDN origin URL constants, isolated in a server-safe module to prevent Next.js client-reference poisoning when imported by server-side code.
+
+## Key Components
+
+| Export | Value | Description |
+|--------|-------|-------------|
+| `MUX_STREAM_ORIGIN` | `https://stream.mux.com` | HLS playback base URL for `.m3u8` manifests, segments, and MP4 renditions |
+| `MUX_IMAGE_ORIGIN` | `https://image.mux.com` | Server-generated thumbnail base URL |
+
+## Usage Example
+
+```typescript
+import { MUX_STREAM_ORIGIN, MUX_IMAGE_ORIGIN } from '@/lib/config/mux-origins'
+
+// Build a playback URL (server or client safe)
+const playbackUrl = `${MUX_STREAM_ORIGIN}/${playbackId}.m3u8`
+
+// Build a thumbnail URL
+const thumbnailUrl = `${MUX_IMAGE_ORIGIN}/${playbackId}/thumbnail.jpg`
+
+// Safe for hostname extraction in server-side code
+const streamHost = new URL(MUX_STREAM_ORIGIN).hostname // 'stream.mux.com'
+```
+
+## Why a Separate Module
+
+Previously co-located with `use-video-warmup.ts` (`'use client'`), server-side imports caused a Vercel build crash — Next.js replaced the constants with client-function stubs, making `new URL(MUX_STREAM_ORIGIN)` throw `TypeError: Invalid URL`. Splitting into this non-client module restores server-safe imports while `use-video-warmup.ts` re-exports these for backward compatibility with existing client callers.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.og-editor-preview.md b/openframe-frontend-core/src/components/features/.og-editor-preview.md
index 5398b4389..899c119d9 100644
--- a/openframe-frontend-core/src/components/features/.og-editor-preview.md
+++ b/openframe-frontend-core/src/components/features/.og-editor-preview.md
@@ -1,31 +1,23 @@
-<!-- source-hash: 7e8d4cbbf42c408ee48d1318fbf9c4e3 -->
-Unified SEO & Open Graph editor component that combines meta fields (title, description, keywords), OG image upload, and a live preview into a single reusable panel. Designed for content editors across blog posts, case studies, and product releases.
+<!-- source-hash: 094e2d745dae1343d13b47bac3a9ff7d -->
+Reusable SEO & Open Graph editor panel that combines meta fields, OG image upload, and a live preview into a single composable component.
 
 ## Key Components
 
-### `OGEditorPreview`
-Main exported component that renders a card-style panel with:
-- **SEO Title + Keywords** — side-by-side `Input` fields (responsive grid)
-- **SEO Description + OG Image** — `Textarea` paired with an injected upload widget
-- **OG Preview** — rendered below a divider via the `OGPreviewComponent` slot
-
-### `OGEditorPreviewProps`
-Full interface defining:
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `seoTitle` / `seoDescription` / `seoKeywords` | `string` | Controlled SEO field values |
-| `ogImageUrl` | `string` | Current OG image URL |
-| `title` / `summary` / `featuredImage` | `string` | Auto-populate sources from parent content |
-| `categories` | `Array<{name, slug}>` | Optional category metadata |
-| `OGImageUploadComponent` | `React.ReactNode` | Upload widget injected by parent |
-| `OGPreviewComponent` | `React.ReactNode` | Preview widget injected by parent |
-| `disabled` | `boolean` | Disables all inputs |
+**`OGEditorPreview`** — Main component rendering a card layout with:
+- SEO Title + Keywords (side-by-side grid)
+- SEO Description + OG Image upload (side-by-side grid)
+- OG Preview section (injected via render prop)
+
+**`OGEditorPreviewProps`** — Interface defining:
+- SEO field values (`seoTitle`, `seoDescription`, `seoKeywords`, `ogImageUrl`)
+- Auto-populate sources (`title`, `summary`, `featuredImage`, `categories`)
+- Change handlers for each SEO field
+- `OGImageUploadComponent` / `OGPreviewComponent` — render props for parent-controlled upload/preview logic
 
 ## Usage Example
 
 ```typescript
-import { OGEditorPreview } from './og-editor-preview';
+import { OGEditorPreview } from '@/components/og-editor-preview';
 
 <OGEditorPreview
   seoTitle={post.seoTitle}
@@ -35,13 +27,18 @@ import { OGEditorPreview } from './og-editor-preview';
   title={post.title}
   summary={post.summary}
   featuredImage={post.featuredImage}
-  onSeoTitleChange={(val) => updateField('seoTitle', val)}
-  onSeoDescriptionChange={(val) => updateField('seoDescription', val)}
-  onSeoKeywordsChange={(val) => updateField('seoKeywords', val)}
-  onOgImageUrlChange={(val) => updateField('ogImageUrl', val)}
+  onSeoTitleChange={(val) => updatePost({ seoTitle: val })}
+  onSeoDescriptionChange={(val) => updatePost({ seoDescription: val })}
+  onSeoKeywordsChange={(val) => updatePost({ seoKeywords: val })}
+  onOgImageUrlChange={(val) => updatePost({ ogImageUrl: val })}
   OGImageUploadComponent={<OGImageUploader postId={post.id} />}
-  OGPreviewComponent={<OGPreview title={post.seoTitle} description={post.seoDescription} image={post.ogImageUrl} />}
+  OGPreviewComponent={<OGPreview title={post.seoTitle} image={post.ogImageUrl} />}
+  disabled={isSaving}
 />
 ```
 
-> Upload and preview widgets are passed as render props (`React.ReactNode`), keeping this component decoupled from specific upload or preview implementations.
\ No newline at end of file
+## Notes
+
+- Upload and preview logic are intentionally **decoupled** via render props, keeping this component reusable across blog posts, case studies, and product releases.
+- `disabled` prop propagates to all form inputs for save/loading states.
+- Responsive grid collapses to single column on smaller screens (`lg:grid-cols-2`).
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.release-media-manager.md b/openframe-frontend-core/src/components/features/.release-media-manager.md
index 61178a586..584305f96 100644
--- a/openframe-frontend-core/src/components/features/.release-media-manager.md
+++ b/openframe-frontend-core/src/components/features/.release-media-manager.md
@@ -1,5 +1,5 @@
-<!-- source-hash: 567153c4bee0ea823c8dcb3ad142df21 -->
-A React client component for managing media attachments (images, videos, screenshots, demos) on release entries, supporting file upload, drag-to-reorder, and inline editing.
+<!-- source-hash: e1ac7ea961dcca15d9366fc8ba5a85d0 -->
+A React client component for managing release media attachments, supporting file upload, drag-to-reorder, preview, and metadata editing for images and videos.
 
 ## Key Components
 
@@ -8,11 +8,11 @@ Represents a single media entry with the following fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `media_type` | `'image' \| 'video' \| 'screenshot' \| 'demo'` | Category of media |
-| `media_url` | `string` | Public URL after upload |
+| `media_type` | `'image' \| 'video' \| 'screenshot' \| 'demo'` | Category of the media |
+| `media_url` | `string` | Resolved URL after upload |
 | `title` | `string?` | Optional display title |
 | `description` | `string?` | Optional description |
-| `display_order` | `number?` | Sort position in gallery |
+| `display_order` | `number?` | Sort index |
 | `_file` | `File?` | Temporary pre-upload file reference |
 | `_uploading` | `boolean?` | Upload in-progress flag |
 
@@ -22,16 +22,15 @@ Represents a single media entry with the following fields:
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `media` | `ReleaseMediaItem[]` | Controlled media list |
-| `onChange` | `(media: ReleaseMediaItem[]) => void` | Called on any list mutation |
+| `media` | `ReleaseMediaItem[]` | Current media list (controlled) |
+| `onChange` | `(media: ReleaseMediaItem[]) => void` | Fires on any mutation |
 | `onUpload` | `(file, mediaType) => Promise<string>` | Handles actual file upload, returns URL |
 | `className` | `string?` | Optional wrapper class |
 
 **Internal behaviors:**
-- `handleFileSelect` — detects file MIME type, auto-assigns `media_type`, triggers `onUpload`, rolls back on failure
-- `removeMedia` — removes item by index
-- `updateMedia` — updates a single field on an existing item
-- `handleDragStart` / `handleDragOver` / `handleDrop` — native HTML5 drag-and-drop reordering, updates `display_order` on drop
+- Auto-detects `image/*` → `screenshot` and `video/*` → `demo` on file select
+- Shows upload spinner while `onUpload` resolves; reverts on failure
+- Drag-and-drop reordering updates `display_order` on all items
 
 ## Usage Example
 
@@ -40,10 +39,10 @@ import { ReleaseMediaManager, ReleaseMediaItem } from './release-media-manager';
 
 const [media, setMedia] = useState<ReleaseMediaItem[]>([]);
 
-async function uploadToStorage(file: File, mediaType: string): Promise<string> {
-  const formData = new FormData();
-  formData.append('file', file);
-  const res = await fetch('/api/upload', { method: 'POST', body: formData });
+async function handleUpload(file: File, mediaType: string): Promise<string> {
+  const form = new FormData();
+  form.append('file', file);
+  const res = await fetch('/api/releases/upload', { method: 'POST', body: form });
   const { url } = await res.json();
   return url;
 }
@@ -51,8 +50,8 @@ async function uploadToStorage(file: File, mediaType: string): Promise<string> {
 <ReleaseMediaManager
   media={media}
   onChange={setMedia}
-  onUpload={uploadToStorage}
+  onUpload={handleUpload}
 />
 ```
 
-> **Note:** The component is fully controlled — the parent owns the `media` array. Failed uploads automatically roll back to the previous state without manual intervention.
\ No newline at end of file
+> **Note:** `onUpload` is the only side-effect hook — all state changes are surfaced through `onChange`, keeping the component fully controlled.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/.use-video-warmup.md b/openframe-frontend-core/src/components/features/.use-video-warmup.md
new file mode 100644
index 000000000..6846d6496
--- /dev/null
+++ b/openframe-frontend-core/src/components/features/.use-video-warmup.md
@@ -0,0 +1,44 @@
+<!-- source-hash: c7b4d80b78439746c7e49c13ae4de7c3 -->
+Provides network warming for video content by preconnecting to video-bearing origins and conditionally preloading video bytes when a container nears the viewport.
+
+## Key Components
+
+### `useVideoOriginPreconnect(options?)`
+Fires preconnect hints to Mux stream/image CDN origins and Supabase Storage without any IntersectionObserver setup. Use this when no container `ref` is available (e.g. a page that delegates player rendering to a sibling component).
+
+- **`supabaseStorageOrigin?`** — overrides the value auto-read from `ChatRuntime.endpoints.supabaseStorageOrigin`
+
+### `useVideoWarmup<T>(options?)`
+Full warmup hook. Composes `useVideoOriginPreconnect` with an IO-gated preload step that injects a `<link rel="preload" as="video">` when:
+- The container ref enters within `nearMargin` of the viewport
+- `navigator.connection?.saveData` is not `true`
+- `videoUrl` resolves to the Supabase Storage origin (Mux HLS and YouTube are intentionally excluded)
+
+**Options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `videoUrl` | `undefined` | Effective video URL; only Supabase-hosted URLs are preloaded |
+| `supabaseStorageOrigin` | runtime fallback | Deployment-specific Supabase storage origin |
+| `nearMargin` | `'1000px'` | IO root margin for the preload gate |
+
+**Returns:** `{ ref, isNear }` — attach `ref` to the video container element.
+
+### Re-exports
+`MUX_STREAM_ORIGIN`, `MUX_IMAGE_ORIGIN` — re-exported from the server-safe `mux-origins.ts` module to avoid binding those constants to this `'use client'` file.
+
+## Usage Example
+
+```typescript
+// Full warmup — owns the video container
+const { ref } = useVideoWarmup({
+  videoUrl: entity.videoUrl,
+  nearMargin: '800px',
+})
+return <div ref={ref}><MuxPlayer /></div>
+
+// Preconnect-only — no container ref available
+useVideoOriginPreconnect()
+// supabaseStorageOrigin auto-resolved from ChatRuntime when
+// HubRuntimeProvider is mounted in the tree
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/board/.board-column-header.md b/openframe-frontend-core/src/components/features/board/.board-column-header.md
index 51df6f576..25782df08 100644
--- a/openframe-frontend-core/src/components/features/board/.board-column-header.md
+++ b/openframe-frontend-core/src/components/features/board/.board-column-header.md
@@ -1,38 +1,35 @@
-<!-- source-hash: 1ad6ce49d76bfa9f7bbe6737c01b2305 -->
-Renders the header for a Kanban board column, supporting both expanded and collapsed states with ticket status display, count, and optional ticket creation.
+<!-- source-hash: ca02054e0e467a0cfd1ca2c788a01f8f -->
+Renders the header for a Kanban board column, supporting both expanded and collapsed states with status tag, ticket count, and optional action buttons.
 
 ## Key Components
 
-### `BoardColumnHeaderProps`
-| Prop | Type | Description |
-|------|------|-------------|
-| `column` | `BoardColumnDef` | Column definition including id, label, color, and tickets |
-| `collapsed` | `boolean` | Controls collapsed/expanded display mode |
-| `onToggleCollapse` | `() => void` | Callback to toggle column collapse state |
-| `onAddTicket` | `() => void` (optional) | Callback to trigger ticket creation |
+**`BoardColumnHeaderProps`** — Interface defining the component's props:
+- `column` — `BoardColumnDef` containing label, status key, color, and ticket data
+- `collapsed` — toggles between vertical (collapsed) and horizontal (expanded) layouts
+- `onToggleCollapse` — required callback to expand/collapse the column
+- `onAddTicket` — optional callback; renders a `+` button when provided
+- `onArchive` — optional callback; renders an archive button when provided
 
-### `BoardColumnHeader`
-Client component that renders two distinct layouts:
-- **Collapsed:** Vertical layout with expand icon, rotated status tag, and ticket count
-- **Expanded:** Horizontal layout with status tag, count, collapse button, and optional add-ticket button
+**`BoardColumnHeader`** — Main exported component with two render paths:
+- **Collapsed:** vertical layout with expand arrow, rotated status tag, and ticket count
+- **Expanded:** horizontal layout with status tag, count, collapse arrow, and optional archive/add-ticket actions
 
-Uses `getTicketStatusConfig` to determine whether to use a built-in status color or a custom column color for the `TicketStatusTag`.
+**Status resolution logic** — Uses `resolveTicketStatus` to determine if the column maps to a known canonical status (e.g. `ACTIVE`, `RESOLVED`). Known statuses use the built-in tag variant; unrecognized IDs (custom UUIDs) fall back to the column's `color` prop.
 
 ## Usage Example
 
 ```typescript
-import { BoardColumnHeader } from './board-column-header'
-
 <BoardColumnHeader
   column={{
     id: 'in-progress',
     label: 'In Progress',
-    color: '#FFC008',
-    tickets: [...],
+    tickets: [],
     total: 12,
+    color: '#FFC008',
   }}
   collapsed={false}
-  onToggleCollapse={() => setCollapsed(prev => !prev)}
-  onAddTicket={() => openCreateTicketModal('in-progress')}
+  onToggleCollapse={() => setCollapsed(true)}
+  onAddTicket={() => openNewTicketModal('in-progress')}
+  onArchive={() => archiveResolved('in-progress')}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/board/.board-column.md b/openframe-frontend-core/src/components/features/board/.board-column.md
index 5083df319..578d82a3e 100644
--- a/openframe-frontend-core/src/components/features/board/.board-column.md
+++ b/openframe-frontend-core/src/components/features/board/.board-column.md
@@ -1,43 +1,38 @@
-<!-- source-hash: 1bf9b2d5d2d477b1115c900de71defaa -->
-Renders a single kanban board column with drag-and-drop support, collapsible layout, infinite scroll via IntersectionObserver, and ticket card rendering.
+<!-- source-hash: dc5b742204662fe5e5026feb2b1f4daf -->
+Renders a single kanban board column with drag-and-drop support, collapsible state, infinite scroll loading, and ticket card display.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `BoardColumn` | Component | Main column shell handling collapsed/expanded state, border joining, and color tinting |
-| `BoardColumnProps` | Interface | Public API for the column component |
-| `ColumnBody` | Internal Component | Scrollable droppable zone with `SortableContext`, infinite scroll sentinel, and loading states |
-| `SkeletonStack` | Internal Component | Renders `n` skeleton placeholders during initial load |
-| `EmptyState` | Internal Component | Illustrated empty state shown when a column has no tickets |
+- **`BoardColumn`** — Main exported component. Renders a collapsible column shell with a header, optional color tinting, and border-joining utilities (`joinLeft`/`joinRight`) for adjacent column layouts.
+- **`ColumnBody`** — Internal component managing the droppable zone (`useDroppable`), sortable ticket list (`SortableContext`), and infinite scroll via `IntersectionObserver`.
+- **`SkeletonStack`** — Renders `n` `TicketCardSkeleton` placeholders during initial load.
+- **`EmptyState`** — Displays a tag icon and instructional text when a column has no tickets.
+
+## Props (`BoardColumnProps`)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `column` | `BoardColumnDef` | Column definition including tickets, color, and loading state |
+| `collapsed` | `boolean` | Collapses column to `56px` width |
+| `onToggleCollapse` | `() => void` | Toggle handler for collapse state |
+| `onAddTicket` | `(columnId: string) => void` | Optional callback to add a ticket |
+| `onArchive` | `(columnId: string) => void` | Optional archive callback (only when `column.archivable`) |
+| `getTicketHref` | `(ticketId: string) => string` | Generates links for ticket cards |
+| `renderAssignSlot` | `(ticket: BoardTicket) => ReactNode` | Renders a custom assignee UI per card |
+| `onLoadMore` | `(columnId: string) => void` | Triggered by scroll sentinel for pagination |
+| `loadMoreRootMargin` | `string` | `IntersectionObserver` root margin, defaults to `"200px 0px"` |
+| `joinLeft` / `joinRight` | `boolean` | Removes border/radius on the joined side |
 
 ## Usage Example
 
 ```typescript
 <BoardColumn
-  column={{
-    id: 'open',
-    label: 'Open',
-    color: '#3B82F6',
-    tickets: myTickets,
-    hasMore: true,
-    isLoading: false,
-    isLoadingMore: false,
-  }}
+  column={myColumn}
   collapsed={false}
-  onToggleCollapse={() => setCollapsed(c => !c)}
+  onToggleCollapse={() => setCollapsed(prev => !prev)}
   onAddTicket={(columnId) => openNewTicketModal(columnId)}
   getTicketHref={(ticketId) => `/tickets/${ticketId}`}
-  renderAssignSlot={(ticket) => <AssigneePicker ticket={ticket} />}
+  renderAssignSlot={(ticket) => <AvatarPicker ticket={ticket} />}
   onLoadMore={(columnId) => fetchNextPage(columnId)}
-  joinLeft={false}
-  joinRight={true}
 />
-```
-
-## Notes
-
-- **Drag-and-drop**: Uses `@dnd-kit/core` (`useDroppable`) and `@dnd-kit/sortable` (`SortableContext`) — drop target is disabled when `column.dropDisabled` is set.
-- **Infinite scroll**: An `IntersectionObserver` watches a 1px sentinel div at the bottom of the scroll container; `onLoadMore` fires when it enters the viewport. Scroll is paused while `isLoadingMore` is true.
-- **Collapsed state**: When `collapsed=true`, the column shrinks to `w-14` and hides the body; the header remains visible.
-- **Joined borders**: `joinLeft`/`joinRight` props remove border radii and borders on adjacent edges for seamless multi-column layouts.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/board/.board.md b/openframe-frontend-core/src/components/features/board/.board.md
index 28d382b07..ea5e264d3 100644
--- a/openframe-frontend-core/src/components/features/board/.board.md
+++ b/openframe-frontend-core/src/components/features/board/.board.md
@@ -1,51 +1,47 @@
-<!-- source-hash: 266e1c3c423b749f9d7def8ff717188e -->
-A drag-and-drop Kanban board component that manages ticket movement across columns using `@dnd-kit/core`, with support for column collapsing, horizontal scrolling, and constrained drop rules.
+<!-- source-hash: 93ff2983d48b4ee1f8cf7bffb59d77d2 -->
+Kanban-style drag-and-drop board component that manages multi-column ticket reordering and cross-column moves using `@dnd-kit/core`.
 
 ## Key Components
 
-| Export / Symbol | Description |
-|---|---|
-| `Board` | Main board component rendering all columns with full DnD orchestration |
-| `BoardProps` | Props interface defining columns, event handlers, and customization options |
-| `collisionDetection` | Custom collision strategy: prefers ticket hits, falls back to column, then closest corners |
-| `handleDragStart` | Records drag origin (ticket + source column) and sets overlay state |
-| `handleDragOver` | Optimistically moves tickets across columns respecting `dropDisabled` and `allowedFromColumns` |
-| `handleDragEnd` | Commits the move by calling `onChange` with positional context (`afterTicketId`, `beforeTicketId`), or rolls back |
-| `handleDragCancel` | Reverts local state to the last server-provided `columns` prop |
-| `locate` | Helper to find a ticket's column, index, and reference by ID |
-| `findIndexInColumn` | Helper returning a ticket's index within a specific column |
+| Export | Type | Description |
+|--------|------|-------------|
+| `Board` | Component | Root board with full DnD context, column rendering, and custom scrollbar |
+| `BoardProps` | Interface | Configuration props for columns, callbacks, and rendering slots |
+| `locate` | Helper | Finds a ticket's column, index, and reference by ticket ID |
+| `findIndexInColumn` | Helper | Returns a ticket's index within a specific column |
+
+**Key behaviors:**
+- `collisionDetection` — custom strategy: prefers ticket hits, falls back to column hits, then `closestCorners`
+- `handleDragOver` — handles real-time cross-column moves with `dropDisabled` and `allowedFromColumns` guards
+- `handleDragEnd` — emits a `BoardChange` with `afterTicketId`/`beforeTicketId` for ordered persistence
+- `useBoardCollapse` — persists per-column collapsed state to storage via `collapseStorageKey`
+- `useHorizontalScrollbar` — custom scrollbar track/thumb replacing native browser scrollbar
 
 ## Usage Example
 
 ```typescript
+import { Board } from './board'
+import type { BoardColumnDef, BoardChange } from './types'
+
+const columns: BoardColumnDef[] = [
+  { id: 'open', label: 'Open', tickets: [...] },
+  { id: 'in-progress', label: 'In Progress', tickets: [...], allowedFromColumns: ['open'] },
+  { id: 'done', label: 'Done', tickets: [...], dropDisabled: true },
+]
+
+function handleChange(change: BoardChange) {
+  console.log(`Moved ticket ${change.ticketId} from ${change.fromColumnId} to ${change.toColumnId}`)
+  // persist order using afterTicketId / beforeTicketId
+}
+
 <Board
-  columns={[
-    {
-      id: 'open',
-      label: 'Open',
-      tickets: [{ id: 'T-1', title: 'Fix login bug' }],
-    },
-    {
-      id: 'in-progress',
-      label: 'In Progress',
-      tickets: [],
-      allowedFromColumns: ['open'],
-    },
-    {
-      id: 'done',
-      label: 'Done',
-      tickets: [],
-      dropDisabled: true,
-    },
-  ]}
-  onChange={({ ticketId, fromColumnId, toColumnId, afterTicketId }) => {
-    api.moveTicket({ ticketId, toColumnId, afterTicketId })
-  }}
+  columns={columns}
+  onChange={handleChange}
   onLoadMore={(columnId) => fetchMore(columnId)}
-  getTicketHref={(ticketId) => `/tickets/${ticketId}`}
-  renderAssignSlot={(ticket) => <AssigneeAvatar ticket={ticket} />}
+  onAddTicket={(columnId) => openCreateModal(columnId)}
+  getTicketHref={(id) => `/tickets/${id}`}
   collapseStorageKey="board-collapse-state"
 />
 ```
 
-> **Drop rules:** Set `dropDisabled: true` on a column to block all inbound drops. Use `allowedFromColumns: ['open']` to restrict which source columns can feed into a target — dragging back to the origin column is always permitted regardless of these rules.
\ No newline at end of file
+> `isDraggingRef` prevents external `columns` prop updates from overwriting optimistic local state mid-drag, ensuring smooth UX without flicker.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/board/.types.md b/openframe-frontend-core/src/components/features/board/.types.md
index 9e4d9d803..5c734be52 100644
--- a/openframe-frontend-core/src/components/features/board/.types.md
+++ b/openframe-frontend-core/src/components/features/board/.types.md
@@ -1,45 +1,49 @@
-<!-- source-hash: 17f22ebd29735a4ef28b5782559c367e -->
-Defines the core data types and utility functions for the Kanban-style ticket board, including column definitions, ticket shapes, and helpers for mapping ticket statuses to board columns.
+<!-- source-hash: f68c208ea9150f93d3fc4b626d2c0df2 -->
+Core type definitions and utility functions for the ticket board (kanban-style) feature, including column definitions, ticket shapes, drag-and-drop change descriptors, and helpers for building columns from ticket statuses.
 
 ## Key Components
 
-### Types
+### Types & Interfaces
 
-| Type | Description |
-|------|-------------|
-| `BoardPriority` | Union type for ticket priority levels: `low`, `medium`, `high`, `urgent` |
+| Export | Description |
+|--------|-------------|
+| `BoardPriority` | Union type: `'low' \| 'medium' \| 'high' \| 'urgent'` |
 | `BoardTicketAssignee` | Assignee shape with optional avatar, initials, and name |
-| `BoardTicket` | Core ticket shape with status, priority, assignees, tags, and device info |
-| `BoardColumnDef` | Column definition including tickets, loading states, and drag/drop controls |
-| `BoardChange` | Represents a ticket move event between columns with ordering context |
+| `BoardTicket` | Core ticket shape used on the board |
+| `BoardColumnDef` | Full column definition including display, loading state, and DnD constraints |
+| `BoardChange` | Describes a ticket move event between columns |
 
 ### Functions
 
-| Function | Description |
-|----------|-------------|
-| `columnFromTicketStatus` | Creates a `BoardColumnDef` from a `TicketStatus` with optional overrides |
-| `groupTicketsByStatus` | Buckets a flat ticket array into ordered columns by status |
-| `canonicalize` (internal) | Normalizes raw status strings to `TicketStatus`, including legacy `ACTION_REQUIRED → TECH_REQUIRED` mapping |
+| Export | Description |
+|--------|-------------|
+| `columnFromTicketStatus` | Builds a `BoardColumnDef` from a canonical `TicketStatus` with optional overrides |
+| `groupTicketsByStatus` | Groups a flat ticket array into ordered `BoardColumnDef[]` by status |
 
 ## Usage Example
 
 ```typescript
-import { groupTicketsByStatus, columnFromTicketStatus } from './types'
+import { columnFromTicketStatus, groupTicketsByStatus } from './types'
 
-// Group tickets into columns for the board
-const columns = groupTicketsByStatus(tickets, [
+// Build a single column with overrides
+const activeColumn = columnFromTicketStatus('ACTIVE', myTickets, {
+  label: 'In Progress',
+  dropDisabled: false,
+  system: true,
+})
+
+// Group all tickets into ordered board columns
+const columns = groupTicketsByStatus(allTickets, [
   'ACTIVE',
+  'AI_ASSISTANCE',
   'TECH_REQUIRED',
   'ON_HOLD',
   'RESOLVED',
 ])
-
-// Build a single column with custom label and loading state
-const activeColumn = columnFromTicketStatus('ACTIVE', activeTickets, {
-  label: 'In Progress',
-  isLoadingMore: true,
-  total: 42,
-})
 ```
 
-> `canonicalize` handles legacy status values automatically — `ACTION_REQUIRED` from older API responses is silently mapped to `TECH_REQUIRED` before bucketing.
\ No newline at end of file
+## Notes
+
+- `BoardColumnDef.statusKey` allows custom-status columns (UUID `id`) to still resolve the correct `TicketStatusTag` variant for header styling.
+- `canonicalize()` (internal) normalises status strings — mapping legacy `ACTION_REQUIRED` → `TECH_REQUIRED` and uppercasing/underscoring free-text values before bucketing.
+- `STATUS_DEFAULTS` defines the canonical label and hex color for each system status used as fallbacks in `columnFromTicketStatus`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/notifications/.index.md b/openframe-frontend-core/src/components/features/notifications/.index.md
index 1b28d43a4..7671fd318 100644
--- a/openframe-frontend-core/src/components/features/notifications/.index.md
+++ b/openframe-frontend-core/src/components/features/notifications/.index.md
@@ -1,18 +1,22 @@
-<!-- source-hash: ec818e1d65048d1eb76277abcc10c0b6 -->
-Public API barrel file for the notifications module, re-exporting all components, hooks, context providers, and TypeScript types from their respective source files.
+<!-- source-hash: e4841e52bbe08da3a9c3858540ab8080 -->
+Barrel export file for the notifications module, re-exporting all public components, hooks, context providers, and TypeScript types from the notifications subsystem.
 
 ## Key Components
 
-| Export | Type | Source |
-|--------|------|--------|
-| `NotificationsProvider` | Component | `notifications-context` |
-| `useNotifications` | Hook | `notifications-context` |
-| `useOptionalNotifications` | Hook | `notifications-context` |
-| `NotificationDrawer` | Component | `notification-drawer` |
-| `NotificationTile` | Component | `notification-tile` |
-| `Notification` | Type | `types` |
-| `NotificationVariant` | Type | `types` |
-| `AddNotificationInput` | Type | `types` |
+**Context & Hooks**
+- `NotificationsProvider` — Context provider for managing notification state
+- `useNotifications` — Hook to access notifications context (throws if no provider)
+- `useOptionalNotifications` — Hook to access notifications context (returns `undefined` if no provider)
+
+**UI Components**
+- `NotificationDrawer` — Slide-out drawer displaying a list of notifications
+- `NotificationTile` — Individual notification item/card
+- `NotificationPopups` — Toast-style popup notifications with configurable position
+
+**Types**
+- `Notification`, `NotificationVariant`, `NotificationSeverity`, `AddNotificationInput`
+- `NotificationsProviderProps`, `NotificationsActions`
+- `NotificationDrawerProps`, `NotificationTileProps`, `NotificationPopupsProps`, `NotificationPopupsPosition`
 
 ## Usage Example
 
@@ -20,34 +24,30 @@ Public API barrel file for the notifications module, re-exporting all components
 import {
   NotificationsProvider,
   useNotifications,
+  NotificationPopups,
   NotificationDrawer,
-  NotificationTile,
-} from '@/notifications'
-
-import type {
-  Notification,
-  NotificationVariant,
-  AddNotificationInput,
-} from '@/notifications'
+} from './notifications'
+import type { AddNotificationInput } from './notifications'
 
-// Wrap your app with the provider
 function App() {
   return (
     <NotificationsProvider>
+      <NotificationPopups position="top-right" />
       <NotificationDrawer />
-      <MainContent />
+      <MyPage />
     </NotificationsProvider>
   )
 }
 
-// Consume notifications in a child component
-function MainContent() {
+function MyPage() {
   const { addNotification } = useNotifications()
 
   const notify = () => {
     const input: AddNotificationInput = {
-      variant: 'success' as NotificationVariant,
-      message: 'Operation completed successfully',
+      title: 'Success',
+      message: 'Operation completed.',
+      variant: 'toast',
+      severity: 'success',
     }
     addNotification(input)
   }
diff --git a/openframe-frontend-core/src/components/features/notifications/.notification-drawer.md b/openframe-frontend-core/src/components/features/notifications/.notification-drawer.md
index 3714e2c59..ae3c64e0a 100644
--- a/openframe-frontend-core/src/components/features/notifications/.notification-drawer.md
+++ b/openframe-frontend-core/src/components/features/notifications/.notification-drawer.md
@@ -1,34 +1,47 @@
-<!-- source-hash: b78c3c40a3c3824dbca516563b5aef06 -->
-A right-side drawer component that displays unread notifications, a "Complete All" action, a pop-up toggle, and a history navigation button — consuming context from `useOptionalNotifications`.
+<!-- source-hash: 22c01f34e7d2416f17b607f8e963c8d6 -->
+A right-side drawer component for displaying and managing unread notifications, built on Radix UI Dialog primitives with infinite scroll support.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `NotificationDrawer` | Component | Main drawer shell; renders only when notifications context is available |
-| `EmptyState` | Internal Component | Shown when there are no unread notifications |
-| `ShowNotificationsToggleRow` | Internal Component | Switch to enable/disable pop-up notification banners |
-| `NotificationsHistoryButton` | Internal Component | Outline button that navigates to notification history and closes the drawer |
-| `NotificationDrawerProps` | Interface | `className` and optional `liveDurationMs` for tile animations |
+| `NotificationDrawer` | Component | Root drawer component; consumes `NotificationsContext` and renders the full panel |
+| `DrawerScrollList` | Internal | Scrollable list with `IntersectionObserver`-based infinite scroll sentinel |
+| `DrawerLoadingTiles` | Internal | Animated skeleton tiles shown while loading more notifications |
+| `EmptyState` | Internal | Shown when there are no unread notifications |
+| `ShowNotificationsToggleRow` | Internal | Toggle switch to enable/disable pop-up notification banners |
+| `NotificationsHistoryButton` | Internal | Outline button that triggers `onHistoryClick` and closes the drawer |
+
+### `NotificationDrawerProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes for the drawer content |
+| `liveDurationMs` | `number` | — | Passed to each `NotificationTile` for live countdown behavior |
+| `loadMoreRootMargin` | `string` | `'200px'` | `rootMargin` for the `IntersectionObserver` that triggers pagination |
 
 ## Usage Example
 
 ```typescript
-import { NotificationDrawer } from './notification-drawer'
 import { NotificationsProvider } from './notifications-context'
+import { NotificationDrawer } from './notification-drawer'
 
-// Wrap your app (or layout) with the provider, then drop the drawer anywhere:
-export function AppLayout({ children }: { children: React.ReactNode }) {
+export function AppShell() {
   return (
     <NotificationsProvider
       notifications={notifications}
-      onHistoryClick={() => router.push('/notifications/history')}
+      onMarkRead={handleMarkRead}
+      onLoadMore={handleLoadMore}
+      hasMore={hasMore}
     >
-      {children}
-      <NotificationDrawer liveDurationMs={5000} />
+      {/* Drawer reads all state from context — no extra props required */}
+      <NotificationDrawer
+        liveDurationMs={30_000}
+        loadMoreRootMargin="300px"
+      />
     </NotificationsProvider>
   )
 }
 ```
 
-> **Note:** `NotificationDrawer` returns `null` when rendered outside a `NotificationsProvider`. Open/close state is fully managed through the context — use the `open`/`close` methods exposed by `useOptionalNotifications` to control visibility from elsewhere in the UI.
\ No newline at end of file
+> **Note:** `NotificationDrawer` returns `null` when rendered outside a `NotificationsProvider`. Open/close state, `markRead`, `markAllRead`, and pagination are all driven by `useOptionalNotifications()`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/notifications/.notification-popups.md b/openframe-frontend-core/src/components/features/notifications/.notification-popups.md
new file mode 100644
index 000000000..d08b69858
--- /dev/null
+++ b/openframe-frontend-core/src/components/features/notifications/.notification-popups.md
@@ -0,0 +1,45 @@
+<!-- source-hash: 5c8225541c23b75809d638040c04ad7c -->
+Renders a fixed-position overlay of transient notification toasts, consuming live (unread, unsettled, within `liveDurationMs`) notifications from the notifications context.
+
+## Key Components
+
+**`NotificationPopupsPosition`** — Union type for the four supported corner positions: `'top-right'`, `'top-left'`, `'bottom-right'`, `'bottom-left'`.
+
+**`NotificationPopupsProps`** — Configuration interface:
+| Prop | Default | Description |
+|---|---|---|
+| `liveDurationMs` | `4000` | How long (ms) a notification stays visible |
+| `maxVisible` | `4` | Maximum simultaneous toasts |
+| `position` | `'top-right'` | Corner anchor for the popup stack |
+| `hideWhenDrawerOpen` | `true` | Hides popups when the notification drawer is open |
+
+**`NotificationPopups`** — Main export. Reads from `useOptionalNotifications` context; returns `null` if context is absent, `showPopups` is false, or no live notifications exist.
+
+**Activation behavior** — Clicking or pressing `Enter`/`Space` on a toast:
+- If `notification.onClick` exists → calls it, marks the notification read and settled
+- Otherwise → opens the notification drawer, marks settled only
+
+Nested `<button>` elements (dismiss/action controls) handle their own events independently via `closest('button')` guard.
+
+## Usage Example
+
+```typescript
+import { NotificationPopups } from './notification-popups'
+import { NotificationsProvider } from './notifications-context'
+
+export function AppShell() {
+  return (
+    <NotificationsProvider>
+      <main>{/* app content */}</main>
+
+      {/* Toasts in bottom-right, hidden after 5s, max 3 visible */}
+      <NotificationPopups
+        position="bottom-right"
+        liveDurationMs={5000}
+        maxVisible={3}
+        hideWhenDrawerOpen={true}
+      />
+    </NotificationsProvider>
+  )
+}
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/notifications/.notifications-context.md b/openframe-frontend-core/src/components/features/notifications/.notifications-context.md
index c33564363..c74e53873 100644
--- a/openframe-frontend-core/src/components/features/notifications/.notifications-context.md
+++ b/openframe-frontend-core/src/components/features/notifications/.notifications-context.md
@@ -1,73 +1,53 @@
-<!-- source-hash: c21d20125d1c832d1265f5a500b7053e -->
-React context provider managing in-app notification state, including add, read, settle, remove, and panel open/close operations via a reducer pattern.
+<!-- source-hash: 88927981fd8125618868d164be4e2c25 -->
+React context provider for managing in-app notification state, including read/unread tracking, drawer open state, popup visibility, and optional server-side persistence callbacks.
 
 ## Key Components
 
-### `NotificationsProvider`
-Wraps your app (or a subtree) to supply notification state. Uses `useReducer` for immutable state transitions and `useCallback`/`useMemo` for stable references.
+**`NotificationsProvider`** — Top-level provider wrapping the app or a subtree. Manages a `useReducer`-based notification list with a configurable cap (`maxNotifications`, default `50`), drawer open state, and popup visibility.
 
-**Props:**
+**`useNotifications()`** — Hook that returns the full context value; throws if used outside the provider.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `initialNotifications` | `Notification[]` | `[]` | Seed the store on mount |
-| `maxNotifications` | `number` | `50` | Hard cap; oldest entries are trimmed |
-| `defaultShowPopups` | `boolean` | `true` | Initial popup visibility |
-| `onShowPopupsChange` | `(v: boolean) => void` | — | Callback on popup toggle |
-| `onHistoryClick` | `() => void` | — | Callback for "view history" action |
+**`useOptionalNotifications()`** — Safe version that returns `null` instead of throwing when used outside the provider.
 
-### `useNotifications`
-Primary hook — throws if called outside the provider.
+**`NotificationsActions`** — Optional side-effect callbacks (`onMarkRead`, `onMarkAllRead`, `onRemove`, `onMarkSettled`) fired after local state updates for server-side persistence.
 
-### `useOptionalNotifications`
-Safe hook — returns `null` instead of throwing; useful for components that optionally participate in the notification system.
+**Reducer actions** — `add`, `upsert`, `set`, `markRead`, `markAllRead`, `markSettled`, `remove`, `clear`
 
-### `reducer`
-Pure state reducer handling: `add`, `markRead`, `markAllRead`, `markSettled`, `remove`, `clear`.
+- `add` prepends and deduplicates by `id`, respects `maxNotifications`
+- `upsert` merges in-place if the `id` already exists, otherwise prepends
+- `set` syncs a full list while preserving existing `read`/`settled` state
 
 ## Usage Example
 
 ```typescript
-import { NotificationsProvider, useNotifications } from './notifications-context'
-
-// 1. Wrap your app
-export default function App() {
-  return (
-    <NotificationsProvider maxNotifications={100} defaultShowPopups={true}>
-      <Dashboard />
-    </NotificationsProvider>
-  )
-}
-
-// 2. Consume in any child component
-function Dashboard() {
-  const { addNotification, unreadCount, markAllRead, toggle } = useNotifications()
-
-  const notify = () =>
+// Wrap your app
+<NotificationsProvider
+  initialNotifications={serverNotifications}
+  maxNotifications={100}
+  actions={{
+    onMarkRead: async (id) => await api.markNotificationRead(id),
+    onMarkAllRead: async () => await api.markAllRead(),
+    onRemove: async (id) => await api.deleteNotification(id),
+  }}
+  hasMore={pagination.hasMore}
+  isLoadingMore={pagination.isLoading}
+  onLoadMore={pagination.loadNextPage}
+>
+  <App />
+</NotificationsProvider>
+
+// Consume in any child component
+function NotificationBell() {
+  const { unreadCount, toggle, addNotification } = useNotifications()
+
+  const handleNew = () => {
     addNotification({
-      title: 'Ticket Updated',
-      description: 'Ticket #1042 was resolved by Mingo AI.',
-      color: 'success',
+      title: 'Ticket updated',
+      message: 'INC-1042 was assigned to you',
+      type: 'info',
     })
+  }
 
-  return (
-    <>
-      <button onClick={notify}>Trigger</button>
-      <button onClick={toggle}>Inbox ({unreadCount})</button>
-      <button onClick={markAllRead}>Mark all read</button>
-    </>
-  )
+  return <button onClick={toggle}>🔔 {unreadCount}</button>
 }
-```
-
-## Context Value Reference
-
-| Method / Property | Description |
-|---|---|
-| `notifications` | Full ordered array, newest first |
-| `unreadCount` | Derived count of unread items |
-| `isOpen` | Panel open state |
-| `addNotification(input)` | Adds entry, returns generated `id` |
-| `markSettled(id)` | Marks a notification as acted upon (e.g. hides progress) |
-| `open / close / toggle` | Control panel visibility |
-| `setShowPopups(bool)` | Toggle toast popups globally |
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/notifications/.types.md b/openframe-frontend-core/src/components/features/notifications/.types.md
index ca723da54..69d80c663 100644
--- a/openframe-frontend-core/src/components/features/notifications/.types.md
+++ b/openframe-frontend-core/src/components/features/notifications/.types.md
@@ -1,45 +1,50 @@
-<!-- source-hash: 30636d800aad270ef8c49d64c5fe172d -->
-Defines TypeScript types for the notification system, including variant styles, notification shape, and input for creating new notifications.
+<!-- source-hash: 8b6849d4e24d5051b6f4a7164f95042b -->
+Type definitions for the notification system, defining the shape of notification objects and related input types used across the UI.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `NotificationVariant` | `type` | Union type for notification styles: `default`, `success`, `warning`, `error`, `info` |
-| `Notification` | `interface` | Full notification object shape including metadata and state |
-| `AddNotificationInput` | `type` | Partial input type for creating notifications, omitting auto-generated fields |
+- **`NotificationVariant`** — Union type for visual styling: `'default' | 'success' | 'warning' | 'error' | 'info'`
+- **`NotificationSeverity`** — Union type for severity levels: `'INFO' | 'WARNING' | 'DANGER'`
+- **`Notification`** — Core interface representing a full notification record with display, state, and interaction fields
+- **`AddNotificationInput`** — Input type for creating notifications, omitting server-managed fields (`id`, `createdAt`, `settled`) and making `id`, `createdAt`, and `read` optional
+
+## Notification Interface Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier |
+| `title` | `ReactNode` | ✅ | Primary display content |
+| `createdAt` | `number` | ✅ | Unix timestamp |
+| `variant` | `NotificationVariant` | ❌ | Visual style |
+| `description` | `ReactNode` | ❌ | Secondary content |
+| `read` | `boolean` | ❌ | Read state |
+| `settled` | `boolean` | ❌ | Dismissed/resolved state |
+| `severity` | `NotificationSeverity` | ❌ | Alert severity level |
+| `category` | `string` | ❌ | Grouping label |
+| `meta` | `Record<string, unknown>` | ❌ | Arbitrary metadata |
+| `onClick` | `() => void` | ❌ | Click handler |
 
 ## Usage Example
 
 ```typescript
-import type { Notification, AddNotificationInput, NotificationVariant } from './types'
+import type { Notification, AddNotificationInput } from './types'
 
-// Creating a new notification input
+// Creating a new notification
 const input: AddNotificationInput = {
+  title: 'Ticket Updated',
+  description: 'Ticket #1042 has been resolved.',
   variant: 'success',
-  title: 'Ticket Resolved',
-  description: 'Issue #1042 has been closed successfully.',
-  meta: { ticketId: '1042' }
+  severity: 'INFO',
+  category: 'tickets',
+  onClick: () => router.push('/tickets/1042'),
 }
 
-// Full notification object (after system assigns id, createdAt, etc.)
+// Full notification after system assignment
 const notification: Notification = {
-  id: 'notif-abc123',
-  variant: 'error',
-  title: 'Connection Failed',
-  description: 'Unable to reach the RMM agent.',
+  ...input,
+  id: 'notif_abc123',
   createdAt: Date.now(),
   read: false,
   settled: false,
-  meta: { agentId: 'agent-007' }
 }
-
-// Using the variant type directly
-const variant: NotificationVariant = 'warning'
-```
-
-## Notes
-
-- `title` and `description` accept `ReactNode`, allowing rich content (strings, JSX elements).
-- `AddNotificationInput` makes `id` and `createdAt` optional, allowing the system to auto-generate them.
-- `meta` is an open-ended `Record<string, unknown>` for attaching arbitrary contextual data.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/features/ticket-status-config-list/.ticket-status-config-list.md b/openframe-frontend-core/src/components/features/ticket-status-config-list/.ticket-status-config-list.md
new file mode 100644
index 000000000..6deb17f1b
--- /dev/null
+++ b/openframe-frontend-core/src/components/features/ticket-status-config-list/.ticket-status-config-list.md
@@ -0,0 +1,52 @@
+<!-- source-hash: 747c97a0dcc543cc1e134fa67adf6127 -->
+A reusable drag-and-drop sortable list component for ticket status configuration, built on `@dnd-kit/core` with keyboard and pointer sensor support.
+
+## Key Components
+
+- **`TicketStatusConfigList<T>`** — Generic sortable list container that manages DnD context, sensors, and reorder callbacks. Accepts any item type with an `id: string` field.
+- **`SortableRow`** — Internal wrapper that applies DnD transform/transition styles and exposes drag handle props via a render-prop pattern.
+- **`TicketStatusConfigListProps<T>`** — Props interface accepting `items`, `onReorder(oldIndex, newIndex)`, a `renderRow` render-prop, and an optional `className`.
+- **`SortableRowRenderArgs`** — Render-prop argument type exposing `dragHandleProps`, `dragHandleAttributes`, and `isDragging` to the consumer.
+
+## Usage Example
+
+```typescript
+import {
+  TicketStatusConfigList,
+  type SortableRowRenderArgs,
+} from './ticket-status-config-list'
+
+const statuses = [
+  { id: '1', label: 'Open' },
+  { id: '2', label: 'In Progress' },
+  { id: '3', label: 'Closed' },
+]
+
+function StatusSettings() {
+  const [items, setItems] = React.useState(statuses)
+
+  const handleReorder = (oldIndex: number, newIndex: number) => {
+    setItems(prev => {
+      const next = [...prev]
+      const [moved] = next.splice(oldIndex, 1)
+      next.splice(newIndex, 0, moved)
+      return next
+    })
+  }
+
+  return (
+    <TicketStatusConfigList
+      items={items}
+      onReorder={handleReorder}
+      renderRow={(item, { dragHandleProps, dragHandleAttributes, isDragging }: SortableRowRenderArgs) => (
+        <div style={{ opacity: isDragging ? 0.5 : 1 }}>
+          <span {...dragHandleAttributes} {...dragHandleProps}>⠿</span>
+          {item.label}
+        </div>
+      )}
+    />
+  )
+}
+```
+
+The `onReorder` callback receives array indices rather than IDs, so the parent is responsible for applying the reorder logic to its own state.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/icons/.vendor-directory-icon.md b/openframe-frontend-core/src/components/icons/.vendor-directory-icon.md
index bb7f284b6..85b7cf94c 100644
--- a/openframe-frontend-core/src/components/icons/.vendor-directory-icon.md
+++ b/openframe-frontend-core/src/components/icons/.vendor-directory-icon.md
@@ -1,32 +1,31 @@
-<!-- source-hash: bb86444b1d7f0013339971e9d47458b3 -->
-A React SVG icon component that renders a vendor directory/search icon, featuring a 3D package/box with a magnifying glass overlay to represent searching through vendor directories.
+<!-- source-hash: 9f5009b34317d5970b3bb61aa96ef597 -->
+A deprecated SVG icon component representing a vendor directory with a search/magnifier overlay, used in the Flamingo MSP platform UI.
 
 ## Key Components
 
-- **VendorDirectoryIcon**: Main functional component that renders the SVG icon
-- **VendorDirectoryIconProps**: TypeScript interface defining customizable props including color, dimensions, and CSS classes
+**`VendorDirectoryIconProps`** — Interface defining optional props:
+- `color` — Fill color for SVG paths (default: `'white'`)
+- `className` — CSS class string (default: `""`)
+- `width` — Icon width in pixels (default: `20`)
+- `height` — Icon height in pixels (default: `20`)
+
+**`VendorDirectoryIcon`** — Deprecated React functional component rendering a two-path SVG: a package/box shape with a search magnifier overlay, fixed to a `20x20` viewBox.
+
+> **⚠️ Deprecated:** Use icons from `icons-v2-generated` instead.
 
 ## Usage Example
 
 ```typescript
 import { VendorDirectoryIcon } from './vendor-directory-icon';
 
-// Basic usage with defaults (white, 20x20px)
+// Default usage
 <VendorDirectoryIcon />
 
-// Customized appearance
-<VendorDirectoryIcon 
-  color="#3B82F6" 
-  width={32} 
-  height={32} 
-  className="hover:opacity-80 transition-opacity" 
+// Custom size and color
+<VendorDirectoryIcon
+  width={24}
+  height={24}
+  color="#FFC008"
+  className="mr-2"
 />
-
-// In a button or navigation
-<button className="flex items-center gap-2">
-  <VendorDirectoryIcon color="currentColor" />
-  <span>Search Vendors</span>
-</button>
-```
-
-The icon uses a fixed 20x20 viewBox that scales proportionally with the width/height props. The SVG contains two main path elements: a 3D isometric package/directory icon and a magnifying glass overlay, making it perfect for vendor search or directory browsing functionality in applications.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/layout/.page-heading.md b/openframe-frontend-core/src/components/layout/.page-heading.md
new file mode 100644
index 000000000..209ffa2e7
--- /dev/null
+++ b/openframe-frontend-core/src/components/layout/.page-heading.md
@@ -0,0 +1,36 @@
+<!-- source-hash: 213b73998e45c90c2915371440ce2702 -->
+Renders a consistent page-level heading (`<h1>` or `<h2>`) with an optional description paragraph, serving as the single source of truth for the ODS `text-h1` typographic token across all pages.
+
+## Key Components
+
+- **`PAGE_HEADING_CLASS`** — Exported constant (`'text-h1 text-ods-text-primary'`) for rare cases where the heading element cannot be used directly
+- **`PageHeadingProps`** — Interface defining `children`, `as`, `description`, `className`, and `descriptionClassName`
+- **`PageHeading`** — Primary component; renders the heading tag and an optional `<p>` description, safely excluding falsy `ReactNode` values (empty string, `false`) to prevent phantom spacing
+
+## Usage Example
+
+```typescript
+// Standard h1 with description
+<PageHeading description="Manage all your connected devices from one place.">
+  Devices
+</PageHeading>
+
+// Pass 'h2' when a hero h1 already exists above
+<PageHeading as="h2" className="mt-8">
+  Recent Activity
+</PageHeading>
+
+// With an accent span in the heading
+<PageHeading description={<>Learn more at <a href="/docs">docs</a></>}>
+  Welcome to <span className="text-amber-400">OpenFrame</span>
+</PageHeading>
+
+// Using PAGE_HEADING_CLASS directly (non-component caller)
+<div className={PAGE_HEADING_CLASS}>Custom Heading</div>
+```
+
+## Notes
+
+- **Do not** hardcode `text-h1` sizes or letter-spacing elsewhere — always use `<PageHeading>` or `PAGE_HEADING_CLASS`
+- Layout concerns (margins, container widths) belong to the caller; this component owns only the heading and description styling
+- The `description` guard handles `cond && 'text'` patterns that may evaluate to `false`, preventing empty `<p>` elements from adding unwanted vertical gap
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/layout/.title-block.md b/openframe-frontend-core/src/components/layout/.title-block.md
index cd4a38c32..ae9d15d88 100644
--- a/openframe-frontend-core/src/components/layout/.title-block.md
+++ b/openframe-frontend-core/src/components/layout/.title-block.md
@@ -1,21 +1,28 @@
-<!-- source-hash: ff0ecf9e6a81a5b5db96e020586aff9d -->
-A client-side page header component that renders a title, optional subtitle, entity image, back button, and action controls in a responsive layout.
+<!-- source-hash: 6ec937ab0916481fee0c43b56587e4bb -->
+A reusable page header component that renders a title, optional subtitle, entity image, back button, and action controls in a responsive layout.
 
 ## Key Components
 
-- **`TitleBlockProps`** — Interface defining all configurable props including title, subtitle, image, navigation, actions, and visual variant
-- **`TitleBlock`** — Main exported component handling layout for page-level headings with responsive behavior (`plain` vs `card` variants)
-- **`variant`** — Controls visual treatment: `plain` (default, transparent) collapses `card` style (bordered, padded) on `md+` breakpoints
+**`TitleBlockProps`** — Interface defining all configurable props:
+- `title` / `subtitle` — Primary and secondary heading text
+- `image` — Entity image with `src` and `alt`
+- `backButton` — Back navigation with optional label and click handler
+- `actions` / `menuActions` — Action buttons or grouped menu actions passed to `PageActions`
+- `actionsVariant` — Controls button rendering style (`icon-buttons`, `primary-buttons`, `menu-primary`)
+- `selector` — Desktop-only slot (e.g. `TabSelector`) rendered alongside actions
+- `variant` — `plain` (default, transparent) or `card` (bordered/padded on mobile, collapses on `md+`)
+
+**`TitleBlock`** — Main exported component with responsive flex layout that stacks vertically on `md` and returns to horizontal on `lg`.
 
 ## Usage Example
 
 ```typescript
-import { TitleBlock } from './title-block'
+import { TitleBlock } from '@/components/layout/title-block'
 
 // Basic usage
 <TitleBlock
-  title="Devices"
-  subtitle="Manage all enrolled devices"
+  title="Managed Devices"
+  subtitle="All enrolled endpoints"
   backButton={{ label: 'Back', onClick: () => router.back() }}
   actions={[
     { label: 'Add Device', icon: PlusIcon, onClick: handleAdd },
@@ -23,20 +30,14 @@ import { TitleBlock } from './title-block'
   actionsVariant="primary-buttons"
 />
 
-// With entity image and card variant (e.g. mobile-first detail pages)
+// With entity image and card variant (mobile)
 <TitleBlock
+  variant="card"
   title="Acme Corp"
-  subtitle="Enterprise Client"
+  subtitle="Enterprise client"
   image={{ src: '/logos/acme.png', alt: 'Acme Corp' }}
-  variant="card"
-  actions={[{ label: 'Edit', icon: EditIcon, onClick: handleEdit }]}
-  menuActions={[{ label: 'More', items: [...] }]}
-  selector={<TabSelector tabs={tabs} />}
+  menuActions={[
+    { label: 'Settings', items: [{ label: 'Edit', onClick: handleEdit }] },
+  ]}
 />
-```
-
-## Notes
-
-- The `selector` slot (e.g. a `TabSelector`) is desktop-only and rendered alongside actions
-- Back button is hidden on mobile (`hidden md:inline-flex`)
-- Title truncates with `title` attribute tooltip when content overflows
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.card-skeleton.md b/openframe-frontend-core/src/components/loading/.card-skeleton.md
index 336f96c27..2c7453f73 100644
--- a/openframe-frontend-core/src/components/loading/.card-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.card-skeleton.md
@@ -1,54 +1,51 @@
-<!-- source-hash: b4a4c7c8c54bac836e374bc9dd198d5b -->
+<!-- source-hash: 762e95c95557a2590f5c70724bc5d5af -->
 Reusable skeleton loading components for card UI elements, providing animated placeholder states that match the structure of vendor, blog, category, and alternative card layouts.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `CardSkeleton` | Single card skeleton with variant-based layout rendering |
-| `CardSkeletonGrid` | Responsive grid of `CardSkeleton` instances for list loading states |
-| `CardSkeletonProps` | Interface defining variant, visibility toggles, and styling options |
+**`CardSkeleton`** — Main export. Renders a single card skeleton with configurable variant and display options. Accepts `role="status"` and `aria-label` for accessibility.
 
-**Internal sub-components (not exported):**
+**`CardSkeletonGrid`** — Renders a responsive grid of `CardSkeleton` instances. Grid columns adapt automatically per variant.
+
+**Internal Content Components** (not exported):
 
 | Component | Mirrors |
-|-----------|---------|
-| `VendorCardContent` | Logo, title, category, description, stats, and tag |
-| `BlogCardContent` | OG image, title chips, description, author, and date metadata |
-| `CategoryCardContent` | Icon grid, title, description, and action button |
-| `AlternativeCardContent` | Avatar, title, description, and optional action button |
+|---|---|
+| `VendorCardContent` | Vendor cards with logo, title, stats, and tag |
+| `BlogCardContent` | Blog cards with OG image, chips, description, author, and date |
+| `CategoryCardContent` | Category cards with icon grid and action button |
+| `AlternativeCardContent` | Comparison list cards with avatar and description |
 
-## Usage Example
+## Props
 
 ```typescript
-import { CardSkeleton, CardSkeletonGrid } from "./card-skeleton"
+interface CardSkeletonProps {
+  variant?: 'vendor' | 'blog' | 'category' | 'alternative' // default: 'vendor'
+  showActions?: boolean    // default: true
+  showMetadata?: boolean   // default: true
+  className?: string
+  containerClassName?: string
+}
+```
 
-// Single skeleton while fetching one vendor
-<CardSkeleton variant="vendor" showActions showMetadata />
+## Usage Example
 
-// Full loading grid for a blog listing page
-<CardSkeletonGrid
-  variant="blog"
-  count={4}
-  showActions={false}
-  showMetadata
-  className="my-8"
-/>
+```typescript
+// Single card skeleton
+<CardSkeleton variant="blog" showMetadata={true} />
 
-// Category grid without custom container styling
+// Grid of vendor card skeletons
 <CardSkeletonGrid
-  variant="category"
-  count={8}
-  containerClassName="bg-neutral-900 border border-neutral-700"
+  count={6}
+  variant="vendor"
+  containerClassName="bg-white border border-gray-200"
 />
-```
 
-## Props Reference
+// Category grid (4-column on large screens)
+<CardSkeletonGrid count={4} variant="category" />
+
+// Alternative cards (single column, no actions)
+<CardSkeletonGrid count={3} variant="alternative" showActions={false} />
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'vendor' \| 'blog' \| 'category' \| 'alternative'` | `'vendor'` | Card layout to replicate |
-| `showActions` | `boolean` | `true` | Renders action button placeholder |
-| `showMetadata` | `boolean` | `true` | Renders footer metadata placeholder |
-| `containerClassName` | `string` | `bg-ods-card border border-ods-border` | Overrides card container background and border |
-| `count` *(grid only)* | `number` | `6` | Number of skeleton cards to render |
\ No newline at end of file
+> Uses `UnifiedSkeleton` primitives (`TextSkeleton`, `MediaSkeleton`, `InteractiveSkeleton`) to ensure consistent pulse animations across all card types.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.device-card-skeleton.md b/openframe-frontend-core/src/components/loading/.device-card-skeleton.md
index 88b55465d..70b5c3ff9 100644
--- a/openframe-frontend-core/src/components/loading/.device-card-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.device-card-skeleton.md
@@ -1,47 +1,38 @@
-<!-- source-hash: 778a7f2774363f614672d36f1704ffb9 -->
-Loading skeleton component that mimics the exact layout of a `DeviceCard` to prevent layout shifts during data fetching.
+<!-- source-hash: 54aa570e451e331c157161933707661b -->
+Loading skeleton component that mimics the exact layout of `DeviceCard` during data fetching, preventing layout shifts with matching dimensions and animated placeholders.
 
 ## Key Components
 
-### `DeviceCardSkeleton`
-A single animated placeholder card matching the three-row `DeviceCard` structure:
-- **Row 1:** Device icon + device name + more button
-- **Row 2:** OS badge + organization icon + organization name
-- **Row 3:** Status badge + last seen timestamp
+| Export | Type | Description |
+|--------|------|-------------|
+| `DeviceCardSkeleton` | Component | Single card skeleton matching DeviceCard's 3-row layout |
+| `DeviceCardSkeletonGrid` | Component | Responsive grid of `DeviceCardSkeleton` instances |
+| `DeviceCardSkeletonProps` | Interface | Props for `DeviceCardSkeleton` (`className?`) |
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `className` | `string?` | Additional CSS classes |
+**Layout rows matched by `DeviceCardSkeleton`:**
+- **Row 1** — Device icon + device name + more button
+- **Row 2** — OS badge + organization icon + organization name
+- **Row 3** — Status badge + last seen timestamp
 
-### `DeviceCardSkeletonGrid`
-Renders a responsive grid of `DeviceCardSkeleton` instances, matching the `DevicesGrid` responsive column layout.
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `count` | `number?` | `12` | Number of skeleton cards to render |
-| `className` | `string?` | — | Additional CSS classes |
-
-**Responsive columns:** 1 → 2 (md) → 4 (lg)
+**`DeviceCardSkeletonGrid` responsive columns:**
+- Mobile: 1 col · Tablet (`md`): 2 cols · Desktop (`lg`/`xl`): 4 cols
 
 ## Usage Example
 
 ```typescript
-// Single skeleton card
+// Single skeleton (e.g., while one card is loading)
 import { DeviceCardSkeleton } from "./device-card-skeleton"
 
-function DeviceDetailLoader() {
-  return <DeviceCardSkeleton className="max-w-sm" />
-}
+<DeviceCardSkeleton className="my-custom-class" />
 
-// Full grid during page load
+// Grid skeleton (e.g., full page loading state)
 import { DeviceCardSkeletonGrid } from "./device-card-skeleton"
 
-function DevicesPage({ isLoading, devices }) {
-  if (isLoading) {
-    return <DeviceCardSkeletonGrid count={8} />
-  }
-  return <DevicesGrid devices={devices} />
-}
+// Default: renders 12 skeleton cards
+<DeviceCardSkeletonGrid />
+
+// Custom count
+<DeviceCardSkeletonGrid count={8} className="p-4" />
 ```
 
-> Both components include ARIA attributes (`role="status"` and `aria-label`) for screen reader accessibility during loading states.
\ No newline at end of file
+Both components include `role="status"` and `aria-label` for accessible loading announcements, and use `animate-pulse` on placeholder elements for visual feedback.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.margin-report-skeleton.md b/openframe-frontend-core/src/components/loading/.margin-report-skeleton.md
index 0e9bae14d..0822457a1 100644
--- a/openframe-frontend-core/src/components/loading/.margin-report-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.margin-report-skeleton.md
@@ -1,54 +1,48 @@
-<!-- source-hash: a465f87f85ec79ae37576015929fe094 -->
-A full-page loading skeleton for the Margin Report view, rendering animated placeholder blocks that mirror the report's layout sections while optionally displaying an overlay with a CTA or status message.
+<!-- source-hash: 127fb87dc40adf3f8c34a96c4df3de81 -->
+A loading skeleton placeholder component for the Margin Report page, rendering animated grey block placeholders that mirror the full report layout while data is being fetched.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `MarginReportSkeleton` | `React.FC` | Main skeleton component with pulse animation and optional overlay |
-| `MarginReportSkeletonProps` | `interface` | Props contract for the skeleton component |
+### `MarginReportSkeleton`
+Main export. Renders a full-page skeleton UI with optional pulse animation and overlay support.
 
-### Props
+**Props (`MarginReportSkeletonProps`):**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `animate` | `boolean` | `true` | Toggles CSS `animate-pulse` on the root element |
-| `description` | `React.ReactNode` | — | Explanatory text rendered above the overlay content |
-| `overlayContent` | `React.ReactNode` | — | Node rendered in a centered fixed overlay (e.g. button, spinner) |
-
-### Skeleton Sections Rendered
-
-```text
-├── Header (title + subtitle bars)
-├── Summary cards (3-column grid)
-├── MSP Profile + Report Info (2-column grid)
-├── Vendor lists — Commercial & Open-Source stacks (2-column, 5 rows each)
-├── Strategic Recommendations header + cards (3-column grid)
-└── OpenFrame value section (header + 3 value cards)
-```
+| `animate` | `boolean` | `true` | Enables CSS `animate-pulse` on the skeleton blocks |
+| `description` | `React.ReactNode` | — | Optional heading text shown inside the overlay |
+| `overlayContent` | `React.ReactNode` | — | Optional node (button, spinner, etc.) centered over the skeleton via a fixed overlay |
+
+**Skeleton sections rendered (in order):**
+- Page header (title + subtitle bars)
+- 3-column summary cards
+- MSP Profile + Report Info cards (2-column)
+- Commercial Stack & Open-Source Stack vendor lists (5 rows each)
+- Strategic Recommendations header + 3-card grid
+- OpenFrame value section (header + 3-card grid)
 
 ## Usage Example
 
 ```typescript
-// Basic animated skeleton while data loads
+import { MarginReportSkeleton } from './margin-report-skeleton';
+
+// Basic loading state
 <MarginReportSkeleton />
 
-// Static skeleton with a gated CTA overlay
+// With overlay CTA while report is being generated
 <MarginReportSkeleton
-  animate={false}
-  description="Generate your free Margin Report to unlock insights."
+  animate={true}
+  description="Your margin report is being generated…"
   overlayContent={
-    <Button onClick={handleGenerate}>
+    <button onClick={handleGenerateReport}>
       Generate Report
-    </Button>
+    </button>
   }
 />
 
-// Skeleton with a loading spinner overlay
-<MarginReportSkeleton
-  description="Calculating your margins…"
-  overlayContent={<Spinner size="lg" />}
-/>
+// Static snapshot (no animation)
+<MarginReportSkeleton animate={false} />
 ```
 
-> **Note:** When `overlayContent` is provided, a semi-transparent overlay (`bg-ods-card/80`) covers the entire skeleton. The overlay content is viewport-centered via `fixed` positioning with pointer-events re-enabled only on the CTA container.
\ No newline at end of file
+> **Note:** The overlay (`overlayContent`) uses `position: fixed` centering so it stays visible regardless of scroll position. The backdrop uses `pointer-events-none` while the inner content restores `pointer-events-auto`, keeping the rest of the page non-interactive.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.organization-card-skeleton.md b/openframe-frontend-core/src/components/loading/.organization-card-skeleton.md
index a03f1f64e..442277f9e 100644
--- a/openframe-frontend-core/src/components/loading/.organization-card-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.organization-card-skeleton.md
@@ -1,46 +1,39 @@
-<!-- source-hash: 254d5d86afe2187734cde56c533fc995 -->
-Loading skeleton component that renders a placeholder matching the exact layout and dimensions of an `OrganizationCard`, preventing layout shifts during data fetching.
+<!-- source-hash: 42afed7b963d9c8db89ec0c7a70f20ee -->
+Loading skeleton component that renders a placeholder layout matching the `OrganizationCard` component's exact dimensions and structure, preventing layout shifts during data fetching.
 
 ## Key Components
 
 ### `OrganizationCardSkeleton`
-Single card skeleton with three configurable sections:
-- **Header** — 60×60px org logo placeholder + title/subtitle text skeletons
-- **Description** — Fixed 48px height with two-line body text skeletons (toggled via `showDescription`)
-- **Footer** — Two stat items (icon + caption) and a tag/badge placeholder (toggled via `showFooter`)
+Single card skeleton with three optional sections:
+- **Header** — 60×60px org logo (`OrganizationIconSkeleton`) + title + subtitle text placeholders
+- **Description** — Fixed 48px height, 2-line body text placeholders (toggled via `showDescription`)
+- **Footer** — Icon+caption stat pairs and a tag/badge placeholder (toggled via `showFooter`)
 
 ### `OrganizationCardSkeletonGrid`
-Renders a responsive grid of `OrganizationCardSkeleton` instances:
-- Mobile: 1 column | Tablet (`md`): 2 columns | Desktop (`lg`): 3 columns
+Renders `count` skeleton cards in a responsive grid (1 → 2 → 3 columns across mobile/tablet/desktop).
 
 ### `OrganizationCardSkeletonProps`
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | — | Additional CSS classes |
-| `containerClassName` | `string` | — | Overrides card background & border |
-| `showFooter` | `boolean` | `true` | Renders footer stats area |
-| `showDescription` | `boolean` | `true` | Renders description area |
+|---|---|---|---|
+| `className` | `string` | — | Extra classes on the card wrapper |
+| `containerClassName` | `string` | — | Overrides card background/border classes |
+| `showFooter` | `boolean` | `true` | Renders the stats/badge footer row |
+| `showDescription` | `boolean` | `true` | Renders the description block |
 
 ## Usage Example
 
 ```typescript
-// Single card skeleton
+// Single skeleton card
 <OrganizationCardSkeleton
-  showDescription={true}
   showFooter={true}
+  showDescription={false}
+  containerClassName="bg-white border border-gray-200"
 />
 
-// Full grid skeleton during data load
+// Full grid while loading
 <OrganizationCardSkeletonGrid
   count={9}
   showFooter={true}
-  showDescription={false}
-  className="my-4"
-/>
-
-// Custom container styling
-<OrganizationCardSkeleton
-  containerClassName="bg-gray-900 border border-gray-700"
-  showFooter={false}
+  showDescription={true}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.organization-icon-skeleton.md b/openframe-frontend-core/src/components/loading/.organization-icon-skeleton.md
index 2f3ffcbf5..7364a3bef 100644
--- a/openframe-frontend-core/src/components/loading/.organization-icon-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.organization-icon-skeleton.md
@@ -1,41 +1,41 @@
-<!-- source-hash: 31726d42ed65c56efadaa8abd3f2fc5b -->
-A React skeleton loading component that provides visual placeholders for organization icons while data is loading, ensuring consistent layout and preventing visual jumps during loading states.
+<!-- source-hash: 45999614de7204fe66e3d0b2ca239d81 -->
+A loading skeleton placeholder component that mirrors the exact dimensions and styling of `OrganizationIcon`/`VendorIcon` to prevent layout shifts during data loading states.
 
 ## Key Components
 
-- **OrganizationIconSkeleton**: Main skeleton component with configurable size, background, and styling options
-- **OrganizationIconSkeletonProps**: TypeScript interface defining component props including size variants, styling options, and accessibility features
-- **sizeClasses**: Size mapping object that matches OrganizationIcon dimensions exactly (xs: 24px to xl: 64px)
-- **backgroundClasses**: Background style variants (dark, light, white) for different UI contexts
+**`OrganizationIconSkeleton`** — Main exported component that renders an animated pulse placeholder.
+
+**`OrganizationIconSkeletonProps`** — Interface defining:
+- `size` — Six size variants (`xs`→`xl`) matching `OrganizationIcon` pixel dimensions exactly
+- `showBackground` — Toggles the container border/background wrapper (default: `true`)
+- `backgroundStyle` — Three background themes: `dark`, `light`, `white` (default: `dark`)
+- `className` — Additional Tailwind classes for overrides
+
+**`sizeClasses`** — Internal map of size tokens to Tailwind dimension classes (`w-6 h-6` through `w-16 h-16`)
+
+**`backgroundClasses`** — Internal map of background style tokens to ODS design token classes
 
 ## Usage Example
 
 ```typescript
-import { OrganizationIconSkeleton } from './organization-icon-skeleton'
-
-// Basic usage in a table (default md size)
+// Default (md, dark background) — organizations table / dashboard
 <OrganizationIconSkeleton />
 
-// Device card with smaller size
-<OrganizationIconSkeleton size="sm" backgroundStyle="light" />
-
-// Detail view with large size
-<OrganizationIconSkeleton 
-  size="xl" 
-  backgroundStyle="white"
-  className="shadow-sm"
-/>
-
-// Without background container
-<OrganizationIconSkeleton 
-  size="lg" 
-  showBackground={false}
-/>
-
-// Loading list with multiple skeletons
-{Array.from({ length: 3 }).map((_, i) => (
-  <OrganizationIconSkeleton key={i} size="md" />
-))}
+// Devices table
+<OrganizationIconSkeleton size="sm" />
+
+// Detail view
+<OrganizationIconSkeleton size="xl" />
+
+// Light card background
+<OrganizationIconSkeleton size="md" backgroundStyle="light" />
+
+// No background container (bare skeleton)
+<OrganizationIconSkeleton size="sm" showBackground={false} />
 ```
 
-The component includes proper ARIA labels for accessibility and uses CSS animations for the pulsing skeleton effect. It maintains exact visual parity with the actual OrganizationIcon component to ensure seamless loading transitions.
\ No newline at end of file
+## Notes
+
+- Renders with `role="status"` and `aria-label` for screen reader accessibility
+- Inner pulse element is sized at 50% (`w-1/2 h-1/2`) of the container, matching icon inner content proportions
+- Drop-in replacement wherever `OrganizationIcon` or `VendorIcon` appears in skeleton screens
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.page-layout-skeleton.md b/openframe-frontend-core/src/components/loading/.page-layout-skeleton.md
index 52b4dbcfe..1d69d019a 100644
--- a/openframe-frontend-core/src/components/loading/.page-layout-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.page-layout-skeleton.md
@@ -1,20 +1,20 @@
-<!-- source-hash: d81e064ec80f99a3beddcfc15467f602 -->
-Skeleton loading components for the page layout, providing animated placeholders that match the structure of major UI sections including headers, heroes, sidebars, articles, and vendor detail pages.
+<!-- source-hash: 73a906eae8999ee28b4f79ffdf90cf75 -->
+Skeleton loading components for the page layout, providing animated placeholder UI that mirrors the structure of `AnnouncementBar`, `Header`, `Hero`, `Sidebar`, `Article`, and `Vendor Detail` sections during data fetching.
 
 ## Key Components
 
 | Export | Description |
 |--------|-------------|
-| `AnnouncementBarSkeleton` | Matches `AnnouncementBar` with logo, text lines, and close button placeholders |
-| `HeaderSkeleton` | Sticky header with logo, nav links, and action button skeletons |
-| `HeroSkeleton` | Full-width hero section with title, subtitle, and CTA placeholders |
-| `SearchContainerSkeleton` | Search input with optional filter chip row |
-| `CategorySidebarSkeleton` | Sidebar mimicking `MultiLevelNavigation` with folder/file icons and README badges |
+| `AnnouncementBarSkeleton` | Animated placeholder matching the `AnnouncementBar` component (logo, text, close button) |
+| `HeaderSkeleton` | Sticky header skeleton with logo, nav links, and action buttons (responsive) |
+| `HeroSkeleton` | Full-width hero section with title, subtitle, and CTA button placeholders |
+| `SearchContainerSkeleton` | Search input + optional filter chip row |
+| `CategorySidebarSkeleton` | 11-item nav skeleton matching `MultiLevelNavigation` (folder/file icons, README badges, chevrons) |
 | `BreadcrumbSkeleton` | Horizontal breadcrumb trail with separator dots |
-| `ResultsHeaderSkeleton` | Results count and sort controls placeholder |
-| `TwoColumnLayoutSkeleton` | Responsive grid wrapper accepting custom sidebar/main content with configurable `sidebarPosition` |
-| `ArticleLayoutSkeleton` | Full article page skeleton with header, featured image, and paragraph blocks |
-| `VendorDetailLayoutSkeleton` | Vendor detail page with breadcrumb, hero logo/title area, and responsive layout |
+| `ResultsHeaderSkeleton` | Result count / sort bar placeholder |
+| `TwoColumnLayoutSkeleton` | Composable two-column grid (sidebar + main); supports `left`/`right` sidebar position |
+| `ArticleLayoutSkeleton` | Full article layout: tags, title, metadata, featured image, 12-paragraph body |
+| `VendorDetailLayoutSkeleton` | Complete vendor detail page structure with breadcrumb, hero, and content areas |
 
 ## Usage Example
 
@@ -23,24 +23,31 @@ import {
   HeaderSkeleton,
   TwoColumnLayoutSkeleton,
   CategorySidebarSkeleton,
-} from "./page-layout-skeleton"
-
-// Drop-in loading state for a browse page
-function BrowsePage() {
-  if (isLoading) {
-    return (
-      <>
-        <HeaderSkeleton />
-        <TwoColumnLayoutSkeleton
-          sidebarContent={<CategorySidebarSkeleton />}
-          sidebarPosition="left"
-        />
-      </>
-    )
-  }
-  return <ActualContent />
+  ArticleLayoutSkeleton,
+} from "@/components/skeletons/page-layout-skeleton"
+
+// Simple page shell while data loads
+function LoadingPage() {
+  return (
+    <>
+      <HeaderSkeleton />
+      <TwoColumnLayoutSkeleton
+        sidebarPosition="left"
+        sidebarContent={<CategorySidebarSkeleton />}
+      />
+    </>
+  )
+}
+
+// Article page loading state
+function LoadingArticle() {
+  return <ArticleLayoutSkeleton className="px-4" />
+}
+
+// Search page with filters disabled
+function LoadingSearch() {
+  return <SearchContainerSkeleton showFilters={false} className="my-6" />
 }
+```
 
-// Inline search skeleton with filters hidden
-<SearchContainerSkeleton showFilters={false} className="my-4" />
-```
\ No newline at end of file
+All components accept an optional `className` prop for layout overrides and internally use `UnifiedSkeleton`, `TextSkeleton`, `MediaSkeleton`, and `InteractiveSkeleton` primitives for consistent pulse animations.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/loading/.users-grid-skeleton.md b/openframe-frontend-core/src/components/loading/.users-grid-skeleton.md
index 4b8b8aa9b..9bcf327ff 100644
--- a/openframe-frontend-core/src/components/loading/.users-grid-skeleton.md
+++ b/openframe-frontend-core/src/components/loading/.users-grid-skeleton.md
@@ -1,45 +1,34 @@
-<!-- source-hash: b81e47a927a9ff4d5803ff0d1171b304 -->
-A skeleton loading component that displays a placeholder table structure while user data is being fetched, providing visual feedback during loading states.
+<!-- source-hash: 202f8061fbc5ae731343adc15e766d13 -->
+A loading skeleton component for the users grid table, rendering animated placeholder rows while user data is being fetched.
 
 ## Key Components
 
-- **`UsersGridSkeleton`** - Main skeleton component that renders an animated placeholder table
-- **`Props`** interface defining:
-  - `rows` - Number of skeleton rows to display (defaults to 10)
-  - `className` - Optional additional CSS classes for styling
+**`UsersGridSkeleton`** — Default export component that renders a pulsing skeleton table with fixed column headers (`Name`, `Email`, `Role`, `Created`, `Last Sign-In`) and configurable placeholder rows.
 
-## Features
+**Props:**
 
-- **Responsive Design**: Horizontal scroll for mobile compatibility with `overflow-x-auto`
-- **Pulse Animation**: Built-in `animate-pulse` class for loading feedback
-- **Fixed Structure**: Matches actual users grid with 5 columns (Name, Email, Role, Created, Last Sign-In)
-- **Customizable Rows**: Configurable number of skeleton rows based on expected data size
-- **Theme Integration**: Uses ODS (design system) color tokens and styling
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rows` | `number` | `10` | Number of skeleton rows to render |
+| `className` | `string` | — | Additional CSS classes for the wrapper |
 
 ## Usage Example
 
 ```typescript
-import { UsersGridSkeleton } from './users-grid-skeleton'
-
 // Basic usage with default 10 rows
-function UsersList() {
-  const [loading, setLoading] = useState(true)
-  const [users, setUsers] = useState([])
-
-  if (loading) {
-    return <UsersGridSkeleton />
-  }
-
-  return <UsersGrid users={users} />
-}
-
-// Custom row count and styling
-function AdminPanel() {
-  return (
-    <UsersGridSkeleton 
-      rows={5}
-      className="shadow-lg"
-    />
-  )
-}
-```
\ No newline at end of file
+<UsersGridSkeleton />
+
+// Custom row count while data loads
+{isLoading ? (
+  <UsersGridSkeleton rows={5} className="mt-4" />
+) : (
+  <UsersGrid users={users} />
+)}
+```
+
+## Notes
+
+- Uses `animate-pulse` (Tailwind) for the shimmer effect
+- Each row renders 5 cells matching the 5 column headers
+- Styled with ODS design tokens (`ods-border`, `ods-card`, `ods-text-primary`) ensuring consistency with the live users table
+- `cn()` utility allows safe class merging for layout overrides
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/navigation/.app-header.md b/openframe-frontend-core/src/components/navigation/.app-header.md
index ba749602b..5b55d9949 100644
--- a/openframe-frontend-core/src/components/navigation/.app-header.md
+++ b/openframe-frontend-core/src/components/navigation/.app-header.md
@@ -1,58 +1,55 @@
-<!-- source-hash: 898258d76810df35b3a9175ed9b09824 -->
-Responsive application header component for the OpenFrame platform, providing navigation controls, search, organization filtering, notifications, and user account management across mobile and desktop breakpoints.
+<!-- source-hash: 5b94bf019e6894a9329ab1fd93c4be25 -->
+Responsive application header component for the OpenFrame platform, rendering navigation controls, search, organization filtering, notifications, user menu, and the Mingo AI launcher button.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `AppHeader` | `React.memo` component | Main header component with full prop-driven configuration |
-| `AppHeaderProps` | Interface | Full prop contract for the header |
-| `NotificationsHeaderButton` | Internal component | Bell icon button with unread badge, integrates with `NotificationsContext` |
+### `AppHeader` (default export)
+A memoized React component that composes all header sections with responsive behavior — mobile shows a burger menu and logo, desktop shows the full control bar.
 
-## Props Overview
+### `AppHeaderProps`
+Full interface for configuring header features. Key props:
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `isMobileMenuOpen` | `boolean` | Required; controls burger menu icon state |
-| `onToggleMobileMenu` | `() => void` | Callback to toggle the mobile sidebar |
-| `disabled` | `boolean` | Dims all controls except the mobile burger toggle |
-| `showSearch` | `boolean` | Renders global search (desktop) or search button (mobile) |
-| `showOrganizations` | `boolean` | Renders org filter dropdown (large screens only) |
-| `showNotifications` | `boolean` | Renders notification bell with unread badge |
-| `showUser` | `boolean` | Renders user avatar + dropdown (desktop only) |
+| `showSearch` | `boolean` | Enables global search (desktop full-bar, mobile icon) |
+| `showOrganizations` | `boolean` | Renders org filter (desktop `lg+` only) |
+| `showNotifications` | `boolean` | Bell icon with unread dot indicator |
+| `showMingoAI` | `boolean` | Mingo AI drawer launcher button |
+| `isMingoAIActive` | `boolean` | Visual pressed state for Mingo button |
+| `isMobileMenuOpen` | `boolean` | Controls burger/X icon toggle |
+| `disabled` | `boolean` | Dims all controls except the mobile burger |
+
+### `NotificationsHeaderButton` (internal)
+Connects to `NotificationsContext` via `useOptionalNotifications()`, falling back to the `fallbackUnreadCount` prop when no context provider is present.
 
 ## Usage Example
 
 ```typescript
-import { AppHeader } from './app-header'
-
-export function Shell() {
-  const [mobileOpen, setMobileOpen] = React.useState(false)
-
-  return (
-    <AppHeader
-      isMobileMenuOpen={mobileOpen}
-      onToggleMobileMenu={() => setMobileOpen(prev => !prev)}
-      showSearch
-      onSearch={(query) => console.log(query)}
-      showOrganizations
-      organizations={[{ id: 'org-1', name: 'Acme Corp' }]}
-      selectedOrgId="org-1"
-      onOrgChange={(id) => console.log(id)}
-      showNotifications
-      unreadCount={3}
-      showUser
-      userName="Jane Doe"
-      userEmail="jane@acme.com"
-      onProfile={() => router.push('/profile')}
-      onLogout={() => signOut()}
-    />
-  )
-}
+<AppHeader
+  showSearch
+  onSearch={(query) => console.log(query)}
+  showOrganizations
+  organizations={[{ id: 'org-1', name: 'Acme Corp' }]}
+  selectedOrgId="org-1"
+  onOrgChange={(id) => setSelectedOrg(id)}
+  showNotifications
+  unreadCount={3}
+  showMingoAI
+  onMingoAI={() => setDrawerOpen(true)}
+  isMingoAIActive={isDrawerOpen}
+  showUser
+  userName="Jane Doe"
+  userEmail="jane@acme.com"
+  onProfile={() => router.push('/profile')}
+  onLogout={handleLogout}
+  isMobileMenuOpen={mobileMenuOpen}
+  onToggleMobileMenu={() => setMobileMenuOpen(v => !v)}
+/>
 ```
 
 ## Behavior Notes
 
-- **Responsive layout:** Mobile renders a burger icon + logo; desktop shows the full search bar and org filter
-- **Disabled state:** Setting `disabled={true}` applies `pointer-events-none opacity-50` to all controls except the mobile menu toggle
-- **Notifications:** Prefers live unread count from `NotificationsContext` when available, falls back to the `unreadCount` prop; switches between `BellIcon` and `BellRingingIcon` based on count
\ No newline at end of file
+- Uses `useMdUp()` to switch between mobile (`h-12`) and desktop (`h-14`) layouts
+- The `disabled` prop sets `pointer-events-none opacity-50` on all controls **except** the mobile burger toggle
+- Mingo AI button renders icon-only on mobile, full label on desktop (`md+`)
+- User dropdown is desktop-only (`md+`); displays avatar, name, email, profile link, and logout
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/navigation/.app-layout-drawer.md b/openframe-frontend-core/src/components/navigation/.app-layout-drawer.md
new file mode 100644
index 000000000..520c2e8e1
--- /dev/null
+++ b/openframe-frontend-core/src/components/navigation/.app-layout-drawer.md
@@ -0,0 +1,49 @@
+<!-- source-hash: 40775cd6c3c3200e16a7006537baa864 -->
+A layout-aware drawer component that renders **inside** the `AppLayout` content area (not as a viewport-level overlay), keeping the header and sidebar visible and interactive while the drawer is open.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `AppLayoutDrawerRoot` | Root wrapper; manages controlled/uncontrolled open state and exposes it via `DrawerOpenContext`. Forces `modal={false}` by default. |
+| `AppLayoutDrawerTrigger` | Alias of `DialogPrimitive.Trigger` |
+| `AppLayoutDrawerClose` | Alias of `DialogPrimitive.Close` |
+| `appLayoutDrawerVariants` | CVA variants for the outer wrapper — handles side (left/right/top/bottom), flush mode, and slide animations using `absolute` positioning. |
+| `appLayoutDrawerPanelVariants` | CVA variants for the inner panel — controls borders, rounding, padding, and flush breakpoint behavior. |
+| `AppLayoutDrawerResizeHandle` | Drag/keyboard-accessible resize handle; supports pointer capture, directional arrow keys, and Home/End shortcuts. |
+| `useContainedResizableSize` | Hook that tracks container dimensions via `ResizeObserver`, clamps drawer size to available space, and persists size to `localStorage`. |
+
+## Usage Example
+
+```typescript
+import {
+  AppLayoutDrawerRoot,
+  AppLayoutDrawerTrigger,
+  AppLayoutDrawerClose,
+} from "./app-layout-drawer"
+
+function MyPanel() {
+  return (
+    <AppLayoutDrawerRoot>
+      <AppLayoutDrawerTrigger asChild>
+        <button>Open Details</button>
+      </AppLayoutDrawerTrigger>
+
+      {/* Content portal targets AppLayout container, not document.body */}
+      <AppLayoutDrawerContent side="right" resizable storageKey="my-drawer-width">
+        <DrawerHeader>
+          <DrawerTitle>Details</DrawerTitle>
+        </DrawerHeader>
+        <DrawerBody>Panel content here</DrawerBody>
+        <DrawerFooter>
+          <AppLayoutDrawerClose asChild>
+            <button>Close</button>
+          </AppLayoutDrawerClose>
+        </DrawerFooter>
+      </AppLayoutDrawerContent>
+    </AppLayoutDrawerRoot>
+  )
+}
+```
+
+> **Key behavioral difference from standard `Drawer`:** Uses `absolute` positioning clipped to the layout container and `modal={false}` so header/sidebar remain interactive. A custom overlay div is rendered manually (since Radix's `DialogPrimitive.Overlay` returns `null` in non-modal mode) to prevent click-through flicker on trigger elements.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/navigation/.app-layout.md b/openframe-frontend-core/src/components/navigation/.app-layout.md
index cebcf2640..9f6f802a8 100644
--- a/openframe-frontend-core/src/components/navigation/.app-layout.md
+++ b/openframe-frontend-core/src/components/navigation/.app-layout.md
@@ -1,39 +1,34 @@
-<!-- source-hash: 4a7aa4db8bec1fcce07d28f27fea4092 -->
-Orchestrates the top-level application shell, combining the sidebar, header, mobile menu, and notification drawer into a single full-screen layout with managed mobile menu state.
+<!-- source-hash: bb05b41e1eb3c487eae308af423755ac -->
+Provides the root application shell that composes the sidebar, header, mobile menu, notification drawer, and a portal-target container for layout-level drawers into a single responsive layout.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `AppLayout` | Component | Root layout wrapper rendering all chrome elements and the main content area |
-| `AppLayoutProps` | Interface | Configuration interface for the layout component |
-
-**Key props:**
-- `sidebarConfig` — Navigation structure passed to both `NavigationSidebar` and `MobileBurgerMenu`
-- `headerProps` — Forwarded to `AppHeader` (mobile menu state/toggle are managed internally)
-- `mobileBurgerMenuProps` — Forwarded to `MobileBurgerMenu` (open/close/config are managed internally)
-- `disabled` — Freezes header and sidebar interactions without affecting `children`
-- `loadingFallback` — Custom `Suspense` fallback for the main content area
+| `AppLayout` | Component | Root layout shell combining sidebar, header, mobile menu, and main content area |
+| `AppLayoutProps` | Interface | Props contract for `AppLayout` |
+| `useAppLayoutDrawerContainer` | Hook | Returns the `HTMLElement` portal target for `AppLayoutDrawer`; `null` when used outside `AppLayout` |
+| `AppLayoutDrawerContainerContext` | Context | Internal context exposing the drawer portal container `div` to descendant drawer components |
 
 ## Usage Example
 
 ```typescript
-import { AppLayout } from './app-layout'
-import { sidebarConfig } from '../config/navigation'
+import { AppLayout, AppLayoutDrawer } from '@/components/layout'
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <AppLayout
-      sidebarConfig={sidebarConfig}
+      sidebarConfig={navigationConfig}
       headerProps={{
         logo: <Logo />,
         actions: <UserMenu />,
       }}
       mobileBurgerMenuProps={{
-        footerContent: <SupportLink />,
+        appName: 'Flamingo',
       }}
       loadingFallback={<PageSkeleton />}
       mainClassName="p-6"
+      drawer={<AppLayoutDrawer />}
     >
       {children}
     </AppLayout>
@@ -41,8 +36,22 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+## Layout Structure
+
+```mermaid
+graph TD
+    A["AppLayout"] --> B["NavigationSidebar"]
+    A --> C["MobileBurgerMenu"]
+    A --> D["Main Content Area"]
+    D --> E["AppHeader"]
+    D --> F["NotificationDrawer"]
+    D --> G["DrawerContainer (portal target)"]
+    G --> H["main > Suspense > children"]
+    G --> I["drawer slot"]
+```
+
 ## Notes
 
-- Mobile menu open/close state is fully self-contained — consumers only provide content-level props via `mobileBurgerMenuProps`
-- `children` are wrapped in `Suspense`, enabling async page transitions out of the box
-- `disabled` is intended for loading or onboarding states where navigation should be temporarily locked
\ No newline at end of file
+- The `drawerContainer` ref is exposed via context so drawer components can portal **into the main area only**, keeping the header and sidebar always visible and interactive.
+- The `disabled` prop freezes navigation chrome (links, header actions) without affecting `children` — useful during loading or multi-step flows.
+- Single newlines inside the main area use `overflow-hidden` to clip drawer slide-in animations and prevent layout overflow from propagating to `<html>`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/navigation/.header-mingo-button.md b/openframe-frontend-core/src/components/navigation/.header-mingo-button.md
new file mode 100644
index 000000000..087ad3fce
--- /dev/null
+++ b/openframe-frontend-core/src/components/navigation/.header-mingo-button.md
@@ -0,0 +1,44 @@
+<!-- source-hash: 167c9c053052f1a347bb1bb0405477b2 -->
+Accessible "Mingo AI" launcher button for `AppHeader`, toggling between a branded icon+wordmark view and a close (`X`) affordance based on active and display state.
+
+## Key Components
+
+### `HeaderMingoButton`
+Main exported component. Renders a styled `<button>` that integrates into the `AppHeader` via the shared `divide-x` divider contract.
+
+**Props (`HeaderMingoButtonProps`):**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isActive` | `boolean` | `false` | Reflects open drawer state; sets `aria-pressed` |
+| `iconOnly` | `boolean` | `false` | Hides "Mingo AI" wordmark, collapses to icon-square |
+| `className` | `string` | — | Additional Tailwind/CSS classes |
+| `...props` | `ButtonHTMLAttributes` | — | Passed through to the underlying `<button>` |
+
+**Rendering logic:**
+
+- **Default:** `MingoIcon` (ODS cyan accents) + `"Mingo AI"` bold wordmark
+- **`iconOnly + isActive`:** Swaps logo for `XmarkIcon`, sets `aria-label` to `"Close Mingo AI"`
+- **`iconOnly` only:** Shows `MingoIcon` alone, no wordmark
+
+## Usage Example
+
+```typescript
+import { HeaderMingoButton } from './header-mingo-button'
+
+// Full button — drawer closed
+<HeaderMingoButton onClick={openDrawer} />
+
+// Full button — drawer open
+<HeaderMingoButton isActive onClick={closeDrawer} />
+
+// Narrow viewport (icon-only, drawer open → shows X)
+<HeaderMingoButton
+  isActive
+  iconOnly
+  onClick={closeDrawer}
+  className="md:hidden"
+/>
+```
+
+> **Figma reference:** `7532:222103 — button-full`
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/navigation/.index.md b/openframe-frontend-core/src/components/navigation/.index.md
index 03f22c92e..2e431dbb3 100644
--- a/openframe-frontend-core/src/components/navigation/.index.md
+++ b/openframe-frontend-core/src/components/navigation/.index.md
@@ -1,65 +1,50 @@
-<!-- source-hash: c04d31cdc4af8b84cec9f6c825727d97 -->
-Main entry point for the navigation component library, providing a clean public API with comprehensive exports for headers, sidebars, mobile navigation, and layout components along with their TypeScript type definitions.
+<!-- source-hash: 81f258ead011042674ef42ac369437da -->
+Barrel export file (marked `"use client"`) that consolidates all navigation-related components, hooks, and types for the Flamingo/OpenFrame UI navigation system into a single public API.
 
 ## Key Components
 
-**Core Navigation Components:**
-- `Header` - Main header component with configuration support
-- `AppHeader` - Application-level header implementation  
-- `AppLayout` - Full page layout wrapper with navigation
-- `NavigationSidebar` - Primary sidebar navigation component
-
-**Mobile Navigation:**
-- `MobileNavPanel` - Mobile-optimized navigation panel
-- `MobileBurgerMenu` - Hamburger menu for mobile devices
-- `ClientOnlyHeader` - Header that only renders on client-side
-
-**Interactive Elements:**
-- `SlidingSidebar` - Animated sidebar with slide transitions
-- `StickySectionNav` - Section navigation with scroll tracking
-- `HeaderGlobalSearch` - Global search functionality in header
-- `HeaderOrganizationFilter` - Organization filtering component
-
-**Utility Components:**
-- `HeaderSkeleton` - Loading placeholder for header
-- `HeaderButton` - Styled button component for header actions
+| Export | Type | Description |
+|--------|------|-------------|
+| `Header` / `AppHeader` | Component | Primary and app-level header components |
+| `ClientOnlyHeader` | Component | Header rendered only on the client side |
+| `HeaderSkeleton` | Component | Loading placeholder for the header |
+| `MobileNavPanel` / `MobileBurgerMenu` | Component | Mobile navigation controls |
+| `SlidingSidebar` / `NavigationSidebar` | Component | Sidebar navigation variants |
+| `StickySectionNav` | Component | Sticky in-page section navigation |
+| `useSectionNavigation` | Hook | Controls active section tracking |
+| `AppLayout` | Component | Root layout wrapper with drawer support |
+| `useAppLayoutDrawerContainer` | Hook | Accesses the drawer container context |
+| `AppLayoutDrawer` + sub-components | Components | Compound drawer component (trigger, close, content, header, body, footer) |
+| `HeaderButton` / `HeaderMingoButton` | Component | Action buttons for the header bar |
+| `HeaderGlobalSearch` | Component | Global search trigger in the header |
+| `HeaderOrganizationFilter` | Component | Org-level filter control in the header |
 
 ## Usage Example
 
 ```typescript
-import { 
-  AppLayout, 
-  Header, 
+import {
+  AppLayout,
+  AppHeader,
   NavigationSidebar,
-  type AppLayoutProps,
-  type HeaderConfig 
+  AppLayoutDrawer,
+  AppLayoutDrawerTrigger,
+  AppLayoutDrawerContent,
+  useSectionNavigation,
 } from '@/components/navigation'
 
-// Basic layout setup
-function MyApp() {
-  const headerConfig: HeaderConfig = {
-    showSearch: true,
-    showOrgFilter: true
-  }
-
+export default function RootLayout({ children }) {
   return (
-    <AppLayout
-      header={<Header config={headerConfig} />}
-      sidebar={<NavigationSidebar items={navItems} />}
-    >
-      <main>Your app content</main>
+    <AppLayout>
+      <AppHeader>
+        <HeaderGlobalSearch />
+        <HeaderOrganizationFilter />
+        <HeaderMingoButton />
+      </AppHeader>
+      <NavigationSidebar />
+      {children}
     </AppLayout>
   )
 }
+```
 
-// Mobile-responsive header
-import { ClientOnlyHeader, MobileNavPanel } from '@/components/navigation'
-
-function ResponsiveHeader() {
-  return (
-    <ClientOnlyHeader>
-      <MobileNavPanel items={mobileNavItems} />
-    </ClientOnlyHeader>
-  )
-}
-```
\ No newline at end of file
+> All exports are client-only (`"use client"`). Avoid importing into Server Components directly — use dynamic imports or a server-side wrapper if needed.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/onboarding-guides/.index.md b/openframe-frontend-core/src/components/onboarding-guides/.index.md
new file mode 100644
index 000000000..609597593
--- /dev/null
+++ b/openframe-frontend-core/src/components/onboarding-guides/.index.md
@@ -0,0 +1,42 @@
+<!-- source-hash: 32d8ecb25777faace2a4b5a46e28428a -->
+Barrel export file for the **Onboarding Guides** product surface, exposing views, skeletons, and data-fetching hooks for OpenFrame's onboarding guide feature.
+
+## Key Components
+
+### Views
+- **`OnboardingGuidesCatalogView`** / **`OnboardingGuidesCatalogViewProps`** — Catalog listing view for browsing available onboarding guides
+- **`OnboardingGuideDetailView`** / **`OnboardingGuideDetailViewProps`** — Detail view for a single onboarding guide
+- **`OnboardingGuidesCatalogSkeleton`** — Loading skeleton for the catalog view
+
+### Hooks & Query Keys
+- **`useOnboardingGuides`** — Fetches the list of onboarding guides
+- **`useOnboardingGuide`** — Fetches a single onboarding guide by ID
+- **`useOnboardingGuideSections`** — Fetches sections for a specific guide
+- **`onboardingGuideKeys`** — React Query key factory for cache management
+
+## Usage Example
+
+```typescript
+import {
+  OnboardingGuidesCatalogView,
+  OnboardingGuideDetailView,
+  OnboardingGuidesCatalogSkeleton,
+  useOnboardingGuides,
+  useOnboardingGuide,
+  onboardingGuideKeys,
+} from '@flamingo-stack/openframe-frontend-core/components/onboarding-guides'
+
+// For row/entity types, import from the chat surface — NOT from here:
+import type { OnboardingGuide } from
+  '@flamingo-stack/openframe-frontend-core/components/chat'
+
+function GuideCatalog() {
+  const { data, isLoading } = useOnboardingGuides()
+  if (isLoading) return <OnboardingGuidesCatalogSkeleton />
+  return <OnboardingGuidesCatalogView guides={data} />
+}
+```
+
+## ⚠️ Important: Avoid Duplicate Re-exports
+
+Do **not** import `OnboardingGuide`, `OnboardingGuideFilters`, `OnboardingGuideListResponse`, or `OnboardingGuideSectionSummary` from this barrel. Those types are owned by `components/chat` — re-exporting them here triggers TypeScript **TS2308** (ambiguous re-export) at the top-level barrel.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guide-detail-view.md b/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guide-detail-view.md
new file mode 100644
index 000000000..55443ac41
--- /dev/null
+++ b/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guide-detail-view.md
@@ -0,0 +1,50 @@
+<!-- source-hash: d4580b096a14e84077fc0b2321af1d2e -->
+Renders the public-facing detail page for a single onboarding guide at `/onboarding-guides/<slug>`, supporting both SSR-controlled and self-fetching embed modes.
+
+## Key Components
+
+- **`OnboardingGuideDetailView`** — Main exported component. Displays guide title, author metadata, video player (Mux/MP4 or YouTube), markdown body, video bites, and related guides in the same section.
+- **`OnboardingGuideDetailViewProps`** — Interface controlling two operation modes:
+  - **Controlled/SSR**: pass `initialData` (pre-fetched `OnboardingGuide`)
+  - **Self-fetching**: pass `slug` + `guideEndpoint` factory; the component fetches its own data via `useSelfFetch`
+- **`useSelfFetch`** — Drives data loading; no-ops when `initialData` is provided.
+- **`useVideoWarmup`** — Pre-warms the video connection before playback.
+- **`resolveContentHref`** — Builds related-card hrefs via `runtime.composeContentUrl` or falls back to `basePath`.
+
+## Usage Example
+
+```typescript
+// SSR / controlled mode (hub pattern)
+const guide = await fetchGuide(params.slug)
+
+<OnboardingGuideDetailView
+  initialData={guide}
+  related={relatedGuides}
+  backHref="/getting-started"
+/>
+
+// Self-fetching / config-only embed (no host data layer)
+<OnboardingGuideDetailView
+  slug={params.slug}
+  guideEndpoint={(s) => `/content/api/onboarding-guides/${s}`}
+  related={[]}
+  basePath="/onboarding-guides"
+/>
+
+// Custom markdown renderer and related-card renderer
+<OnboardingGuideDetailView
+  initialData={guide}
+  MarkdownRenderer={MyMDXRenderer}
+  renderRelatedCard={(g) => <MyGuideCard guide={g} />}
+/>
+```
+
+## Render Sections (in order)
+
+1. Back navigation link
+2. Guide title (`h1`)
+3. Author card with section · step metadata
+4. Video player (skipped if no `main_video_url` or `youtube_url`)
+5. Markdown body via `MarkdownRenderer`
+6. Video bites strip
+7. Related guides (same section, filtered from `related` prop)
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-skeleton.md b/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-skeleton.md
new file mode 100644
index 000000000..e765d2e92
--- /dev/null
+++ b/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-skeleton.md
@@ -0,0 +1,28 @@
+<!-- source-hash: 5224e30a6e048fe30c89e1b8a4649bef -->
+Suspense fallback skeleton for the `/onboarding-guides` catalog page, rendering shimmer placeholders that mirror the loaded `<OnboardingGuidesCatalogView>` layout to prevent layout shift during data fetching.
+
+## Key Components
+
+- **`OnboardingGuidesCatalogSkeleton`** — Page-level skeleton component used as a `<Suspense>` fallback, composing:
+  - `<DevSectionPage sectionKey="onboarding">` — preserves hero, back button, and page scaffold
+  - `preControls` slot — reserves space for the search bar (`h-12`) and section pill row (`~74px`)
+  - `3` skeleton sections with `4 + 3 + 3 = 10` cards matching the typical onboarding dataset
+  - `<OnboardingGuideCardSkeleton size="catalog">` — per-card skeleton at `288px` height to eliminate per-card shift on resolve
+
+## Usage Example
+
+```typescript
+import { Suspense } from 'react'
+import { OnboardingGuidesCatalogSkeleton } from './onboarding-guides-catalog-skeleton'
+import { OnboardingGuidesCatalogView } from './onboarding-guides-catalog-view'
+
+export default function OnboardingGuidesPage() {
+  return (
+    <Suspense fallback={<OnboardingGuidesCatalogSkeleton />}>
+      <OnboardingGuidesCatalogView />
+    </Suspense>
+  )
+}
+```
+
+> **Layout shift guarantee:** The skeleton uses identical wrapper classes, section structure, and card heights as the loaded view. The `preControls` slot pre-allocates space for controls rendered post-load, ensuring a zero-shift Suspense → resolved transition.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-view.md b/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-view.md
new file mode 100644
index 000000000..7177da256
--- /dev/null
+++ b/openframe-frontend-core/src/components/onboarding-guides/.onboarding-guides-catalog-view.md
@@ -0,0 +1,40 @@
+<!-- source-hash: 756808054d616ac64d6d4def8dac5599 -->
+Public-facing catalog view for the `/onboarding-guides` route, supporting both SSR-controlled (hub) and self-fetching (config-only embed) data modes with section filtering and RAG-powered search.
+
+## Key Components
+
+- **`OnboardingGuidesCatalogView`** — Main export. Renders the guide grid, section filter pills, and `<DocSearchBar>`. Does NOT render page chrome (caller wraps in `<DevSectionPage>`).
+- **`OnboardingGuidesCatalogViewProps`** — Interface controlling data mode:
+  - *Controlled mode*: pass `initialGuides` + `initialSections` (server-fetched).
+  - *Self-fetch mode*: pass `guidesEndpoint` + `sectionsEndpoint` (client-fetched, refetches on `?section=` URL change).
+- **`useSelfFetch`** — Drives client-side data fetching when no initial data is provided.
+- **`useDocSearch`** — RAG search scoped to `onboarding-guides` table IDs.
+- **`grouped`** (memoized) — Buckets guides by section, sorted by `section_order` then `step_order`.
+- **`renderCard`** — Optional override for per-guide card rendering; defaults to `<OnboardingGuideCard>` with runtime-composed hrefs via `resolveContentHref`.
+
+## Usage Example
+
+```typescript
+// Controlled (SSR / hub) mode — host provides server-fetched data
+<OnboardingGuidesCatalogView
+  initialGuides={guides}
+  initialSections={sections}
+  initialSection={searchParams.section ?? ''}
+  basePath="/onboarding-guides"
+/>
+
+// Self-fetch (config-only embed) mode — view fetches its own data
+<OnboardingGuidesCatalogView
+  guidesEndpoint="/api/onboarding-guides"
+  sectionsEndpoint="/api/onboarding-guides/sections"
+  basePath="/onboarding-guides"
+/>
+
+// Custom card renderer override
+<OnboardingGuidesCatalogView
+  initialGuides={guides}
+  renderCard={(guide) => <MyCustomCard guide={guide} />}
+/>
+```
+
+**Loading states:** Shows `<OnboardingGuidesCatalogSkeleton>` only on cold first load; subsequent section toggles dim the grid (`opacity-60`) while refetching. Fetch errors surface a retryable `<LoadError>`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/onboarding-guides/hooks/.use-onboarding-guides.md b/openframe-frontend-core/src/components/onboarding-guides/hooks/.use-onboarding-guides.md
new file mode 100644
index 000000000..bdc96a7d1
--- /dev/null
+++ b/openframe-frontend-core/src/components/onboarding-guides/hooks/.use-onboarding-guides.md
@@ -0,0 +1,52 @@
+<!-- source-hash: 7cb9adf30fc30ada99b138146bf5376d -->
+React Query hooks for **public-read** access to onboarding guides, plus a shared cache key builder (`onboardingGuideKeys`) used by both client and admin (hub-side) code.
+
+## Key Components
+
+### `onboardingGuideKeys`
+Hierarchical cache key factory for the `['onboarding-guides']` namespace. Exposes both public sub-keys and an `admin` sub-namespace so a single `invalidateQueries({ queryKey: onboardingGuideKeys.all })` clears both public and admin caches simultaneously.
+
+| Key | Purpose |
+|-----|---------|
+| `all` | Root namespace — invalidates everything |
+| `list(filters)` | Filtered guide list |
+| `detail(slug)` | Single guide by slug |
+| `sections()` | Section summaries |
+| `admin.*` | Admin sub-namespace (mutations live hub-side) |
+
+### `useOnboardingGuides(filters?)`
+Fetches a paginated, filterable list of published guides from `GET /api/onboarding-guides`. Accepts `search`, `section`, `limit`, and `offset` filters.
+
+### `useOnboardingGuide(slug)`
+Fetches a single guide by slug from `GET /api/onboarding-guides/:slug`. Query is disabled when `slug` is `undefined`.
+
+### `useOnboardingGuideSections()`
+Fetches all section summaries from `GET /api/onboarding-guides/sections`. Always fetches fresh data (`staleTime: 0`).
+
+## Usage Example
+
+```typescript
+import {
+  useOnboardingGuides,
+  useOnboardingGuide,
+  useOnboardingGuideSections,
+  onboardingGuideKeys,
+} from './use-onboarding-guides'
+
+// Filtered guide list
+const { data: guides } = useOnboardingGuides({ section: 'networking', limit: 10 })
+
+// Single guide (disabled until slug is available)
+const { data: guide } = useOnboardingGuide(slug)
+
+// All section summaries
+const { data: sections } = useOnboardingGuideSections()
+
+// Invalidate all public + admin guide caches from an admin hook
+queryClient.invalidateQueries({ queryKey: onboardingGuideKeys.all })
+
+// Invalidate only the admin cache
+queryClient.invalidateQueries({ queryKey: onboardingGuideKeys.admin.all })
+```
+
+> **Non-Next.js embedders:** Routes under `/api/onboarding-guides*` must be reverse-proxied to the host. Admin mutations (`create`, `update`, `delete`, `publish`, `stats`) are managed hub-side and import `onboardingGuideKeys.admin` from this module.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/platform/.ShellTypeBadge.md b/openframe-frontend-core/src/components/platform/.ShellTypeBadge.md
index 8e3a62041..b29cb5581 100644
--- a/openframe-frontend-core/src/components/platform/.ShellTypeBadge.md
+++ b/openframe-frontend-core/src/components/platform/.ShellTypeBadge.md
@@ -1,18 +1,19 @@
-<!-- source-hash: f614dd9faeadf368597d094822bcd3c7 -->
-Displays a badge combining an icon and label for a given shell/script type, supporting all Tactical RMM shell types (PowerShell, CMD, Bash, Python, Nushell, Deno, Shell).
+<!-- source-hash: de7a7885eb63cb08866a7368b8a6445b -->
+Displays a badge for shell/script types with an appropriate icon and label, supporting all Tactical RMM shell types (PowerShell, CMD, Bash, Python, Nushell, Deno, Shell).
 
 ## Key Components
 
-- **`shellIconMap`** — A typed `Record<ShellType, ShellIconConfig>` mapping every shell type to its corresponding icon component and display props, ensuring exhaustive coverage at compile time.
-- **`defaultIconConfig`** — Fallback icon config (`ShellIcon`) used when an unrecognized shell type is passed.
-- **`ShellTypeBadgeProps`** — Props interface accepting `shellType`, optional `className` for the wrapper, and optional `iconClassName` for icon styling overrides.
-- **`ShellTypeBadge`** — Main React component that normalizes the shell type to uppercase, resolves the label via `getShellLabel`, and renders the icon + label in a flex row.
+- **`ShellTypeBadge`** — Main React component that renders an icon + label pair for a given shell type
+- **`shellIconMap`** — Typed `Record<ShellType, ShellIconConfig>` mapping every `ShellType` value to its icon component and props
+- **`ShellIconConfig`** — Interface defining the icon component type and its size/color/className props
+- **`defaultIconConfig`** — Fallback config using `ShellIcon` for unknown/undefined shell types
+- **`ShellTypeBadgeProps`** — Props interface exposing `shellType`, `className`, and `iconClassName`
 
 ## Usage Example
 
 ```typescript
-import { ShellTypeBadge } from './components/ShellTypeBadge'
-import { ShellTypeValues } from './types/shell.types'
+import { ShellTypeBadge } from './ShellTypeBadge'
+import { ShellTypeValues } from '../../types/shell.types'
 
 // Basic usage
 <ShellTypeBadge shellType={ShellTypeValues.POWERSHELL} />
@@ -20,16 +21,16 @@ import { ShellTypeValues } from './types/shell.types'
 // With custom wrapper and icon class overrides
 <ShellTypeBadge
   shellType={ShellTypeValues.PYTHON}
-  className="bg-ods-surface-secondary px-2 py-1 rounded"
+  className="px-2 py-1 bg-surface rounded"
   iconClassName="opacity-75"
 />
 
-// Dynamic shell type from API data
+// Rendering from a dynamic value (normalized to uppercase internally)
 <ShellTypeBadge shellType={script.shell_type} />
 ```
 
 ## Notes
 
-- Shell type input is normalized to uppercase before lookup, making the component tolerant of mixed-case values from API responses.
-- Icon props support either a `className` (for CSS-driven theming) or a `color` string — the component automatically forwards whichever is applicable.
-- Falls back to `ShellIcon` for any unknown or undefined shell type rather than throwing.
\ No newline at end of file
+- `shellType` is normalized to uppercase internally, so lowercase string values from APIs are handled automatically
+- Unknown shell types fall back to the generic `ShellIcon` via `defaultIconConfig`
+- The `shellIconMap` uses `Record<ShellType, ...>` to enforce exhaustive coverage at compile time — adding a new `ShellType` value will surface a TypeScript error until the map is updated
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/delivery/.delivery-lists.md b/openframe-frontend-core/src/components/shared/delivery/.delivery-lists.md
index d590bc677..ed68c67b2 100644
--- a/openframe-frontend-core/src/components/shared/delivery/.delivery-lists.md
+++ b/openframe-frontend-core/src/components/shared/delivery/.delivery-lists.md
@@ -1,20 +1,12 @@
-<!-- source-hash: a856dcd91dfe86722b63f8f7f40c9eea -->
-Renders the delivery section body with two filterable data tables — "Recently Completed" and "Active Tasks" — fetched from configurable API endpoints and driven by URL search parameters.
+<!-- source-hash: eaa6cef25a39d5eef645d81b3b3acd57 -->
+Renders the delivery section body with two filterable tables — "Recently Completed" and "Active Tasks" — by fetching from separate API endpoints and reacting to URL search params.
 
 ## Key Components
 
-### `DeliveryLists` (default export)
-Main component that orchestrates dual parallel fetches and renders both `DeliveryTable` instances.
-
-### `DeliveryListsProps`
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `completedApiEndpoint` | `string` | `/api/delivery/completed` | GET endpoint for completed tasks |
-| `inProgressApiEndpoint` | `string` | `/api/delivery/in-progress` | GET endpoint for active tasks |
-| `searchParamKey` | `string` | `'search'` | URL + API query param key for search input |
-| `taskTypeParamKey` | `string` | `'task_type'` | URL + API query param key for task-type filter |
-
-> **Coupling constraint:** `searchParamKey` and `taskTypeParamKey` must match the consuming chrome's `section.search.paramKey` / `section.filter.paramKey`. These keys are used for both URL reads and outbound API query params — override both ends consistently.
+- **`DeliveryLists`** — Main exported component. Reads `search` and `task_type` URL params, fetches both delivery buckets in parallel, and renders two `<DeliveryTable>` instances.
+- **`DeliveryListsProps`** — Interface defining the four configurable props (endpoints + param keys).
+- **`DEFAULT_COMPLETED_ENDPOINT`** / **`DEFAULT_IN_PROGRESS_ENDPOINT`** — Fallback API routes (`/api/delivery/completed`, `/api/delivery/in-progress`).
+- **Coupling constraint** — `searchParamKey` and `taskTypeParamKey` are used for both URL reads (`useSearchParams`) and outbound API query params. Both must stay in sync with the consuming chrome's param keys and the backend API contract.
 
 ## Usage Example
 
@@ -22,18 +14,13 @@ Main component that orchestrates dual parallel fetches and renders both `Deliver
 // Zero-config (OpenFrame defaults)
 <DeliveryLists />
 
-// Custom endpoints with matching chrome param keys
+// Custom endpoints + param keys (e.g. reverse-proxy setup)
 <DeliveryLists
-  completedApiEndpoint="/api/v2/tasks/done"
-  inProgressApiEndpoint="/api/v2/tasks/active"
+  completedApiEndpoint="/proxy/delivery/done"
+  inProgressApiEndpoint="/proxy/delivery/active"
   searchParamKey="q"
   taskTypeParamKey="type"
 />
 ```
 
-## Behavior
-
-- **Parallel fetches** via `Promise.all` on both endpoints, re-triggered when URL params or endpoint props change
-- **Empty states**: shows a "Reset Filters" CTA when active filters return no results; shows a generic message when no tasks exist
-- **Error state**: renders `<LoadError>` with a page-reload retry on fetch failure
-- **Loading**: passes `isLoading` to each `<DeliveryTable>` for skeleton rendering
\ No newline at end of file
+> **Note:** If you override `searchParamKey` or `taskTypeParamKey`, you must also update the consuming chrome's `section.search.paramKey` / `section.filter.paramKey` AND ensure the backend reads the same query string keys. Mismatches between the chrome, this component, and the API will silently break filtering.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/dev-section/.dev-card-row.md b/openframe-frontend-core/src/components/shared/dev-section/.dev-card-row.md
index cc5934029..55e13a90e 100644
--- a/openframe-frontend-core/src/components/shared/dev-section/.dev-card-row.md
+++ b/openframe-frontend-core/src/components/shared/dev-section/.dev-card-row.md
@@ -1,27 +1,25 @@
-<!-- source-hash: 8d3da3a7c730a952779ad08cf7640368 -->
-Shared row chrome components for `DevSectionPage` list surfaces (delivery, tickets, etc.), providing a consistent two-column layout with fixed min-height blocks for vertical alignment across grid rows, plus a thread-style conversation variant for ticket detail drawers.
+<!-- source-hash: 0c00c0d0fde761ce69fdbcdde8644ab9 -->
+Shared layout component for `DevSectionPage` list rows (delivery, tickets, and future sections), providing a consistent two-column structure with a fixed-height left column (title/subtitle/description) and a caller-supplied right column for stacked badges.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `DevCardRowContent` | Component | Two-column card row: left (title/subtitle/description) + right (caller-supplied badges) |
-| `DevCardRowSkeleton` | Component | Loading skeleton mirroring `DevCardRowContent` min-heights |
-| `ConversationCardRow` | Component | Thread-style message row with avatar, author header, body, and attachments |
-| `ConversationCardRowSkeleton` | Component | Loading skeleton for a single `ConversationCardRow` |
-| `ConversationCardRowSkeletonList` | Component | Multi-row skeleton list (default: 2 rows) for conversation timeline loading state |
-| `DevCardRowContentProps` | Interface | Props for `DevCardRowContent` |
-| `ConversationCardRowProps` | Interface | Props for `ConversationCardRow` |
+| `DevCardRowContentProps` | Interface | Props for the row content component |
+| `DevCardRowContent` | Component | Renders the two-column row chrome — left: text hierarchy; right: badge slot |
+| `DevCardRowSkeleton` | Component | Single animated skeleton row mirroring `DevCardRowContent` min-heights |
+| `DevCardRowSkeletonList` | Component | Bordered card wrapping `n` skeleton rows (default: 5) for list loading states |
 
 ## Usage Example
 
 ```typescript
-// Static delivery card row (wrapped in a div)
-<div className="border-b border-ods-border p-[12px] md:p-[16px]">
+// Static row (delivery surface)
+<div className="border-b border-ods-border p-4">
   <DevCardRowContent
     title="Deploy v2.4.1 to production"
     subtitle="UPDATED today, #4271, Code review"
-    description="Bumps the API gateway to support new webhook endpoints."
+    description="Bumps the API gateway and rotates the signing key."
+    emptyDescription="No delivery notes provided."
     rightBadges={
       <>
         <StatusBadge status="in-progress" />
@@ -31,30 +29,18 @@ Shared row chrome components for `DevSectionPage` list surfaces (delivery, ticke
   />
 </div>
 
-// Clickable ticket card row (wrapped in a button)
+// Clickable row (tickets surface)
 <button onClick={openTicket}>
   <DevCardRowContent
-    title="Login page throws 502 on Safari"
-    subtitle="OPEN · #1042 · Bug"
+    title="VPN drops on Windows 11 24H2"
+    subtitle="OPEN, #1042, Networking"
     description=""
-    emptyDescription="No description provided for this ticket."
     rightBadges={<SeverityBadge level="critical" />}
   />
 </button>
 
-// Conversation thread row
-<ConversationCardRow
-  author="Jane Smith"
-  role="Resolution"
-  avatarSrc="https://cdn.example.com/avatars/jane.png"
-  timestamp="2026-01-15T14:32:00Z"
-  body="The issue has been resolved by restarting the gateway service."
-  attachments={[{ name: "fix-log.txt", url: "/files/fix-log.txt" }]}
-  variant="support"
-/>
-
-// Loading state
-<ConversationCardRowSkeletonList rows={3} />
+// Loading state for a list shell
+<DevCardRowSkeletonList rows={8} />
 ```
 
-> **Design note:** `DevCardRowContent` is layout-only — no click behavior is baked in. Wrap in `<div>` for static rows or `<button>` for interactive ones. `rightBadges` accepts any `ReactNode`, keeping badge composition flexible per surface.
\ No newline at end of file
+> **Note:** Ticket conversation rows are intentionally excluded — they use the shared `<ChatMessageRow>` component (`components/chat/chat-message-row.tsx`), the same component powering the OpenMSP community feed, keeping both surfaces pixel-identical.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/dev-section/.dev-section-page.md b/openframe-frontend-core/src/components/shared/dev-section/.dev-section-page.md
index 5c5e9e22c..badd6ba32 100644
--- a/openframe-frontend-core/src/components/shared/dev-section/.dev-section-page.md
+++ b/openframe-frontend-core/src/components/shared/dev-section/.dev-section-page.md
@@ -1,48 +1,50 @@
-<!-- source-hash: 0de96ea9df1ea6a28df1ff674cfc5e14 -->
-Full-page wrapper component for dev-center sections (`/roadmap`, `/bug-fixes-and-enhancements`, `/releases`) in the OpenFrame platform. It composes `PageShell → PageLayout → DevSectionView` to deliver a consistent hero icon, search, and filter pill layout across all dev sections.
+<!-- source-hash: 1aff3fa5d309816d9c5756876912ff53 -->
+Full-page wrapper component for OpenFrame dev-center sections (`/roadmap`, `/bug-fixes-and-enhancements`, `/releases`), composing `PageShell` → `PageLayout` → `DevSectionView` with a configurable back-button, hero, and optional pre-controls slot.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `DevSectionPage` | Component | Main page wrapper factory for any `OpenframeDevSectionKey` section |
-| `DevSectionPageProps` | Interface | Props contract for `sectionKey`, `children`, `preControls`, and `backButton` |
-| `SECTION_HERO_ICON_CLASS` | Constant | Tailwind class applied uniformly to all section hero icons |
+| `DevSectionPage` | Component | Main factory component for rendering any registered dev-center section page |
+| `DevSectionPageProps` | Interface | Props contract for `DevSectionPage` |
 
 ### Props
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `sectionKey` | `OpenframeDevSectionKey` | Looks up section metadata from `OPENFRAME_DEV_SECTIONS` |
-| `children` | `ReactNode` | Page-specific list body (e.g. `<RoadmapList />`) |
-| `preControls` | `ReactNode` (optional) | Slot rendered between the hero and search/filter controls |
-| `backButton` | `{ label?, href? } \| false` (optional) | Configures or hides the back button; defaults to `Back to home → /` |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sectionKey` | `OpenframeDevSectionKey` | required | Key into `OPENFRAME_DEV_SECTIONS` registry |
+| `children` | `ReactNode` | required | Section-specific list body (e.g. `<RoadmapList />`) |
+| `preControls` | `ReactNode` | — | Slot rendered between hero and search/filter controls |
+| `backButton` | `{ label?, href? } \| false` | `{ label: 'Back to home', href: '/' }` | Back-button config; pass `false` to hide |
+| `title` | `string` | `OPENFRAME_DEV_SECTIONS[key].hero.title` | Hero title override for non-OpenFrame embeds |
+| `subtitle` | `string` | `OPENFRAME_DEV_SECTIONS[key].hero.description` | Hero subtitle override |
 
 ## Usage Example
 
 ```typescript
-// Adding a new section page is a single mount:
-import { DevSectionPage } from '@/components/dev-center/dev-section-page';
-
+// pages/roadmap/page.tsx — minimal, uses all defaults
 export default function RoadmapPage() {
+  return (
+    <DevSectionPage sectionKey="roadmap">
+      <RoadmapList />
+    </DevSectionPage>
+  );
+}
+
+// Custom embed — overrides branding and back-button destination
+export default function CustomRoadmapPage() {
   return (
     <DevSectionPage
       sectionKey="roadmap"
-      backButton={{ label: 'Back to home', href: '/' }}
+      title="Product Roadmap"
+      subtitle="See what we're building next."
+      backButton={{ label: 'Back to dashboard', href: '/dashboard' }}
+      preControls={<NewTicketForm />}
     >
       <RoadmapList />
     </DevSectionPage>
   );
 }
-
-// With a preControls slot (e.g. Help Center ticket form above filters):
-<DevSectionPage
-  sectionKey="help-center"
-  preControls={<OpenTicketForm />}
-  backButton={false} // hide back button
->
-  <TicketList />
-</DevSectionPage>
 ```
 
-> **Extensibility:** Adding a new dev-center section requires only one entry in `OPENFRAME_DEV_SECTIONS` plus a single page file mounting `DevSectionPage` with the new key. Design system changes to `BackButton` or `TitleBlock` propagate automatically via the shared `PageLayout`.
\ No newline at end of file
+> **Extending:** Adding a new section requires only one entry in `OPENFRAME_DEV_SECTIONS` and a single page file mounting `DevSectionPage` with the new `sectionKey`. No changes to this component are needed.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/dev-section/.dev-section-view.md b/openframe-frontend-core/src/components/shared/dev-section/.dev-section-view.md
index ba3975523..1d6369c76 100644
--- a/openframe-frontend-core/src/components/shared/dev-section/.dev-section-view.md
+++ b/openframe-frontend-core/src/components/shared/dev-section/.dev-section-view.md
@@ -1,43 +1,43 @@
-<!-- source-hash: 508a1c69dd2d082f4bed6cb98c63998b -->
-Canonical chrome wrapper for dev-center sections (Roadmap, Delivery, Releases), handling title rendering, inline search, filter pills, and URL-param wiring in both tabbed and full-page layout modes.
+<!-- source-hash: 740500f74090989b9c2db01ca7144ae9 -->
+Canonical layout shell for dev-center sections (Roadmap, Delivery, Releases), handling title rendering, inline search, filter pills, and URL parameter wiring in both hero (full-page) and compact (tabbed) display modes.
 
 ## Key Components
 
-### `DevSectionView`
-The single shared layout shell consumed by every dev-center section page. Supports two display modes:
-- **Hero mode** — full-page layout with icon, `<h1>`, and description (pass `hero` prop)
-- **Compact mode** — tab-context `<h2>` heading only (omit `hero`)
-
-### `DevSectionViewProps`
-| Prop | Type | Description |
-|------|------|-------------|
-| `sectionKey` | `OpenframeDevSectionKey` | Registry key driving title, search, and filter config |
-| `hero` | `{ icon: ReactNode, description: string }` | Enables full-page hero rendering |
-| `preControls` | `ReactNode` | Optional slot between hero and search/filter controls |
-| `children` | `ReactNode` | Section-specific list body; reads URL params set by this component |
-
-### URL Contract
-- Search commits to `?<paramKey>=...` on **Enter only** (not every keystroke)
-- Filter changes are applied immediately via `router.replace` with `scroll: false`
-- Default filter values are omitted from the URL (cleaned via `params.delete`)
-- `searchValue` is lazy-initialized from URL params to prevent stale flash on tab switch
+**`DevSectionView`** — Primary exported component that:
+- Renders a **hero** (icon + `h1` + description) or **compact heading** (`h2`) based on the `hero` prop
+- Wires a `SearchInput` to URL params, committing only on Enter (not on every keystroke)
+- Wires a `StatusFilterComponent` to URL params via `handleFilterChange`
+- Exposes a `preControls` slot rendered between the hero and the search/filter row
+- Delegates all list rendering to `children`, which read URL params independently via `useSearchParams()`
+
+**`DevSectionViewProps`** — Interface defining:
+| Prop | Required | Description |
+|---|---|---|
+| `sectionKey` | ✅ | Looks up config in `OPENFRAME_DEV_SECTIONS` registry |
+| `hero` | ❌ | Enables full-page hero mode with icon, title, description |
+| `preControls` | ❌ | Slot rendered above search/filter controls |
+| `children` | ✅ | List body consuming URL search/filter params |
 
 ## Usage Example
 
 ```typescript
-// Hero (full-page) mode
+// Full-page hero mode (e.g. /roadmap)
 <DevSectionView
   sectionKey="roadmap"
-  hero={{ icon: <RoadmapIcon />, description: "Track upcoming features." }}
+  hero={{
+    icon: <RoadmapIcon />,
+    title: "Product Roadmap",
+    description: "Upcoming features and improvements."
+  }}
   preControls={<NewTicketForm />}
 >
   <RoadmapList />
 </DevSectionView>
 
-// Compact (tabbed) mode
+// Compact tab mode (e.g. inside /roadmap-and-releases)
 <DevSectionView sectionKey="releases">
   <ReleasesList />
 </DevSectionView>
 ```
 
-Children read filter/search state directly from URL params via `useSearchParams()` — no prop drilling required.
\ No newline at end of file
+> Search state is lazy-initialised from the URL to avoid a stale-value flash on tab switches. Filter resets to the default value by deleting the param rather than writing the default string.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.doc-search-bar.md b/openframe-frontend-core/src/components/shared/doc-search/.doc-search-bar.md
new file mode 100644
index 000000000..278131faf
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.doc-search-bar.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 07409d514305754ffc933394824594aa -->
+A presentational RAG-search dropdown component that wraps `<SearchInput>` with standardized `<DocSearchResultRow>` rendering, providing a consistent typeahead UI across all doc-search surfaces (data-room sidebar, onboarding guide catalog, etc.).
+
+## Key Components
+
+**`DocSearchBar`** — Main export. A thin presentation wrapper; all data-fetching stays hub-side via `useDocSearch` and is passed in as props.
+
+**`DocSearchBarProps`** — Interface defining the component's contract:
+- `query` / `onQueryChange` — controlled input state
+- `results` / `isLoading` — hook-fetched search results passed directly
+- `onResultSelect` — selection handler preserving modifier keys (`metaKey`, `ctrlKey`, etc.) for new-tab behavior
+- `showDropdown` — caller-controlled dropdown visibility override
+- `minQueryLength` — typeahead trigger threshold (default: `2`)
+- `debounceMs` — input debounce delay (default: `0`; consumers debounce in the hook)
+- `renderResult` — optional row renderer override; defaults to `<DocSearchResultRow>`
+
+## Usage Example
+
+```typescript
+// Typical consumer — hook lives hub-side, component stays minimal
+const { query, setQuery, results, isLoading, handleSelect } = useDocSearch()
+
+return (
+  <DocSearchBar
+    placeholder="Search docs..."
+    query={query}
+    onQueryChange={setQuery}
+    results={results}
+    isLoading={isLoading}
+    onResultSelect={handleSelect}
+    minQueryLength={2}
+  />
+)
+
+// Custom row chrome override
+<DocSearchBar
+  {...baseProps}
+  renderResult={(result, isHighlighted) => (
+    <MyCustomRow result={result} active={isHighlighted} />
+  )}
+/>
+```
+
+## Design Notes
+
+The hook (`useDocSearch`) intentionally stays hub-side — it depends on hub-only context (`useDocNavigation`, rag-table-config registry, `decideNewTab`). This component accepts hook output as plain props, keeping both consumers at ~5 lines each while the dropdown UI remains identical across surfaces.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.doc-search-result-row.md b/openframe-frontend-core/src/components/shared/doc-search/.doc-search-result-row.md
new file mode 100644
index 000000000..9ee09c8d5
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.doc-search-result-row.md
@@ -0,0 +1,32 @@
+<!-- source-hash: b0e6f6a3a50c1611ab724a7e8381c137 -->
+Renders a single search result row for doc-search dropdowns, providing a consistent visual layout across all search surfaces (company hub data-room, onboarding-guide catalog, etc.).
+
+## Key Components
+
+- **`DocSearchResultRowEntry`** — Minimal result shape interface compatible with any `useDocSearch` hook result exposing `title?`, `path?`, and `metadata?`
+- **`DocSearchResultRowProps`** — Props interface accepting a `result` entry and `isHighlighted` boolean
+- **`DocSearchResultRow`** — Main component rendering the icon, title, and relative path for a single dropdown row
+
+## Behavior
+
+- Resolves the source icon via `resolveSourceIcon()` using `metadata.sourceRepo` and `metadata.documentType`, keeping icon appearance in sync with inline chat-card references
+- Highlights the title in accent color (`text-ods-accent`) when `isHighlighted` is `true`
+- Suppresses the path subtitle for group entries (`metadata.isGroup`) or flat paths without a `/`
+- Formats the path display using `formatRelativePath()` for a cleaner breadcrumb-style label
+
+## Usage Example
+
+```typescript
+import { DocSearchResultRow } from './doc-search-result-row'
+
+const result = {
+  title: 'Onboarding Guide',
+  path: 'guides/onboarding/getting-started',
+  metadata: {
+    documentType: 'onboarding-guide',
+    sourceRepo: 'internal-docs',
+  },
+}
+
+<DocSearchResultRow result={result} isHighlighted={false} />
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.format-relative-path.md b/openframe-frontend-core/src/components/shared/doc-search/.format-relative-path.md
new file mode 100644
index 000000000..39d267a08
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.format-relative-path.md
@@ -0,0 +1,21 @@
+<!-- source-hash: ab6e8805ed4afb72f4daaf8533fb546d -->
+Formats a full document path into a human-readable breadcrumb trail, showing only parent folder segments (excluding the filename).
+
+## Key Components
+
+- **`formatRelativePath(fullPath: string): string`** — Strips the `.md` extension, splits on `/`, excludes the last segment (filename), then capitalizes and replaces hyphens with spaces in each remaining segment, joining them with ` / `.
+
+## Usage Example
+
+```typescript
+import { formatRelativePath } from './format-relative-path'
+
+formatRelativePath('openframe-oss-tenant/architecture/api-controllers.md')
+// → 'Openframe oss tenant / Architecture'
+
+formatRelativePath('docs/getting-started.md')
+// → 'Docs'
+
+formatRelativePath('')
+// → ''
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.index.md b/openframe-frontend-core/src/components/shared/doc-search/.index.md
new file mode 100644
index 000000000..b6acd0fea
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.index.md
@@ -0,0 +1,48 @@
+<!-- source-hash: 1a3cdf4f2baf4c14c3068d549bbbc83a -->
+Public API barrel file for the doc-search package, re-exporting all components, hooks, utilities, and types needed to embed documentation search functionality in any consumer application.
+
+## Key Components
+
+| Export | Source | Description |
+|--------|--------|-------------|
+| `DocSearchBar` / `DocSearchBarProps` | `./doc-search-bar` | Search input UI component |
+| `DocSearchResultRow` / `DocSearchResultRowProps` / `DocSearchResultRowEntry` | `./doc-search-result-row` | Individual search result renderer |
+| `useDocSearch` / `UseDocSearchConfig` | `./use-doc-search` | Hook encapsulating debounced fetch + result navigation logic |
+| `resolveSearchResultAction` / `SearchResultAction` | `./resolve-search-result-action` | Determines the navigation action for a given result |
+| `mapDocSearchResults` | `./map-doc-search-results` | Transforms raw API results into display-ready entries |
+| `formatRelativePath` | `./format-relative-path` | Utility to normalize/display doc paths |
+| `DocSearchResult` | `./types` | Shared result type |
+
+## Usage Example
+
+```typescript
+import {
+  DocSearchBar,
+  DocSearchResultRow,
+  useDocSearch,
+  resolveSearchResultAction,
+  type DocSearchResult,
+} from '@flamingo/doc-search'
+
+function SearchPanel() {
+  const { query, setQuery, results, isLoading } = useDocSearch({
+    debounceMs: 300,
+    onNavigate: (path) => router.push(path),
+  })
+
+  return (
+    <>
+      <DocSearchBar value={query} onChange={setQuery} loading={isLoading} />
+      {results.map((result: DocSearchResult) => (
+        <DocSearchResultRow
+          key={result.id}
+          entry={result}
+          action={resolveSearchResultAction(result)}
+        />
+      ))}
+    </>
+  )
+}
+```
+
+> **Note:** `useDocSearch` was migrated from the hub's `hooks/use-docs.ts` so embedders can mount the search bar directly without re-implementing debounced fetch or result navigation logic.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.map-doc-search-results.md b/openframe-frontend-core/src/components/shared/doc-search/.map-doc-search-results.md
new file mode 100644
index 000000000..513e549e7
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.map-doc-search-results.md
@@ -0,0 +1,33 @@
+<!-- source-hash: 0432b27945c1f7d64624ec15662b0110 -->
+Transforms RAG `/api/docs/search` wire results into `SearchResult` rows for the `<DocSearchBar>` dropdown, collapsing financial entity-table rows into single grouped entries.
+
+## Key Components
+
+**`SEARCH_GROUP_REPOS`** — Set of financial source repos (`financial-cap-table`, `financial-kpis`, `financial-pnl`, `financial-balance-sheet`, `financial-cash-flow`) whose rows are collapsed into a single grouped result.
+
+**`ENTITY_LABELS`** — Display name map for known `sourceRepo` values (both grouped financial tables and individual content types like blog posts, webinars, etc.).
+
+**`mapDocSearchResults(docs)`** — Pure transform function. Iterates `DocSearchResult[]`, groups financial table rows by `sourceRepo` (preserving the insertion order of the first occurrence), and returns a flat `SearchResult[]` where:
+- Grouped repos → one row: `"Cap Table (12 records)"` with `metadata.isGroup = true` and a nested `items[]` array.
+- All other docs → individual rows with `snippet`, `matchType`, `externalUrl`, and other metadata forwarded as-is.
+
+## Usage Example
+
+```typescript
+import { mapDocSearchResults } from './map-doc-search-results'
+
+// Raw results from GET /api/docs/search
+const rawDocs: DocSearchResult[] = await fetchDocSearch(query)
+
+// Ready for <DocSearchBar> dropdown
+const rows: SearchResult[] = mapDocSearchResults(rawDocs)
+
+// Grouped financial table example output:
+// {
+//   id: 'group-financial-cap-table',
+//   title: 'Cap Table (5 records)',
+//   metadata: { isGroup: true, items: [...] }
+// }
+```
+
+> **Note:** This is a pure transform with no side effects. Callers that need telemetry or logging should wrap `mapDocSearchResults` rather than modifying it directly.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.resolve-search-result-action.md b/openframe-frontend-core/src/components/shared/doc-search/.resolve-search-result-action.md
new file mode 100644
index 000000000..31f73a5fc
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.resolve-search-result-action.md
@@ -0,0 +1,48 @@
+<!-- source-hash: f287f0ffda0699577d87fde5f21130f1 -->
+Resolves the appropriate navigation or interaction action when a user selects a search result, returning one of five typed discriminated union actions for a single `switch` dispatch.
+
+## Key Components
+
+### `SearchResultAction` (exported union type)
+
+| Kind | Payload | Description |
+|------|---------|-------------|
+| `navigate-same-tab` | `href: string` | External URL, same tab |
+| `navigate-new-tab` | `href: string` | External URL, new tab |
+| `ask-ai` | `detail: { source, ref: ChatRef }` | Entity drill-in via AI chat |
+| `route` | `path: string` | Legacy internal path navigation |
+| `noop` | — | No actionable target found |
+
+### `resolveSearchResultAction(result, source, runtimeMode?)`
+
+Pure function — no React, no side effects. Evaluates `result.metadata` in priority order:
+
+1. **`externalUrl`** present → delegates to `decideNewTab` using `targetPlatform` and `runtimeMode` to choose same-tab vs new-tab
+2. **`id` + `sourceRepo` + `documentType`** all present → returns `ask-ai` with a `ChatRef` built from the row's primary key
+3. **`result.path`** present → returns legacy `route` action
+4. **Nothing actionable** → returns `noop`
+
+## Usage Example
+
+```typescript
+import { resolveSearchResultAction } from './resolve-search-result-action'
+
+const action = resolveSearchResultAction(searchResult, 'my-source', 'host')
+
+switch (action.kind) {
+  case 'navigate-same-tab':
+    router.push(action.href)
+    break
+  case 'navigate-new-tab':
+    window.open(action.href, '_blank')
+    break
+  case 'ask-ai':
+    chatRef.current?.send(action.detail)
+    break
+  case 'route':
+    navigate(action.path)
+    break
+  case 'noop':
+    break
+}
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.types.md b/openframe-frontend-core/src/components/shared/doc-search/.types.md
new file mode 100644
index 000000000..8e0a65153
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.types.md
@@ -0,0 +1,43 @@
+<!-- source-hash: 537733be76caba7ce3819410ae7e37fd -->
+Single wire-shape contract for one document/entity search result returned by `/api/docs/search`.
+
+## Key Components
+
+### `DocSearchResult` interface
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` | `string` | Internal path identifier for the result |
+| `name` | `string` | Display name of the document or folder |
+| `type` | `'file' \| 'folder'` | Whether the result is a file or folder node |
+| `snippet` | `string` | Preview text excerpt shown in search results |
+| `matchType` | `'title' \| 'content'` | Whether the match was on title or body content |
+| `documentType` | `string?` | Optional document category/type classifier |
+| `externalUrl` | `string?` | External viewer URL when the doc lives outside the hub |
+| `targetPlatform` | `string \| null \| undefined` | Platform owning `externalUrl`; used by `decideNewTab` to determine same-tab vs. new-tab navigation |
+| `sourceRepo` | `string?` | Repository the document originates from |
+| `entityId` | `string?` | Primary key value from `RagTableConfig`; enables chat panel drill-in for entity rows that have no public viewer URL |
+
+## Usage Example
+
+```typescript
+import type { DocSearchResult } from './types'
+
+// Consuming a search API response
+const results: DocSearchResult[] = await fetch('/api/docs/search?q=firewall')
+  .then(res => res.json())
+
+results.forEach(result => {
+  if (result.entityId) {
+    // No public URL — open chat panel with entity drill-in
+    openChatPanel({ entityIdFilter: result.entityId })
+  } else if (result.externalUrl) {
+    const newTab = decideNewTab(result.targetPlatform)
+    navigate(result.externalUrl, { newTab })
+  } else {
+    navigate(result.path)
+  }
+})
+```
+
+> **Sync contract:** This interface must remain field-for-field identical with `lib/data/doc-search-utils.ts:DocSearchResult` on the hub side. Any field additions must be mirrored in both locations.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/doc-search/.use-doc-search.md b/openframe-frontend-core/src/components/shared/doc-search/.use-doc-search.md
new file mode 100644
index 000000000..866af8fa6
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/doc-search/.use-doc-search.md
@@ -0,0 +1,46 @@
+<!-- source-hash: d875770781ca37f97e78a853dba4a697 -->
+Debounced RAG search hook that fetches results from `/api/docs/search` and handles multi-mode navigation (same-tab, new-tab, in-page swap, AI dispatch, embed-mode).
+
+## Key Components
+
+**`UseDocSearchConfig`** — Configuration interface with the following options:
+
+| Option | Required | Description |
+|---|---|---|
+| `source` | ✅ | Discriminator forwarded as `?source=` query param |
+| `baseRoute` | ✅ | Route prefix used to detect in-page-swappable results |
+| `onNavigate` | ✅ | Fallback navigation callback (e.g. `router.push`) |
+| `tableIds` | ❌ | Narrow search to specific RAG table IDs |
+| `onInPageSwap` | ❌ | Hub callback for soft doc-tree swaps; returns `true` if handled |
+| `searchEndpoint` | ❌ | Defaults to `'/api/docs/search'` |
+
+**`useDocSearch(config)`** — Returns:
+- `query` / `setQuery` — controlled search input state
+- `results` — mapped `SearchResult[]`
+- `isLoading` — unified loading state (debounce lag + in-flight fetch)
+- `handleResultSelect` — click/keyboard handler resolving one of five action kinds: `navigate-same-tab`, `navigate-new-tab`, `ask-ai`, `route`, `noop`
+- `keepDropdownOpen` — `true` when a new-tab navigation occurred so the dropdown stays visible
+
+## Usage Example
+
+```typescript
+// Hub usage — in-page swap wired to doc-tree navigation
+const { query, setQuery, results, isLoading, handleResultSelect, keepDropdownOpen } =
+  useDocSearch({
+    source: 'openframe',
+    baseRoute: '/onboarding-guides',
+    onNavigate: (path) => router.push(path),
+    tableIds: ['onboarding-guides'],
+    onInPageSwap: (path) => docNavigation.navigate(path),
+  })
+
+// Bare embedder — minimal config, falls back to window.location
+const search = useDocSearch({
+  source: 'openframe',
+  baseRoute: '/docs',
+  onNavigate: (path) => window.location.assign(path),
+  searchEndpoint: '/proxy/api/docs/search',
+})
+```
+
+> **Note:** Modifier-key handling (`metaKey`, `ctrlKey`, `shiftKey`) forces new-tab behavior on `<div>`-based rows to match native `<a target="_blank">` semantics.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/legal-document/.legal-document-page.md b/openframe-frontend-core/src/components/shared/legal-document/.legal-document-page.md
index 748f9c26f..cb8d58f26 100644
--- a/openframe-frontend-core/src/components/shared/legal-document/.legal-document-page.md
+++ b/openframe-frontend-core/src/components/shared/legal-document/.legal-document-page.md
@@ -1,23 +1,23 @@
-<!-- source-hash: 3706922a9df0493d5342fee857818e2a -->
-Unified page component for rendering markdown-backed legal documents (privacy policy, terms of service, etc.), replacing duplicate per-document hub components with a single configurable abstraction.
+<!-- source-hash: 647a70227b2b296351ad95d6d76984e9 -->
+Unified page component for rendering markdown-backed legal documents (privacy policy, terms of service, etc.), replacing duplicate per-document hub components with a single configurable implementation.
 
 ## Key Components
 
 ### `LegalDocumentPage`
-Main exported component that handles the full page lifecycle — loading skeleton, error state, empty state, and rendered markdown content — driven entirely by props.
+Main exported component that handles all legal document rendering states: loading skeleton, error display, empty state, and full markdown content.
 
 ### `LegalDocumentPageProps`
 Configuration interface covering:
-- **`docType`** — drives the default `/api/legal/<docType>` endpoint and error-log prefix
-- **`title` / `fallbackDescription`** — heading and subtitle text
-- **`contactEmail` / `errorContactPrompt` / `errorTitle` / `emptyStateMessage`** — per-document copy strings
-- **`initialData` / `initialLastUpdatedLabel`** — SSR hydration-safe pre-fetched data
-- **`apiEndpoint`** — optional override for reverse-proxy or alternate API paths
-- **`MarkdownRenderer`** — injectable renderer (defaults to `SimpleMarkdownRenderer`); pass a richer renderer for embeds/video/OG previews
-- **`backButton`** — configurable back-nav; pass `false` to hide in embed mode
+- `docType` — drives the default API endpoint `/api/legal/<docType>`
+- `title`, `fallbackDescription`, `contactEmail` — document-specific copy
+- `errorTitle`, `errorContactPrompt`, `emptyStateMessage` — user-facing error/empty strings
+- `initialData` / `initialLastUpdatedLabel` — SSR hydration props
+- `apiEndpoint` — optional override for reverse-proxy or alternate API paths
+- `MarkdownRenderer` — injectable renderer component (defaults to `SimpleMarkdownRenderer`)
+- `backButton` — back-nav config or `false` to suppress
 
 ### `LegalDocumentMarkdownRendererProps`
-Renderer contract interface with `content`, `sectionIds`, and `demoteMarkdownH1ToH2`.
+Interface contract for custom `MarkdownRenderer` components, accepting `content`, optional `sectionIds`, and `demoteMarkdownH1ToH2`.
 
 ## Usage Example
 
@@ -28,22 +28,23 @@ Renderer contract interface with `content`, `sectionIds`, and `demoteMarkdownH1T
   title="Privacy Policy"
   fallbackDescription="Our privacy policy and data protection practices."
   contactEmail="privacy@openframe.io"
-  errorContactPrompt="For privacy-related questions, please contact:"
   errorTitle="Unable to load privacy policy"
+  errorContactPrompt="For privacy-related questions, please contact:"
   emptyStateMessage="Privacy policy content is not available at this time."
   initialData={ssrDocument}
-  initialLastUpdatedLabel="January 15, 2025"
+  initialLastUpdatedLabel="January 1, 2025"
+  backButton={{ label: 'Back to home', href: '/' }}
 />
 
-// Embed mode with custom renderer and no back button
+// Terms of Service with custom renderer and hidden back button
 <LegalDocumentPage
   docType="terms"
   title="Terms of Service"
-  fallbackDescription="Terms governing use of our platform."
+  fallbackDescription="Our terms and conditions."
   contactEmail="legal@openframe.io"
-  errorContactPrompt="For legal questions, please contact:"
   errorTitle="Unable to load terms of service"
-  emptyStateMessage="Terms of service content is not available at this time."
+  errorContactPrompt="For legal questions, please contact:"
+  emptyStateMessage="Terms of service content is not available."
   MarkdownRenderer={RichMarkdownRenderer}
   backButton={false}
 />
diff --git a/openframe-frontend-core/src/components/shared/legal-document/.use-legal-docs.md b/openframe-frontend-core/src/components/shared/legal-document/.use-legal-docs.md
index bf8cb9a4b..cf5d4fdab 100644
--- a/openframe-frontend-core/src/components/shared/legal-document/.use-legal-docs.md
+++ b/openframe-frontend-core/src/components/shared/legal-document/.use-legal-docs.md
@@ -1,5 +1,5 @@
-<!-- source-hash: 8cc6f0cadfbca233ed799a57d6b4388c -->
-A React hook that fetches markdown-backed legal documents (privacy policy, terms of service, etc.) from a hub API endpoint, with support for SSR/RSC pre-fetched data and manual refetching.
+<!-- source-hash: 697833b11c0495f61aa494d1636be193 -->
+React hook for fetching markdown-backed legal documents (privacy policy, terms of service, etc.) from a hub API endpoint, with optional SSR/RSC `initialData` support.
 
 ## Key Components
 
@@ -7,36 +7,51 @@ A React hook that fetches markdown-backed legal documents (privacy policy, terms
 
 | Interface | Description |
 |-----------|-------------|
-| `LegalDocument` | Shape of the fetched document — includes title, markdown content, GitHub sync metadata, and parsed section headings |
-| `UseLegalDocsOptions` | Hook configuration — optional `initialData` for SSR hydration and `apiEndpoint` override for reverse-proxy embedders |
-| `UseLegalDocsReturn` | Hook return value — `data`, `isLoading`, `error`, and `refetch` |
+| `LegalDocument` | Shape of the fetched document, mirroring the server-side `LegalDocument` type (avoids importing server types in client code) |
+| `UseLegalDocsOptions` | Optional `initialData` (SSR pre-fetch) and `apiEndpoint` override |
+| `UseLegalDocsReturn` | `{ data, isLoading, error, refetch }` |
 
 ### `useLegalDocs(docType, options?)`
 
-Core hook that manages fetch lifecycle for a legal document. Key behaviors:
+| Param | Type | Description |
+|-------|------|-------------|
+| `docType` | `string` | Document identifier — drives the default endpoint path (`/api/legal/<docType>`). Common values: `'privacy'`, `'terms'` |
+| `options.initialData` | `LegalDocument \| null` | Pre-fetched payload from server; skips initial client fetch when provided |
+| `options.apiEndpoint` | `string` | Override the default endpoint (e.g. `/proxy/legal/privacy` for reverse-proxy embedders) |
 
-- **Default endpoint:** `/api/legal/<docType>` — overridable via `apiEndpoint`
-- **SSR-safe:** When `initialData` is provided, the initial client fetch is skipped entirely
-- **`docType` reset guard:** When `docType` changes, stale data is cleared immediately before the new fetch resolves — prevents flash of wrong content in embedders cycling through document types
-- **Error handling:** Propagates HTTP errors and empty-content responses as human-readable strings via the `error` state
+**Behaviours:**
+- Resets cached data when `docType` changes, preventing stale content flicker during sequential doc loads
+- Skips fetch on mount when `initialData` is present
+- Guards against tainted format-string injection (CodeQL `js/tainted-format-string`) by keeping `console.error` format string constant
 
 ## Usage Example
 
 ```typescript
-// Basic client-side fetch
-const { data, isLoading, error, refetch } = useLegalDocs('privacy');
-
-// SSR hydration — skip initial client fetch
-const { data } = useLegalDocs('terms', {
-  initialData: serverFetchedDoc,
-});
-
-// Reverse-proxy embedder overriding the endpoint
-const { data, isLoading } = useLegalDocs('privacy', {
-  apiEndpoint: '/proxy/legal/privacy',
-});
-
-if (isLoading) return <Spinner />;
-if (error) return <ErrorBanner message={error} onRetry={refetch} />;
-return <MarkdownRenderer content={data?.content} />;
+import { useLegalDocs } from '@/hooks/use-legal-docs';
+
+// Basic usage — fetches from /api/legal/privacy
+function PrivacyPage() {
+  const { data, isLoading, error, refetch } = useLegalDocs('privacy');
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage message={error} onRetry={refetch} />;
+
+  return <MarkdownRenderer content={data?.content} />;
+}
+
+// With SSR pre-fetch — skips client fetch on first render
+function TermsPage({ initialData }: { initialData: LegalDocument }) {
+  const { data } = useLegalDocs('terms', { initialData });
+
+  return <MarkdownRenderer content={data?.content} />;
+}
+
+// Reverse-proxy embedder with custom endpoint
+function EmbeddedPrivacy() {
+  const { data } = useLegalDocs('privacy', {
+    apiEndpoint: '/proxy/legal/privacy',
+  });
+
+  return <MarkdownRenderer content={data?.content} />;
+}
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/product-release/.index.md b/openframe-frontend-core/src/components/shared/product-release/.index.md
index cf4f4901f..c8a9194cd 100644
--- a/openframe-frontend-core/src/components/shared/product-release/.index.md
+++ b/openframe-frontend-core/src/components/shared/product-release/.index.md
@@ -1,38 +1,39 @@
-<!-- source-hash: b0b73e639c7dda545193a2a31fafd1ca -->
-Barrel export file for the **product release** UI component family, re-exporting all public components, skeletons, and related TypeScript types from the `product-release` feature directory.
+<!-- source-hash: 60b9ca8b719e2a8ed7836247d6f859d9 -->
+Barrel export file for the product release UI component library, re-exporting all public components, props types, and shared types from the product release feature module.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ProductReleaseCard` | Component | Card UI for displaying a product release |
-| `ProductReleaseCardSkeleton` | Component | Loading skeleton for `ProductReleaseCard` |
-| `ReleaseDetailPage` | Component | Full release detail page layout |
-| `ReleaseDetailSkeleton` | Component | Loading skeleton for `ReleaseDetailPage` |
-| `DeliveryResponse` | Type | Canonical delivery response type (sourced from `types/delivery`) |
-| `ProductReleaseCardProps` | Type | Props for `ProductReleaseCard` |
-| `ReleaseDetailPageProps` | Type | Props for `ReleaseDetailPage` |
-| `VideoDisplaySectionProps` | Type | Props for the video display section slot |
-| `MarkdownRendererProps` | Type | Props for the markdown renderer slot |
-| `RoadmapItem` | Type | Individual roadmap item type |
-
-> **Note:** `RoadmapSectionProps` and `DeliverySectionProps` are intentionally **not** re-exported here to avoid TS2308 ambiguous re-export conflicts with the concrete `<RoadmapGrid>` / `<DeliverySection>` components. Import them directly from the `release-detail-page` module if needed.
+| Export | Source | Description |
+|--------|--------|-------------|
+| `ProductReleaseCard` | `./product-release-card` | Card component for displaying a single product release |
+| `ProductReleaseCardSkeleton` | `./product-release-card-skeleton` | Loading skeleton for `ProductReleaseCard` |
+| `ProductReleasesView` | `./product-releases-view` | List/grid view rendering multiple release cards |
+| `ReleaseDetailPage` | `./release-detail-page` | Full detail page for a single release |
+| `ReleaseDetailSkeleton` | `./release-detail-skeleton` | Loading skeleton for `ReleaseDetailPage` |
+| `DeliveryResponse` | `../../../types/delivery` | Canonical delivery response type (re-sourced to preserve deep-import path resolution) |
+
+### Notable Type Exports
+
+- `ProductReleaseCardProps`, `ProductReleaseCardSkeletonProps`, `ProductReleasesViewProps`
+- `ProductReleaseCardExtras` — additional data slots for release cards
+- `ReleaseDetailPageProps`, `VideoDisplaySectionProps`, `MarkdownRendererProps`, `RoadmapItem`
+
+> **Note:** `RoadmapSectionProps` and `DeliverySection Props` are intentionally **not** re-exported here to avoid TS2308 ambiguous re-export conflicts with concrete component prop types in `./shared`. Import them directly from the `release-detail-page` module if needed.
 
 ## Usage Example
 
 ```typescript
 import {
-  ProductReleaseCard,
-  ProductReleaseCardSkeleton,
+  ProductReleasesView,
   ReleaseDetailPage,
   ReleaseDetailSkeleton,
-  type ReleaseDetailPageProps,
+  type ProductReleaseCardExtras,
   type DeliveryResponse,
 } from '@flamingo-stack/openframe-frontend-core/components/shared/product-release'
+```
 
-// Render a release card
-<ProductReleaseCard title="v2.1.0" date="2025-06-01" />
+For slot types not exposed here:
 
-// Deep import for internal slot types
+```typescript
 import type { RoadmapSectionProps } from '@flamingo-stack/openframe-frontend-core/components/shared/product-release/release-detail-page'
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/product-release/.product-releases-view.md b/openframe-frontend-core/src/components/shared/product-release/.product-releases-view.md
new file mode 100644
index 000000000..176d23d3d
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/product-release/.product-releases-view.md
@@ -0,0 +1,42 @@
+<!-- source-hash: 12df6264efd81d55770e0ad3e4556641 -->
+Self-contained releases list surface that fetches, paginates, and renders product release cards driven entirely by URL search params — no external state management required.
+
+## Key Components
+
+### `ProductReleasesView` (main export)
+The primary list component. Reads `search`, `release_status`, and `page` URL params written by the section chrome, fetches the configured endpoint via `useSelfFetch`, and renders a stable fixed-slot grid of `ProductReleaseCard` entries with loading skeletons and pagination.
+
+### `ReleaseRow` (internal)
+Per-release child component that isolates per-item hooks (`useChatRuntime`, `useEntityCardLink`, `useRouter`) out of the parent `.map()` to satisfy Rules of Hooks. Resolves the detail href via `resolveContentHref` and handles soft/hard navigation via `executeNavigationImperative`.
+
+### `ProductReleaseCardExtras` (exported type)
+Subset of `ProductReleaseCardProps` — the caller-supplied fields per release, excluding nav/layout props that the view owns internally.
+
+## Key Behaviors
+
+- **SSR hydration** — pass `initialData` to skip the first client fetch
+- **Stable layout** — always renders `itemsPerPage` slots; uses `visibility` toggling to prevent height shifts during loading/empty transitions
+- **Filter reset** — clears `search`, `release_status`, and `page` params atomically via `router.replace`
+- **Custom card builder** — defaults to `buildProductReleaseCardProps` (rich `lg` metadata); override via `buildCardProps` prop
+
+## Usage Example
+
+```typescript
+import { ProductReleasesView } from './product-releases-view'
+
+// Minimal — uses all defaults
+<ProductReleasesView />
+
+// With SSR hydration and custom endpoint
+<ProductReleasesView
+  endpoint="/api/v2/releases"
+  initialData={serverFetchedData}
+  itemsPerPage={10}
+  basePath="/changelog"
+  buildCardProps={(release) => ({
+    formattedDate: formatDate(release.published_at),
+    type: release.type,
+    status: release.status,
+  })}
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/roadmap/.index.md b/openframe-frontend-core/src/components/shared/roadmap/.index.md
index e6d44918b..776c23cd5 100644
--- a/openframe-frontend-core/src/components/shared/roadmap/.index.md
+++ b/openframe-frontend-core/src/components/shared/roadmap/.index.md
@@ -1,37 +1,34 @@
-<!-- source-hash: 499214f4840bb2650161d384a662b71b -->
-Barrel export file for the shared roadmap surface, exposing grid components and voting hook while intentionally omitting `RoadmapItem` and `VoteType` to prevent TypeScript TS2308 ambiguous re-export errors.
+<!-- source-hash: 84846be8d32682355ecb5cfae1b2e793 -->
+Barrel export file for the shared roadmap surface, re-exporting grid, skeleton, voting hook, and view components while deliberately excluding `RoadmapItem` and `VoteType` to avoid TypeScript TS2308 ambiguous re-export conflicts.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `RoadmapGrid` | Component | Main grid layout for displaying roadmap items |
-| `RoadmapGridProps` | Type | Props interface for `RoadmapGrid` |
-| `RoadmapGridSkeleton` | Component | Loading skeleton for the roadmap grid |
-| `RoadmapGridSkeletonProps` | Type | Props interface for `RoadmapGridSkeleton` |
-| `useRoadmapVoting` | Hook | Hook encapsulating roadmap voting logic |
-| `VoteState` | Type | State shape for a vote interaction |
-| `UseRoadmapVotingOptions` | Type | Options interface for `useRoadmapVoting` |
+| `RoadmapGrid` / `RoadmapGridProps` | Component | Grid layout for displaying roadmap items |
+| `RoadmapGridSkeleton` / `RoadmapGridSkeletonProps` | Component | Loading skeleton for the roadmap grid |
+| `useRoadmapVoting` / `VoteState` / `UseRoadmapVotingOptions` | Hook + Types | Voting logic and state management for roadmap items |
+| `RoadmapView` / `RoadmapViewProps` | Component | Self-fetching roadmap surface; host only configures API routes |
 
-## Intentionally Omitted Exports
+## Intentional Omissions
 
-| Omitted | Reason | Canonical Import Path |
-|---------|--------|-----------------------|
-| `RoadmapItem` | Already exported via two paths; a third triggers TS2308 | `@flamingo-stack/openframe-frontend-core/components/chat` |
-| `VoteType` | Duplicate of the same type re-exported from `./chat` | `@flamingo-stack/openframe-frontend-core/components/chat` |
+- **`RoadmapItem`** — already exported via two canonical paths; a third would trigger TS2308
+- **`VoteType`** — canonical export lives in `@flamingo-stack/openframe-frontend-core/components/chat`
 
 ## Usage Example
 
 ```typescript
-// ✅ Import roadmap surface components from this barrel
+// Import roadmap surface components
 import {
   RoadmapGrid,
   RoadmapGridSkeleton,
+  RoadmapView,
   useRoadmapVoting,
-  type VoteState,
-  type UseRoadmapVotingOptions,
-} from '@flamingo-stack/openframe-frontend-core/components/shared/roadmap';
+} from '@flamingo-stack/openframe-frontend-core/components/roadmap';
 
-// ✅ Import omitted types from their canonical paths
-import type { RoadmapItem, VoteType } from '@flamingo-stack/openframe-frontend-core/components/chat';
-```
\ No newline at end of file
+// Import excluded types from their canonical paths
+import type { RoadmapItem } from '@flamingo-stack/openframe-frontend-core/components/chat';
+import type { VoteType } from '@flamingo-stack/openframe-frontend-core/components/chat';
+```
+
+> **Note:** Never import `RoadmapItem` or `VoteType` from this barrel. Use the canonical paths above to avoid ambiguous re-export errors across the component barrel hierarchy.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/roadmap/.roadmap-grid.md b/openframe-frontend-core/src/components/shared/roadmap/.roadmap-grid.md
index 33d5d7fd8..649ab75b8 100644
--- a/openframe-frontend-core/src/components/shared/roadmap/.roadmap-grid.md
+++ b/openframe-frontend-core/src/components/shared/roadmap/.roadmap-grid.md
@@ -1,66 +1,40 @@
-<!-- source-hash: afe909dc035ab417a954948a391b890a -->
-Full-page roadmap surface that renders a responsive 2-column grid of `RoadmapCard` components with integrated voting state and live count refresh.
+<!-- source-hash: ef1bcf17b92482b3f568f6c8dfedbc0f -->
+Shared roadmap list surface that renders roadmap items either as a flat 2-column grid or grouped into collapsible per-quarter accordions, with unified voting state across all sections.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `RoadmapGrid` | Component | Main grid component rendering all roadmap items |
-| `RoadmapGridProps` | Interface | Component prop contract |
-| `DEFAULT_BUILD_REFRESH_URL` | Constant | Default URL builder: `(taskId) => /api/roadmap/${taskId}` |
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `RoadmapItem[]` | — | Roadmap entries to display |
-| `onItemUpdate` | `(item: RoadmapItem) => void` | — | Callback fired after a successful vote refresh |
-| `showLeftMargin` | `boolean` | `true` | Applies `md:ml-[120px]` for hero alignment; pass `false` for rails |
-| `buildRefreshUrl` | `(taskId: string) => string` | `DEFAULT_BUILD_REFRESH_URL` | Path-based URL builder for per-task refresh after vote |
-| `votingOptions` | `UseRoadmapVotingOptions` | — | Vote endpoint + storage key forwarded to `useRoadmapVoting` |
-
-## Voting Flow
-
-```mermaid
-graph TD
-    A["User Clicks Vote"] --> B{"Task Already Voting?"}
-    B -->|Yes| C["Ignore / No-op"]
-    B -->|No| D["Lock Task ID in votingTasks"]
-    D --> E["toggleVote()"]
-    E --> F{"result.success?"}
-    F -->|No| G["Unlock Task ID"]
-    F -->|Yes| H["GET buildRefreshUrl(taskId)"]
-    H --> I{"response.ok?"}
-    I -->|Yes| J["onItemUpdate(data.item)"]
-    I -->|No| G
-    J --> G
-```
+- **`RoadmapGrid`** — Main export. Handles quarter bucketing, chronological sorting, accordion expand/collapse state (hydration-safe), and shared voting logic.
+- **`RoadmapGridSingle`** — Internal flat 2-col grid for a single set of items; receives voting state from parent to prevent race conditions across quarters.
+- **`computeDefaultExpandedQuarters`** — Pure helper that determines which quarters expand by default (current + future quarters, recent past within `quartersToKeepClosed` window).
+- **`useRoadmapVoting`** — External hook providing `getVote` / `toggleVote`; instantiated once at `RoadmapGrid` level and shared downward.
 
 ## Usage Example
 
 ```typescript
-import { RoadmapGrid } from './roadmap-grid';
-import type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
-
-function RoadmapPage({ items }: { items: RoadmapItem[] }) {
-  const [roadmapItems, setRoadmapItems] = useState(items);
-
-  const handleItemUpdate = (updated: RoadmapItem) => {
-    setRoadmapItems(prev =>
-      prev.map(i => (i.id === updated.id ? updated : i))
-    );
-  };
-
-  return (
-    <RoadmapGrid
-      items={roadmapItems}
-      onItemUpdate={handleItemUpdate}
-      showLeftMargin={true}
-      buildRefreshUrl={(taskId) => `/api/roadmap/${taskId}`}
-      votingOptions={{ endpoint: '/api/votes', storageKey: 'roadmap-votes' }}
-    />
-  );
-}
+// Full-page grouped mode (e.g. RoadmapView)
+<RoadmapGrid
+  items={roadmapItems}
+  groupByQuarter={true}
+  hasActiveFilters={searchQuery.length > 0}
+  quartersToKeepClosed={2}
+  onItemUpdate={(updated) => patchList(updated)}
+  votingOptions={{ endpoint: '/api/roadmap/vote', storageKey: 'roadmap-votes' }}
+  buildRefreshUrl={(taskId) => `/api/roadmap/${taskId}`}
+/>
+
+// Flat mode for related-content rails (existing callers unchanged)
+<RoadmapGrid
+  items={filteredItems}
+  showLeftMargin={false}
+  groupByQuarter={false}
+/>
 ```
 
-> **Note on `buildRefreshUrl`:** This prop is intentionally a function rather than a string template to safely support embedders whose by-id route shape differs (e.g. `/api/roadmap?id=…`). String concatenation would silently break non-standard routes.
\ No newline at end of file
+## Behavior Notes
+
+| Prop | Default | Effect |
+|---|---|---|
+| `groupByQuarter` | `false` | `true` enables accordion quarter grouping |
+| `hasActiveFilters` | `false` | `true` forces all quarters to expand |
+| `quartersToKeepClosed` | `2` | Past quarters older than N quarters collapse by default |
+| `showLeftMargin` | `true` | Pass `false` for embedded/rail contexts |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/shared/roadmap/.roadmap-view.md b/openframe-frontend-core/src/components/shared/roadmap/.roadmap-view.md
new file mode 100644
index 000000000..11724ac3f
--- /dev/null
+++ b/openframe-frontend-core/src/components/shared/roadmap/.roadmap-view.md
@@ -0,0 +1,32 @@
+<!-- source-hash: 8f3ce77b2789653875b5e5f2873e58fe -->
+Self-contained roadmap list surface that fetches and renders roadmap items with filtering, SSR hydration, and live vote patching.
+
+## Key Components
+
+- **`RoadmapView`** — Primary export; orchestrates data fetching via `useSelfFetch`, reads URL search params for filtering, and delegates rendering to `RoadmapGrid`
+- **`RoadmapViewProps`** — Configuration interface exposing API routes (`endpoint`, `buildRefreshUrl`, `votingOptions`), SSR hydration (`initialItems`), and URL param keys (`searchParamKey`, `statusParamKey`)
+
+## Behavior Notes
+
+- **Filtering**: Reads `search` and `status` from URL params (written by the section chrome `DevSectionView`) and folds them into the fetch URL — the URL acts as the cache key, triggering refetches on filter changes
+- **SSR hydration**: `initialItems` is memoized into a stable `initialData` reference to prevent the `useSelfFetch` re-sync effect from clobbering optimistic vote patches
+- **Loading states**: Shows `RoadmapGridSkeleton` only during the first fetch (no data yet); malformed responses without `items` render an empty grid rather than a stuck skeleton
+- **Live vote patching**: `onItemUpdate` patches the updated task back into local state after a per-task refresh, keeping vote counts live without a full list reload
+
+## Usage Example
+
+```typescript
+// Minimal — uses all defaults (/api/roadmap, standard param keys)
+<RoadmapView />
+
+// Full configuration with SSR hydration and custom API routes
+<RoadmapView
+  endpoint="/api/my-roadmap"
+  initialItems={serverSideItems}
+  showLeftMargin
+  buildRefreshUrl={(id) => `/api/my-roadmap/${id}`}
+  votingOptions={{ voteEndpoint: '/api/vote', storageKey: 'roadmap-votes' }}
+  searchParamKey="q"
+  statusParamKey="status"
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/.help-center-card.md b/openframe-frontend-core/src/components/tickets/.help-center-card.md
index 889b468de..58c40b6db 100644
--- a/openframe-frontend-core/src/components/tickets/.help-center-card.md
+++ b/openframe-frontend-core/src/components/tickets/.help-center-card.md
@@ -1,38 +1,21 @@
-<!-- source-hash: a4fe8194703f767fe2216ee1b9351f99 -->
-A client-side React component that renders a single support ticket row in the Help Center list, featuring a toggleable expanded drawer for full ticket interaction.
+<!-- source-hash: 4378ab9a5b31b31dbefc8fedc83bc862 -->
+Single ticket row component for the Help Center list that renders a summary button toggling an expandable `<TicketDetailDrawer />` beneath it.
 
 ## Key Components
 
-### `HelpCenterCard` (default export)
-The primary component rendering a ticket summary row as a clickable `<button>` that toggles a `<TicketDetailDrawer>` below it. Key behaviors:
+**`HelpCenterCard`** — Main exported component. Renders a clickable summary row using `<DevCardRowContent>` (shared with the delivery list) with an optional `<TicketDetailDrawer>` sibling that expands below on toggle.
 
-- **Optimistic rows** are rendered as non-expandable (dimmed, `opacity-60`) until the server confirms the ticket ID
-- **Scroll-on-expand** uses `scrollElementIntoView` with a cross-row layout-shift correction — compensates when a sibling drawer above collapses simultaneously, shifting the page Y position
-- **Sticky header offset** (`STICKY_HEADER_OFFSET_PX = 96`) is applied both as `scrollMarginTop` inline style (for browser/anchor scrolls) and as `headerOffset` (for programmatic scroll), keeping them in sync from a single constant
+**`HelpCenterCardProps`** — Interface defining ticket data, expanded/busy state, event handlers (`onToggle`, `onSendMessage`, `onClose`, `onReopen`, `onActionCollapsed`), and optional reply-error props forwarded to the drawer.
 
-### `HelpCenterCardProps`
-```typescript
-interface HelpCenterCardProps {
-  ticket: AnyTicket
-  expanded: boolean
-  onToggle: (id: string) => void
-  busy: boolean
-  supportSystemDown: boolean
-  onSendMessage: TicketDetailDrawerProps['onSendMessage']
-  onClose: TicketDetailDrawerProps['onClose']
-  onReopen: TicketDetailDrawerProps['onReopen']
-  onActionCollapsed: () => void
-}
-```
-
-### `mapPriorityScheme` (internal)
-Maps ticket priority strings to `StatusBadge` color schemes. Kept separate from the shared `getStatusColorScheme` to avoid conflating workflow status with severity.
-
-| Priority | Color Scheme |
-|----------|-------------|
-| `HIGH` / `URGENT` | `error` (red) |
-| `MEDIUM` | `warning` (yellow) |
-| `LOW` / unknown | `default` |
+**`mapPriorityScheme`** — Local helper mapping ticket priority strings (`HIGH`, `URGENT`, `MEDIUM`, `LOW`) to `StatusBadge` color schemes. Kept separate from the workflow-status `getStatusColorScheme` to avoid badge mis-rendering.
+
+**`STICKY_HEADER_OFFSET_PX`** — Single constant (`96`) governing both `scrollMarginTop` inline style (CSS anchor/Tab-focus scroll) and the `headerOffset` passed to `scrollElementIntoView` (click-to-expand path). One source of truth for both scroll correction strategies.
+
+## Notable Behaviors
+
+- **Optimistic tickets** (pending `external_id`) render as non-expandable rows at 60% opacity — the drawer requires a real ID to fetch engagements.
+- **Scroll-on-expand** uses a rAF-deferred `scrollElementIntoView` call in a `useEffect` keyed on `isExpanded`, intentionally not in the click handler. This avoids the browser scroll-anchoring bug that cancelled native smooth scrolls on every open after the first.
+- **Click isolation** — the drawer is a sibling of the toggle `<button>`, not a child, so drawer interactions never bubble to the row's toggle handler.
 
 ## Usage Example
 
@@ -44,8 +27,10 @@ Maps ticket priority strings to `StatusBadge` color schemes. Kept separate from
   busy={isBusy}
   supportSystemDown={false}
   onSendMessage={handleSendMessage}
-  onClose={handleCloseTicket}
-  onReopen={handleReopenTicket}
+  onClose={handleClose}
+  onReopen={handleReopen}
   onActionCollapsed={() => setExpandedId(null)}
+  replyError={replyErrors[ticket.external_id]}
+  onClearReplyError={() => clearReplyError(ticket.external_id)}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/.help-center-list.md b/openframe-frontend-core/src/components/tickets/.help-center-list.md
index 935a686b0..aa80ab314 100644
--- a/openframe-frontend-core/src/components/tickets/.help-center-list.md
+++ b/openframe-frontend-core/src/components/tickets/.help-center-list.md
@@ -1,28 +1,30 @@
-<!-- source-hash: 827d4c23e1bcd10b78b97232f2822fa0 -->
-Renders the full Help Center surface for authenticated users, providing ticket listing, creation, filtering, pagination, and optimistic UI updates. Serves as the primary component mounted on the `/tickets` route in OpenFrame.
+<!-- source-hash: 64a1e228f84c4998c0ec7514f43ae09c -->
+Renders the full Help Center surface for the `/tickets` page, managing ticket listing, creation, optimistic updates, and drawer state via URL params.
 
 ## Key Components
 
-- **`HelpCenterList`** — Public entry point. Guards against unauthenticated access (renders skeleton during identity load, `EmptyState` for anon users), then delegates to `HelpCenterListAuthed`.
-- **`HelpCenterListAuthed`** — Internal component handling all authenticated state: merges optimistic + server tickets, manages expanded row, wires mutation callbacks, and composes the full page layout via `<DevSectionPage>`.
-- **`HelpCenterListProps`** — Accepts an optional `toast` override for testability.
+**`HelpCenterList`** — Public entry point. Handles identity gating: renders a skeleton during auth resolution, an `EmptyState` sign-in prompt for anonymous users, or delegates to the authed sub-component.
 
-**Key hooks used:**
-- `useTicketsList` — fetches paginated tickets by `search`, `status`, `page`
-- `useTicketActions` — mutations (submit, close, reopen, send message) with optimistic callbacks
-- `useChatIdentity` — resolves session email/name; guards the auth gate
+**`HelpCenterListAuthed`** — Internal component (not exported) that owns all authenticated state and logic:
+- `optimisticTickets` — local placeholder state (intentionally outside TanStack cache)
+- `setOpenTicket` — writes/clears `?ticket=<external_id>` URL param to control drawer state
+- `removeTicketFromCache` — safely removes a ticket from all `['tickets']` query cache slots via `setQueriesData`
+- `toggleRow` — maps internal ticket `id` → `external_id` for URL-driven open/close
+
+**`HelpCenterListProps`** — Single exported interface; accepts an optional `toast` override for testing.
 
 ## Usage Example
 
 ```typescript
-// Mounted directly on the /tickets page (OpenFrame):
-import { HelpCenterList } from './help-center-list'
+// Mount on the /tickets page (Next.js App Router)
+import { HelpCenterList } from '@/components/help-center/help-center-list'
 
 export default function TicketsPage() {
   return <HelpCenterList />
 }
 
-// With toast override for testing:
+// With toast override in tests
+import { render } from '@testing-library/react'
 import { mockToast } from '../test-utils'
 
 render(<HelpCenterList toast={mockToast} />)
@@ -30,11 +32,14 @@ render(<HelpCenterList toast={mockToast} />)
 
 ## State Model
 
-```text
-URL params        → search, status, page   (read by useTicketsList)
-optimisticTickets → local useState          (prepend on submit, remove on settle)
-expandedTicketId  → local useState          (single drawer open at a time)
-supportSystemDown → local useState          (disables create form on error)
+```mermaid
+graph TD
+    A["URL Params"] -->|"?search= ?status= ?page="| B["useTicketsList"]
+    A -->|"?ticket=<external_id>"| C["expandedTicketId (derived)"]
+    D["optimisticTickets (local state)"] --> E["merged: AnyTicket[]"]
+    B --> E
+    E --> F["HelpCenterCard list"]
+    C --> F
 ```
 
-> **Note:** Optimistic placeholders are kept in local state (not the TanStack query cache) so URL filter changes don't discard in-flight submissions mid-render.
\ No newline at end of file
+> URL params are the single source of truth for open drawer, search, status, and pagination. Optimistic placeholders are kept in local state — not the TanStack cache — so filter/page refetches don't evict in-flight placeholders.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/.index.md b/openframe-frontend-core/src/components/tickets/.index.md
index 4dcbec1a4..6a239fc5a 100644
--- a/openframe-frontend-core/src/components/tickets/.index.md
+++ b/openframe-frontend-core/src/components/tickets/.index.md
@@ -1,65 +1,53 @@
-<!-- source-hash: 9ab6eac897ae7fbb7ae6454201513bed -->
-Barrel export file for the tickets feature module, re-exporting all public components, hooks, and types related to ticket management and the Help Center UI.
+<!-- source-hash: b1b3afa2679df984c26b9b2281cbbe54 -->
+Barrel export file for the Tickets feature module, re-exporting all public components, hooks, and types related to ticket management and the Help Center surface.
 
 ## Key Components
 
-### Components
-| Export | Description |
-|--------|-------------|
-| `TicketCenter` | Main ticket management surface |
-| `TicketOpenForm` | Form for opening new tickets |
-| `TicketRow` | Individual ticket row renderer |
-| `TicketDetailDrawer` | Slide-out drawer for ticket details |
-| `TicketLinkedDeliveryCard` | Card linking a ticket to a delivery |
-| `HelpCenterList` | Full-page customer-facing ticket list, used by OpenFrame's `/tickets` route |
-| `HelpCenterCard` | Expandable card for a single Help Center entry |
-| `HelpCenterCreateForm` / `HelpCenterCreateFormSkeleton` | Ticket creation form with loading skeleton |
-
-### Hooks
-| Export | Description |
-|--------|-------------|
-| `useTicketsList` | Fetches and manages the tickets list state |
-| `useTicketActions` | Provides ticket mutation actions; `mapTicketActionError` maps error codes |
-| `useTicketEngagements` | Manages ticket engagement threads and file attachments |
-
-### Types & Constants
-| Export | Description |
-|--------|-------------|
-| `TicketData`, `AnyTicket`, `OptimisticTicket` | Core ticket data shapes |
-| `TicketClickupSummary` | ClickUp-specific ticket summary |
-| `TicketActionErrorCode`, `MappedTicketActionError` | Typed error handling |
-| `TICKET_TOAST_COPY` | Toast notification copy constants |
-| `isOptimistic` | Type guard for optimistic ticket entries |
-| `TicketRef`, `TicketEngagement`, `TicketEngagementFile` | Supporting types |
+**Components**
+- `TicketCenter` — Main ticket management interface
+- `TicketOpenForm` — Form for opening new tickets
+- `TicketRow` — Individual ticket row renderer
+- `TicketDetailDrawer` — Slide-out drawer for ticket details (exposes `TicketRef`)
+- `TicketLinkedDeliveryCard` — Card showing delivery items linked to a ticket
+- `TicketReplyComposer` — Composer UI for replying to tickets
+- `HelpCenterList` — Full-page customer-facing ticket surface for OpenFrame's `/tickets` route; composable inside third-party `<PageShell>` wrappers
+- `HelpCenterCard` — Individual card within the Help Center list
+- `HelpCenterCreateForm` / `HelpCenterCreateFormSkeleton` — Ticket creation form with loading skeleton
+
+**Hooks**
+- `useTicketsList` — Fetches and manages the ticket list state
+- `useTicketActions` — CRUD actions for tickets; exposes `mapTicketActionError` helper
+- `useTicketEngagements` — Manages ticket engagement threads and file attachments
+
+**Types & Constants**
+- `TicketData`, `OptimisticTicket`, `AnyTicket` — Core ticket data shapes
+- `TicketClickupSummary` — ClickUp integration summary type
+- `TicketActionErrorCode` / `MappedTicketActionError` — Structured error handling
+- `TICKET_TOAST_COPY` — Toast notification strings
+- `isOptimistic` — Type guard for optimistic ticket entries
 
 ## Usage Example
 
 ```typescript
 import {
   HelpCenterList,
-  TicketDetailDrawer,
   useTicketsList,
   useTicketActions,
   isOptimistic,
   type AnyTicket,
 } from '@/features/tickets'
 
-function TicketsPage() {
+function MyTicketPage() {
   const { tickets } = useTicketsList()
   const { closeTicket } = useTicketActions()
 
   return (
-    <HelpCenterList>
-      {tickets.map((ticket: AnyTicket) => (
-        <TicketDetailDrawer
-          key={isOptimistic(ticket) ? ticket.optimisticId : ticket.id}
-          ticket={ticket}
-          onClose={() => closeTicket(ticket.id)}
-        />
-      ))}
-    </HelpCenterList>
+    <HelpCenterList
+      tickets={tickets}
+      onClose={(ticket: AnyTicket) => {
+        if (!isOptimistic(ticket)) closeTicket(ticket.id)
+      }}
+    />
   )
 }
-```
-
-> **Note:** Third-party embedders can mount `<HelpCenterList />` inside their own `<PageShell>` to get the full Help Center UX without the OpenFrame route wrapper.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/.ticket-detail-drawer.md b/openframe-frontend-core/src/components/tickets/.ticket-detail-drawer.md
index 5dca66cd6..bcc109df8 100644
--- a/openframe-frontend-core/src/components/tickets/.ticket-detail-drawer.md
+++ b/openframe-frontend-core/src/components/tickets/.ticket-detail-drawer.md
@@ -1,23 +1,19 @@
-<!-- source-hash: 8a7542421be9aaeac5211827f8967375 -->
-Expanded drawer component for a single ticket's detail view, rendering the conversation timeline, metadata, and status-dependent actions (reply/close/reopen).
+<!-- source-hash: d5729deddb6f8a091db5e9b6f5e0f0a4 -->
+Expanded drawer view for a single support ticket, rendering the conversation timeline, metadata, and status-dependent actions (reply composer or reopen control).
 
 ## Key Components
 
-### `TicketDetailDrawer` (main export)
-The root drawer component that composes the full expanded ticket view:
-- Renders optional linked ClickUp delivery card
-- Delegates conversation rendering to `TicketTimelinePanel`
-- Conditionally renders `OpenActions` or `ReopenAction` based on ticket status
+**`TicketDetailDrawer`** — Root exported component. Accepts a ticket, busy/error state, and mutation callbacks; renders the full expanded panel including assignee header, optional ClickUp delivery card, conversation timeline, reply-failure banner, and action controls.
 
-### `TicketTimelinePanel`
-Internal component that builds a chronological conversation thread:
-- Splits legacy `ticket.body` on ` --- ` separators for historical compatibility
-- Fetches Note engagements via `useTicketEngagements`
-- Resolves customer identity with a 4-level precedence chain (live identity → mirror name → email → "You")
-- Shows skeleton loader during initial fetch; `EmptyState` when no content exists
+**`TicketTimelinePanel`** — Internal component that fetches and renders the chronological conversation. Uses `useTicketEngagements` with live polling (`TICKET_LIVE_POLL_MS`), `useStickToBottom` for auto-scroll, and splits legacy `ticket.body` multi-turn strings on the `---` separator. Suppresses the "Original message" body turn when a matching customer engagement already exists.
 
-### `TicketRef`
-Minimal identity bundle (`id` + `external_id`) threaded through mutation callbacks — `external_id` targets HubSpot, `id` drives React/TanStack cache keys.
+**`AssignedAgentRow`** — Displays the assigned support agent (or "Unassigned" fallback).
+
+**`ReopenAction`** — Shown when `ticket.status === 'CLOSED'`; calls `onReopen` then `onActionCollapsed`.
+
+**`ReplyFailureBanner`** — Persistent inline error banner above the composer for failed send attempts; distinct from transient toasts.
+
+**`TicketRef`** — Exported type `{ id: string; external_id: string }` passed to all action callbacks.
 
 ## Usage Example
 
@@ -27,22 +23,14 @@ Minimal identity bundle (`id` + `external_id`) threaded through mutation callbac
   busy={isMutating}
   supportSystemDown={false}
   onSendMessage={async (ref, text, attachments) => {
-    await sendNoteEngagement(ref.external_id, text, attachments)
-    return true
-  }}
-  onClose={async (ref, resolution) => {
-    await closeTicket(ref.external_id, resolution)
-    return true
-  }}
-  onReopen={async (ref) => {
-    await reopenTicket(ref.external_id)
-    return true
+    return await actions.sendMessage(ref, text, attachments)
   }}
+  onClose={async (ref, resolution) => actions.closeTicket(ref, resolution)}
+  onReopen={async (ref) => actions.reopenTicket(ref)}
   onActionCollapsed={() => setDrawerOpen(false)}
+  replyError={replyError}
+  onClearReplyError={() => actions.clearReplyError(ticket.external_id)}
 />
 ```
 
-## Notes
-- All local state (composer text, attachments, close-confirm dialog) is owned here; parent owns ticket data and mutation callbacks
-- Optimistic tickets (pre-server-confirmation) skip the engagement fetch until a real `external_id` is available
-- The timeline intentionally has no inner scroll — content flows with the page to avoid competing scroll surfaces
\ No newline at end of file
+The parent owns ticket data and mutation state; this component manages only local UI state (composer text, attachment bag, close-confirm dialog).
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/.ticket-reply-composer.md b/openframe-frontend-core/src/components/tickets/.ticket-reply-composer.md
new file mode 100644
index 000000000..0fecead83
--- /dev/null
+++ b/openframe-frontend-core/src/components/tickets/.ticket-reply-composer.md
@@ -0,0 +1,35 @@
+<!-- source-hash: d48a2a82c23200567034e210dc847d5a -->
+Reply composer for open tickets, combining a shared `ChatInput` with file attachment support and a confirmation dialog for closing tickets.
+
+## Key Components
+
+- **`TicketReplyComposer`** — Main exported component that renders the full reply UI
+- **`TicketReplyComposerProps`** — Interface defining required props: `ticket`, `busy`, `supportSystemDown`, `onSendMessage`, `onClose`
+- **`useChatAttachments`** — Hook managing staged file attachments (add, remove, clear, inflight tracking)
+- **`ChatInput`** — Shared input component handling send semantics, max length, and disabled states
+- **`AlertDialog`** — Confirmation dialog for closing a ticket with an optional resolution note
+
+## Behavior Notes
+
+- **Send resilience** — Draft text and staged files survive a failed send; `attachments.clear()` is only called on success
+- **Attachment-only replies** — `allowEmptySend` enables sending when files are staged but no text is typed
+- **Disabled states** — Input is blocked while `busy` OR uploads are inflight; the attach `+` button is hidden entirely when `supportSystemDown`
+- **Close is non-destructive** — Styled as a low-emphasis text button (not red/destructive) since closing is reversible via Reopen
+- **No drawer collapse** — `confirmClose` intentionally omits `onActionCollapsed` to preserve the ticket row in view after closure
+
+## Usage Example
+
+```typescript
+<TicketReplyComposer
+  ticket={ticket}
+  busy={isSending}
+  supportSystemDown={!isConnected}
+  onSendMessage={async (ref, text, files) => {
+    const ok = await sendReply(ref, text, files)
+    return ok
+  }}
+  onClose={async (ref, resolution) => {
+    await closeTicket(ref, resolution)
+  }}
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/.types.md b/openframe-frontend-core/src/components/tickets/.types.md
index 96f983f28..088159983 100644
--- a/openframe-frontend-core/src/components/tickets/.types.md
+++ b/openframe-frontend-core/src/components/tickets/.types.md
@@ -1,19 +1,27 @@
-<!-- source-hash: 63b1778d9923d2e7914bfaebf859d9ff -->
-Defines the shared type contract for the ticket management feature, including wire shapes for ticket data returned from the `POST /api/chat/agent/find-ticket` endpoint, optimistic UI helpers, error handling types, and UI constants.
+<!-- source-hash: eaad96fbee2b55e506fa06a65db08f00 -->
+Defines the complete type contract for the ticket management system, including wire shapes, cache slot structure, error codes, and UI constants shared across the ticket center, drawer, and action helpers.
 
 ## Key Components
 
-| Export | Kind | Description |
-|--------|------|-------------|
-| `TicketData` | Interface | Wire shape of a ticket row from the find-ticket API, mirroring the server's `FindTicketResult` projection |
-| `TicketClickupSummary` | Interface | Compact projection of a linked ClickUp task for the ticket drawer's delivery card |
-| `OptimisticTicket` | Interface | Extends `TicketData` with `_optimistic: true` for pre-flight UI placeholders |
-| `AnyTicket` | Type | Union of `TicketData \| OptimisticTicket` |
-| `isOptimistic()` | Type Guard | Narrows `AnyTicket` to `OptimisticTicket` |
-| `TicketActionErrorCode` | Type | Discriminated string union of stable server-side error codes |
-| `MappedTicketActionError` | Interface | Structured error envelope with toast copy, cache hints, and retry metadata |
-| `TICKET_TEXT_MAX_CHARS` | Constant | Client-side cap of `5000` chars for ticket text inputs |
-| `TOAST_COPY` | Constant | Centralized `as const` map of all user-visible toast strings |
+**Interfaces**
+- `TicketData` — Primary wire shape returned by `POST /api/chat/agent/find-ticket`; includes HubSpot fields, ClickUp link, assigned owner, and customer info
+- `TicketAssignedOwner` — Resolved agent profile (name, email, avatar) for drawer header attribution
+- `TicketClickupSummary` — Compact linked ClickUp task projection; aligns with `DeliveryItem` for shared rendering primitives
+- `OptimisticTicket` — Extends `TicketData` with `_optimistic: true` for pre-server-roundtrip list prepending
+- `TicketsCacheSlot` — Typed shape for `['tickets', …]` TanStack Query cache slots; prevents bare-array assumptions
+- `MappedTicketActionError` — Normalized error envelope with routing flags (`supportSystemDown`, `removeRowFromCache`)
+
+**Types**
+- `AnyTicket` — Union of `TicketData | OptimisticTicket`
+- `TicketActionErrorCode` — Discriminated string union of all known server error codes
+
+**Functions**
+- `isOptimistic(t)` — Type guard narrowing `AnyTicket` to `OptimisticTicket`
+
+**Constants**
+- `TICKET_TEXT_MAX_CHARS` — Client-side cap (`5000`) for ticket content
+- `TICKET_LIVE_POLL_MS` — Shared refresh cadence (`8000`ms) for list + conversation polls
+- `TOAST_COPY` — Centralized user-visible toast strings
 
 ## Usage Example
 
@@ -21,37 +29,39 @@ Defines the shared type contract for the ticket management feature, including wi
 import {
   AnyTicket,
   isOptimistic,
+  TicketsCacheSlot,
   MappedTicketActionError,
-  TICKET_TEXT_MAX_CHARS,
+  TICKET_LIVE_POLL_MS,
   TOAST_COPY,
 } from './types'
 
-// Narrow optimistic rows before rendering the drawer
+// Type guard for optimistic rows
 function renderTicket(ticket: AnyTicket) {
-  if (isOptimistic(ticket)) {
-    return <SkeletonDrawer />
-  }
-  return <TicketDrawer data={ticket} />
+  if (isOptimistic(ticket)) return <SkeletonRow />
+  return <TicketRow data={ticket} />
 }
 
-// Validate user input before submission
-if (content.length > TICKET_TEXT_MAX_CHARS) {
-  throw new Error(`Max ${TICKET_TEXT_MAX_CHARS} characters allowed`)
-}
+// Cache mutation typed through slot shape
+queryClient.setQueriesData<TicketsCacheSlot>(
+  { queryKey: ['tickets'] },
+  (old) => ({
+    ...old,
+    tickets: old?.tickets?.map((t) =>
+      t.id === updatedId ? { ...t, status: 'CLOSED' } : t
+    ),
+  })
+)
 
-// Handle a mapped server error
+// Live poll wired to shared constant
+useTicketsList({ refetchInterval: TICKET_LIVE_POLL_MS })
+
+// Toast on success
+toast(TOAST_COPY.close_success)
+
+// Error routing
 function handleError(err: MappedTicketActionError) {
-  if (err.supportSystemDown) {
-    showSupportDownBanner()
-  }
-  if (err.removeRowFromCache) {
-    removeTicketFromList(ticketId)
-  }
+  if (err.supportSystemDown) showSystemDownBanner()
+  if (err.removeRowFromCache) evictTicketRow(err)
   toast({ title: err.message })
 }
-
-// Use centralized toast copy on success
-toast(TOAST_COPY.open_success)
-```
-
-> **Note:** `TicketData` is intentionally duplicated from the server's `FindTicketResult`. If `FIND_TICKET_SELECT` gains a new column server-side, this interface must be updated to match.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-actions.md b/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-actions.md
index e9a1621fc..8f1adb9f5 100644
--- a/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-actions.md
+++ b/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-actions.md
@@ -1,39 +1,33 @@
-<!-- source-hash: 6164b984e1688be647fedf5037a794eb -->
-Brief description of the file's purpose: This hook encapsulates all ticket write operations (create, update, close, reopen, reply) for the Flamingo/OpenFrame tickets UI, routing them through a single `/api/chat/agent/ticket-action` endpoint with single-flight protection, per-row mutexes, a serialization queue, and mirror-sync retry logic.
+<!-- source-hash: 796f4de978f2839e050490253300131c -->
+Handles all ticket write operations (create, update, close, reopen, reply) through a single POST endpoint, with optimistic UI updates, per-row mutex guards, serialized mutation queuing, and mirror-sync retry logic.
 
 ## Key Components
 
-### `useTicketActions(options: UseTicketActionsOptions): UseTicketActionsReturn`
-The primary exported hook. Accepts callback options from the parent and returns ticket action handlers plus loading state selectors.
+### `useTicketActions(options)`
+Main hook export. Accepts a `UseTicketActionsOptions` config object and returns `UseTicketActionsReturn`.
 
-### `UseTicketActionsOptions`
-Configuration interface injected by the parent component:
-- `prependOptimistic` — adds an optimistic placeholder row to the QueryClient cache before the server roundtrip
-- `removeOptimistic` — removes the placeholder on mirror-sync failure or real ticket arrival
-- `removeTicketFromCache` — silent cache removal on `TICKET_NOT_FOUND`
-- `toast` — notification helper (injected for testability)
-- `onSupportSystemDown` — called on `412 HUBSPOT_DISCONNECTED`
-
-### `UseTicketActionsReturn`
-Returned handler surface:
-- `submitTicket(input)` — creates a new ticket with subject, content, and optional attachments
-- `sendMessage(ticket, text, attachments)` — sends a combined reply note
-- `closeTicket(ticket, resolution?)` — closes a ticket
-- `reopenTicket(ticket)` — reopens a closed ticket
-- `isSubmittingForm` — boolean loading state for form-level submission
-- `isRowBusy(localId)` — per-row busy predicate for UI disabling
-
-### `TicketRef`
-Decouples the local mirror UUID (`id`) from the HubSpot external id (`external_id`), both required for correct mutex and server routing.
+**Options:**
+- `prependOptimistic` — Mutates QueryClient cache to show a placeholder row before server roundtrip
+- `removeOptimistic` — Removes placeholder on failure or replacement
+- `removeTicketFromCache` — Silent cache removal on `TICKET_NOT_FOUND`
+- `toast` — Injected toast helper (test-friendly, no singleton import)
+- `onSupportSystemDown` — Called on 412 `HUBSPOT_DISCONNECTED`
 
 ### Internal Mechanisms
+
 | Mechanism | Purpose |
-|---|---|
-| `formInFlightRef` + `isSubmittingForm` | Prevents duplicate form submits across async ticks |
-| `busyRowsRef` + `busyRows` | Per-row mutex preventing fan-out on the same ticket row |
-| `queueRef` / `enqueue` | Depth-1 serial queue preventing server rate-limit stampedes |
-| `watchMirrorSync` | 3s/6s/12s backoff refetch loop when `mirror_synced === false`; drops placeholder after 30s cap |
-| `watcherControllersRef` | `AbortController` map; aborted on unmount and on duplicate-submit replacement |
+|-----------|---------|
+| `formInFlightRef` + `isSubmittingForm` | Prevents duplicate form submits (sync ref + state mirror) |
+| `busyRowsRef` + `busyRows` | Per-row `Set<ticket_id>` mutex for row-level disable |
+| `mutationQueue` (`queueRef`) | Depth-1 serial queue — prevents server rate-limit stampede |
+| `watcherControllersRef` | Tracks `AbortController` per placeholder for mirror-sync backoff |
+| `replyErrorByTicket` | Persisted inline reply-failure banner state, keyed by `external_id` |
+
+### `executeTicketAction(toolName, args)`
+Internal helper that POSTs to `/api/chat/agent/ticket-action`. Used by all 5 public actions — collapses the chat agent's `propose → confirm-tool` two-step into a single roundtrip.
+
+### Mirror-sync Retry
+On `result.mirror_synced === false`, schedules refetches at **3s / 6s / 12s** (≤30s wall-clock). Drops the optimistic placeholder and surfaces a "Couldn't confirm — Reload" affordance if sync never resolves.
 
 ## Usage Example
 
@@ -45,33 +39,36 @@ const {
   reopenTicket,
   isSubmittingForm,
   isRowBusy,
+  replyErrorFor,
+  clearReplyError,
 } = useTicketActions({
   prependOptimistic: (placeholder) => {
-    queryClient.setQueryData(['tickets'], (old: TicketData) => ({
+    queryClient.setQueryData(['tickets'], (old: TicketsCacheSlot) => ({
       ...old,
       tickets: [placeholder, ...(old?.tickets ?? [])],
     }))
   },
-  removeOptimistic: (id) => {
-    queryClient.setQueryData(['tickets'], (old: TicketData) => ({
-      ...old,
-      tickets: old?.tickets.filter((t) => t.id !== id) ?? [],
-    }))
-  },
-  removeTicketFromCache: (ticketId) => { /* cache mutation */ },
+  removeOptimistic: (id) => { /* remove by id from cache */ },
+  removeTicketFromCache: (id) => { /* silent remove */ },
   toast,
   onSupportSystemDown: () => setSupportSystemDown(true),
 })
 
-// Create a ticket
-const ok = await submitTicket({
-  subject: 'VPN not connecting',
-  content: 'Unable to connect since this morning.',
-})
+// Create
+await submitTicket({ subject: 'VPN down', content: 'Cannot connect' })
 
-// Close a ticket
+// Reply with attachment
+await sendMessage(
+  { id: 'uuid-local', external_id: '12345' },
+  'Here is the fix',
+  [attachment]
+)
+
+// Close with resolution note
 await closeTicket(
-  { id: ticket.id, external_id: ticket.external_id },
-  'Resolved by restarting the VPN client.'
+  { id: 'uuid-local', external_id: '12345' },
+  'Resolved by restarting the service'
 )
-```
\ No newline at end of file
+```
+
+> **Note:** `TicketRef` requires both `id` (local mirror UUID for React-side mutex) and `external_id` (HubSpot numeric ID for server calls). Passing the wrong ID to either side causes either a HubSpot 404 or a broken row-disable state.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-engagements.md b/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-engagements.md
index e3b9cce79..cf306a3d7 100644
--- a/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-engagements.md
+++ b/openframe-frontend-core/src/components/tickets/hooks/.use-ticket-engagements.md
@@ -1,42 +1,40 @@
-<!-- source-hash: 14e8fee946105e4d0d83a53313cfd255 -->
-Fetches the conversation timeline (notes, messages, and attachments) for a single HubSpot ticket, powering the ticket drawer's timeline view. Intentionally separate from the ticket list hook since engagements require expensive multi-stage API calls and are only loaded on demand.
+<!-- source-hash: a2e69d4cd554b8dc751e7fee0f547e6d -->
+Fetches and caches the conversation timeline (notes, messages, and attachments) for a single ticket, powering the drawer's engagement/timeline view with optional live polling.
 
 ## Key Components
 
-### Interfaces
+**Interfaces**
+- `TicketEngagementFile` — attachment metadata: `id`, `name`, `url`, `mime`, `size`
+- `TicketEngagement` — single timeline entry with `body`, `authorRole` (`'customer' | 'support'`), resolved author fields (`authorName`, `authorEmail`, `authorAvatarUrl`), `createdAt`, and nested `attachments[]`
+- `UseTicketEngagementsReturn` — hook return shape: `engagements[]`, `isLoading`, `isFetching`, `error`, `refetch`
 
-| Interface | Description |
-|---|---|
-| `TicketEngagementFile` | Attachment metadata: `id`, `name`, `url`, `mime`, `size` |
-| `TicketEngagement` | A single timeline entry with body, author info (`authorRole`, `authorName`, `authorEmail`, `authorAvatarUrl`), timestamp, and attachments |
-| `UseTicketEngagementsReturn` | Return shape: `engagements`, `isLoading`, `isFetching`, `error`, `refetch` |
-
-### Hook
-
-**`useTicketEngagements(externalTicketId, enabled?)`** — Queries `/api/chat/agent/list-engagements` via `embedAuthedFetch`. Skips execution for anonymous users, missing ticket IDs, and optimistic `temp-*` placeholders. Caching is intentionally disabled (`staleTime: 0`, `gcTime: 0`) so every drawer-open reflects live HubSpot state.
+**Hook**
+- `useTicketEngagements(externalTicketId, enabled?, refetchInterval?)` — primary export; wraps `@tanstack/react-query` with zero stale/gc time (always-fresh HubSpot data), guards against optimistic `temp-*` ticket IDs, and skips the fetch until `useChatIdentity` resolves a non-anon session
 
 ## Usage Example
 
 ```typescript
-const { engagements, isLoading, error, refetch } = useTicketEngagements(ticket.externalId)
-
-if (isLoading) return <Spinner />
-if (error) return <ErrorBanner message={error.message} />
-
-return (
-  <Timeline>
-    {engagements.map(e => (
-      <TimelineEntry
-        key={e.id}
-        body={e.body}
-        role={e.authorRole}   // 'customer' | 'support'
-        author={e.authorName}
-        avatarUrl={e.authorAvatarUrl}
-        attachments={e.attachments}
-      />
-    ))}
-  </Timeline>
+// Basic — fetch once when drawer opens
+const { engagements, isLoading, error } = useTicketEngagements(ticket.externalId)
+
+// With live polling (e.g. 10-second cadence while drawer is open)
+const TICKET_LIVE_POLL_MS = 10_000
+
+const { engagements, isFetching, refetch } = useTicketEngagements(
+  ticket.externalId,
+  true,
+  TICKET_LIVE_POLL_MS,
+)
+
+// Disabled for optimistic/unconfirmed tickets
+const { isLoading } = useTicketEngagements(
+  'temp-abc123', // detected via startsWith('temp-') — fetch is skipped
+  true,
 )
 ```
 
-> **Security note:** The server-side route enforces ticket ownership via `ticketBelongsToCustomer` before returning notes — customers cannot enumerate another customer's timeline by guessing ticket IDs.
\ No newline at end of file
+## Notes
+
+- **Auth:** uses `embedAuthedFetch` (proxy credentials); server enforces ticket ownership via `ticketBelongsToCustomer` — cross-customer enumeration is blocked server-side
+- **Loading state:** `isLoading` covers identity resolution lag to prevent skeleton flash on first render
+- **Polling:** `refetchIntervalInBackground` defaults to `false` — polling pauses on hidden tabs; unmounting the drawer stops polling automatically
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/tickets/hooks/.use-tickets-list.md b/openframe-frontend-core/src/components/tickets/hooks/.use-tickets-list.md
index 4a2549555..f42e23a15 100644
--- a/openframe-frontend-core/src/components/tickets/hooks/.use-tickets-list.md
+++ b/openframe-frontend-core/src/components/tickets/hooks/.use-tickets-list.md
@@ -1,36 +1,20 @@
-<!-- source-hash: 9effa67e5fd33a6782ade58cc9bf19ec -->
-Customer-scoped ticket list hook that wraps `POST /api/chat/agent/find-ticket`, supporting free-text search, status filtering, and server-side pagination with a single round-trip returning both rows and total count.
+<!-- source-hash: 16a7a8091a8762ea28446e7d35291a24 -->
+Fetches and paginates a customer's own ticket list by wrapping `POST /api/chat/agent/find-ticket`, returning tickets, pagination metadata, and loading state via TanStack Query.
 
 ## Key Components
 
-### `useTicketsList(filters)`
-Main exported hook. Accepts a `UseTicketsListFilters` object and returns `UseTicketsListReturn`.
-
-### `UseTicketsListFilters`
-| Field | Type | Description |
-|-------|------|-------------|
-| `customerEmail` | `string` | Resolved identity from parent — **must** be drilled in, not re-fetched |
-| `search` | `string?` | Free-text FTS query; empty = list all tickets |
-| `status` | `string?` | `'open'` \| `'closed'` \| `'all'` — empty/`'all'` skips filter |
-| `page` | `number?` | 1-based page number, defaults to `1` |
-| `pageSize` | `number?` | Items per page, server-capped at `100`, defaults to `20` |
-
-### `UseTicketsListReturn`
-| Field | Type | Description |
-|-------|------|-------------|
-| `tickets` | `TicketData[]` | Current page of tickets |
-| `totalCount` | `number` | Total across all pages (drives pagination) |
-| `totalPages` | `number` | Pre-computed, clamped to ≥1 |
-| `page` / `pageSize` | `number` | Server-echoed values |
-| `isLoading` | `boolean` | `true` when no data exists for the current query slot |
-| `isFetching` | `boolean` | `true` during any background refetch |
-| `lastUpdatedAt` | `number \| null` | Wall-clock timestamp of last successful fetch |
-
-## Cache Behavior
-
-- **Key:** `['tickets', 'self', identity, search, status, page, pageSize]` — each filter+page combo occupies its own slot
-- **Caching disabled** (`staleTime: 0`, `gcTime: 0`) — always fetches fresh data on mount, focus, and navigation
-- **Invalidation:** `useTicketActions` calls `queryClient.invalidateQueries({ queryKey: ['tickets'] })` after mutations, refreshing all slots
+**`useTicketsList(filters)`** — Primary export. Builds a cache-keyed TanStack Query that posts to the find-ticket endpoint with search, status, and pagination params. Intentionally sets `staleTime: 0` / `gcTime: 0` / `refetchOnMount: 'always'` to ensure the customer always sees live ticket data.
+
+**`UseTicketsListFilters`** — Input interface:
+- `customerEmail` — required; disables the query if empty (prevents anon 401 round-trips)
+- `search` — free-text FTS query; empty string means "list all my tickets"
+- `status` — `'open'` | `'closed'` | `'all'` / empty (no filter)
+- `page` / `pageSize` — 1-based pagination; server caps `pageSize` at 100
+- `refetchInterval` — optional polling interval (ms) for live status updates; pauses on hidden tabs
+
+**`UseTicketsListReturn`** — Output interface including `tickets`, `isLoading`, `isFetching`, `error`, `refetch`, `lastUpdatedAt`, `totalCount`, `page`, `pageSize`, and pre-computed `totalPages`.
+
+**Cache key** — `['tickets', 'self', identityKey, search, statusFilter, page, pageSize]`. Each filter+page combo occupies its own slot; mutations via `useTicketActions` invalidate all `['tickets']` slots together.
 
 ## Usage Example
 
@@ -41,14 +25,15 @@ const {
   totalCount,
   totalPages,
   page,
-  pageSize,
+  refetch,
 } = useTicketsList({
   customerEmail: identity.user.email,
-  search: 'printer not working',
+  search: searchQuery,
   status: 'open',
-  page: 1,
+  page: currentPage,
   pageSize: 20,
+  refetchInterval: isDrawerOpen ? 5000 : false,
 })
 ```
 
-> **Note:** Never call `useChatIdentity` inside this hook. Always drill `customerEmail` from the parent to avoid a null-identity race that causes an `EmptyState` flash before the first fetch fires.
\ No newline at end of file
+> **Note:** `customerEmail` must be resolved by the parent (e.g. via `useChatIdentity`) before mounting — drilling it in prevents a race condition where calling `useChatIdentity` inside this hook would produce a `null` identity on the first render, causing an empty-state flash.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.actions-menu.md b/openframe-frontend-core/src/components/ui/.actions-menu.md
index 5217c80cf..f94072313 100644
--- a/openframe-frontend-core/src/components/ui/.actions-menu.md
+++ b/openframe-frontend-core/src/components/ui/.actions-menu.md
@@ -1,31 +1,21 @@
-<!-- source-hash: 342a87b9f572574fd4c65a58c52361ef -->
-A flexible, accessible dropdown actions menu component built on Radix UI primitives, supporting grouped items, checkboxes, submenus, navigation links, and secondary icon actions.
+<!-- source-hash: ac76113bf35175b4311056d7bbaaa902 -->
+A flexible, accessible actions/context menu component built on Radix UI's DropdownMenu primitive, supporting items, checkboxes, submenus, separators, navigation links, and optional secondary icon actions per row.
 
 ## Key Components
 
-### Exported Components
-
-| Component | Description |
-|-----------|-------------|
-| `ActionsMenu` | Standalone menu panel (no trigger) — renders grouped items directly |
-| `ActionsMenuDropdown` | Full dropdown with a configurable trigger button and Radix-powered popover |
-
-### Internal Components
-
-| Component | Description |
-|-----------|-------------|
-| `MenuItem` | Renders a single item — handles `item`, `checkbox`, `submenu`, `separator`, and link variants |
-| `SecondaryAction` | 40px secondary icon button/link on the right side of a row, independently clickable |
-| `GroupSeparator` | Visual divider rendered between groups when `separator: true` |
+- **`ActionsMenu`** — Standalone menu panel (no trigger) that renders grouped items directly into the DOM
+- **`ActionsMenuDropdown`** — Full dropdown with a configurable trigger button (ellipsis by default), wrapping `ActionsMenu` with controlled/uncontrolled open state
+- **`MenuItem`** — Internal component handling all item variants: standard, checkbox, submenu, separator, and link
+- **`SecondaryAction`** — Internal 40px-wide icon button/link rendered on the right side of a row, independently clickable from the primary action
 
 ### Key Interfaces
 
 | Interface | Purpose |
-|-----------|---------|
-| `ActionsMenuItem` | Single menu item with optional `href`, `submenu`, `iconAction`, `checked` |
-| `ActionsMenuGroup` | Collection of items with optional separator |
-| `ActionsMenuProps` | Props for `ActionsMenu` — `groups`, `className`, `onItemClick` |
-| `ActionsMenuDropdownProps` | Extends `ActionsMenuProps` with trigger, alignment, and popover controls |
+|---|---|
+| `ActionsMenuItem` | Defines a single menu row (label, icon, type, href, danger, iconAction, etc.) |
+| `ActionsMenuGroup` | Groups items together with optional separators between groups |
+| `ActionsMenuProps` | Props for the standalone `ActionsMenu` panel |
+| `ActionsMenuDropdownProps` | Extends `ActionsMenuProps` with trigger, alignment, open state, and focus controls |
 
 ## Usage Example
 
@@ -39,36 +29,26 @@ const groups = [
         id: "edit",
         label: "Edit",
         icon: <EditIcon />,
-        onClick: () => console.log("Edit clicked"),
+        onClick: () => handleEdit(),
       },
       {
-        id: "open",
-        label: "Open in new tab",
-        href: "/resource/123",
+        id: "open-link",
+        label: "Open in Browser",
+        href: "https://example.com",
+        openInNewTab: true,
         iconAction: {
           icon: <ExternalLinkIcon />,
           "aria-label": "Open in new tab",
-          href: "/resource/123",
+          href: "https://example.com",
           openInNewTab: true,
         },
       },
-    ],
-    separator: true,
-  },
-  {
-    items: [
-      {
-        id: "notify",
-        label: "Notifications",
-        type: "checkbox",
-        checked: true,
-        onClick: () => toggleNotifications(),
-      },
-      { id: "sep", label: "", type: "separator" },
+      { id: "sep", type: "separator" },
       {
         id: "delete",
         label: "Delete",
-        disabled: true,
+        danger: true,
+        icon: <TrashIcon />,
         onClick: () => handleDelete(),
       },
     ],
@@ -78,10 +58,6 @@ const groups = [
 <ActionsMenuDropdown
   groups={groups}
   align="end"
-  side="bottom"
-  triggerAriaLabel="More actions"
   onItemClick={(item) => console.log("Clicked:", item.id)}
 />
-```
-
-> **Note:** The dropdown auto-closes after selecting a regular item but stays open for `checkbox` and `submenu` types, allowing toggling and nested navigation.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.allowed-domains-input.md b/openframe-frontend-core/src/components/ui/.allowed-domains-input.md
index 71c0d249c..326115bf3 100644
--- a/openframe-frontend-core/src/components/ui/.allowed-domains-input.md
+++ b/openframe-frontend-core/src/components/ui/.allowed-domains-input.md
@@ -1,40 +1,41 @@
-<!-- source-hash: 4488babe1708a2df7fd49ce4d01e1ce8 -->
-A client-side React component for managing a list of allowed domains, supporting add/remove operations with optional validation, duplicate prevention, and error display.
+<!-- source-hash: 7895db249cc73e08a0b3a0db60a89e57 -->
+A controlled React component for managing a list of allowed domains, supporting add/remove operations with optional validation, error display, and keyboard interaction.
 
 ## Key Components
 
-### `AllowedDomainsInputProps`
+**`AllowedDomainsInput`** — A `forwardRef` component that renders a domain list manager with:
+- Existing domain entries displayed as disabled inputs with remove (`X`) buttons
+- A text input for entering new domains (supports `Enter` key to add)
+- An "Add Domain" button with a `PlusCircle` icon
+- Inline error and helper text display
+
+**`AllowedDomainsInputProps`** — Interface defining the component's API:
 
 | Prop | Type | Description |
 |------|------|-------------|
 | `value` | `string[]` | Controlled list of current domains |
-| `onChange` | `(domains: string[]) => void` | Callback when domain list changes |
-| `onValidate` | `(domain: string) => { valid, error?, cleanedDomain? }` | Optional custom domain validator |
-| `label` | `string` | Field label (default: `"Allowed Domains"`) |
-| `placeholder` | `string` | Input placeholder (default: `"example.com"`) |
+| `onChange` | `(domains: string[]) => void` | Called when the domain list changes |
+| `onValidate` | `(domain: string) => { valid, error?, cleanedDomain? }` | Optional custom validator; supports domain normalization via `cleanedDomain` |
 | `disabled` | `boolean` | Disables all interactions |
-| `error` | `string \| null` | External error message |
-| `helperText` | `string` | Helper text shown when no error is present |
-
-### `AllowedDomainsInput`
-
-A `forwardRef` component that renders:
-- **Existing domain rows** — each as a disabled `Input` with an `X` remove button
-- **New domain input** — accepts `Enter` key or "Add Domain" button to submit
-- **Validation feedback** — displays external `error` or internal `localError`
+| `error` | `string \| null` | External error message (takes priority over local errors) |
+| `helperText` | `string` | Descriptive text shown when no error is present |
 
 ## Usage Example
 
 ```typescript
 import { AllowedDomainsInput } from "@/components/ui/allowed-domains-input"
 
-function SettingsForm() {
+function SecuritySettings() {
   const [domains, setDomains] = React.useState<string[]>(["flamingo.run"])
 
   const validateDomain = (domain: string) => {
     const cleaned = domain.toLowerCase().replace(/^https?:\/\//, "")
-    const valid = /^[a-z0-9.-]+\.[a-z]{2,}$/.test(cleaned)
-    return { valid, error: valid ? undefined : "Enter a valid domain", cleanedDomain: cleaned }
+    const isValid = /^[a-z0-9.-]+\.[a-z]{2,}$/.test(cleaned)
+    return {
+      valid: isValid,
+      error: isValid ? undefined : "Enter a valid domain (e.g. example.com)",
+      cleanedDomain: cleaned,
+    }
   }
 
   return (
@@ -42,10 +43,11 @@ function SettingsForm() {
       value={domains}
       onChange={setDomains}
       onValidate={validateDomain}
-      helperText="Only users from these domains can sign in."
+      label="Allowed Email Domains"
+      helperText="Only users from these domains can sign up."
     />
   )
 }
 ```
 
-> **Note:** Duplicate domains are silently ignored. If `onValidate` returns a `cleanedDomain`, that normalized value is stored instead of the raw input.
\ No newline at end of file
+> **Note:** Duplicate domains are silently ignored. The external `error` prop overrides any locally generated validation error.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.color-preset-select.md b/openframe-frontend-core/src/components/ui/.color-preset-select.md
new file mode 100644
index 000000000..1ace5577c
--- /dev/null
+++ b/openframe-frontend-core/src/components/ui/.color-preset-select.md
@@ -0,0 +1,39 @@
+<!-- source-hash: cb751e114f40b091ea638a08012c39d4 -->
+Provides two color selection components: a preset-based color selector (`ColorPresetSelect`) and a full custom color picker (`ColorPickerInput`) with HEX/RGB/HSL input support.
+
+## Key Components
+
+### Exports
+
+- **`ColorPresetSelect`** — Dropdown that lets users choose from a predefined palette or switch to "Custom" mode. Renders a color swatch + label trigger backed by `ActionsMenuDropdown`.
+- **`ColorPickerInput`** — Full color picker using `react-colorful`'s `HexColorPicker`, with a format switcher (HEX / RGB / HSL) and channel inputs for precise values.
+- **`TICKET_STATUS_COLOR_PRESETS`** — Default 12-color palette (green, teal, sky, red, pink, etc.) for ticket status use cases.
+- **`ColorPreset`** — Interface `{ key, label, color }` describing a named preset entry.
+
+### Internal Helpers
+
+- **`HexInputs`** — Controlled text input with draft state; commits on blur or Enter, validates against `HEX_PATTERN`.
+- **`ChannelInput`** — Numeric input (strips non-digits) clamped to `[min, max]`; used by RGB and HSL rows.
+- **`RgbInputs`** / **`HslInputs`** — Three-channel input rows that convert to/from hex via `ods-color-utils`.
+
+## Usage Example
+
+```typescript
+// Preset selector (e.g., ticket status color)
+<ColorPresetSelect
+  value={color}
+  presetKey={presetKey}
+  onChange={({ color, preset }) => {
+    setColor(color)
+    setPresetKey(preset)
+  }}
+/>
+
+// Full custom picker (always hex in/out)
+<ColorPickerInput
+  value={hexColor}
+  onChange={(hex) => setHexColor(hex)}
+/>
+```
+
+> **Note:** Both components accept `disabled` and `className` props. `ColorPresetSelect` accepts a custom `presets` array; it defaults to `TICKET_STATUS_COLOR_PRESETS`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.cursor-pagination.md b/openframe-frontend-core/src/components/ui/.cursor-pagination.md
index aae81c832..aafdf4460 100644
--- a/openframe-frontend-core/src/components/ui/.cursor-pagination.md
+++ b/openframe-frontend-core/src/components/ui/.cursor-pagination.md
@@ -1,52 +1,58 @@
-<!-- source-hash: 0e65f8e03b416890c9d63ba33ba86a8e -->
-Cursor-based pagination UI components for navigating relay-style paginated data using start/end cursors instead of page numbers.
+<!-- source-hash: cea59b81a5afc9f7041ca6ecd320a1a1 -->
+React components for cursor-based pagination navigation, supporting both full-featured and minimal icon-only variants.
 
 ## Key Components
 
 ### `CursorPagination`
-Full-featured pagination bar with optional info text, Previous/Next navigation, and a reset-to-first-page button. Supports both compact and standard layouts.
+Full-featured pagination bar with optional info text, reset/previous/next navigation, and compact mode support.
 
 ### `CursorPaginationSimple`
-Minimal icon-only variant using transparent buttons — ideal for inline or space-constrained contexts like table toolbars.
+Minimal icon-only pagination using transparent icon buttons — ideal for tight layouts like table toolbars.
 
 ### `CursorPaginationProps`
-Full interface supporting:
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `hasNextPage` | `boolean` | Required. Enables/disables Next button |
-| `hasPreviousPage` | `boolean` | Enables/disables Previous button |
-| `isFirstPage` | `boolean` | Disables reset button when already on page 1 |
-| `startCursor` / `endCursor` | `string \| null` | Relay-style cursors passed back on navigation |
-| `totalCount` / `currentCount` | `number` | Drives the info display text |
-| `onNext` / `onPrevious` / `onReset` | `(cursor) => void` | Navigation callbacks |
-| `compact` | `boolean` | Reduces padding; hides button labels on mobile |
-| `resetButtonIcon` | `'home' \| 'rotate'` | Icon shown on the first-page reset button |
+Full interface controlling cursor values, page state, counts, labels, and callbacks.
 
 ## Usage Example
 
 ```typescript
-import { CursorPagination, CursorPaginationSimple } from './cursor-pagination'
-
-// Full pagination bar
+// Full pagination bar with count info and reset
 <CursorPagination
-  hasNextPage={pageInfo.hasNextPage}
-  hasPreviousPage={pageInfo.hasPreviousPage}
-  startCursor={pageInfo.startCursor}
-  endCursor={pageInfo.endCursor}
-  currentCount={items.length}
-  totalCount={totalCount}
+  hasNextPage={true}
+  hasPreviousPage={false}
+  isFirstPage={true}
+  endCursor="cursor_abc123"
+  currentCount={25}
+  totalCount={200}
   itemName="tickets"
   onNext={(cursor) => fetchPage({ after: cursor })}
   onReset={() => fetchPage({})}
-  compact
+  resetButtonIcon="home"
+  showInfo={true}
+  compact={false}
+/>
+
+// Compact mode — labels hidden on mobile, visible md+
+<CursorPagination
+  hasNextPage={true}
+  endCursor="cursor_xyz"
+  onNext={(cursor) => loadNext(cursor)}
+  compact={true}
 />
 
-// Icon-only minimal variant
+// Minimal icon-only variant for table headers
 <CursorPaginationSimple
-  hasNextPage={pageInfo.hasNextPage}
-  onNext={() => fetchPage({ after: pageInfo.endCursor })}
-  onReset={() => fetchPage({})}
-  isFirstPage={isFirstPage}
+  hasNextPage={true}
+  hasPreviousPage={false}
+  isFirstPage={true}
+  onNext={() => fetchNext()}
+  onReset={() => resetPagination()}
+  loading={isFetching}
 />
-```
\ No newline at end of file
+```
+
+## Notes
+
+- When `onReset` is provided, it replaces the **Previous** button with a **First**/**Home** button, disabled when already on the first page.
+- `getDisplayText()` renders three display modes: exact count (`25 of 200`), unbounded (`25+`), or final page count (`25 items`).
+- `CursorPaginationSimple` passes an empty string to `onNext`/`onPrevious` — callers must manage cursor state externally.
+- Both components accept a `loading` prop that disables all buttons during data fetching.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.dropdown-button.md b/openframe-frontend-core/src/components/ui/.dropdown-button.md
index 9c95e5723..4ee235657 100644
--- a/openframe-frontend-core/src/components/ui/.dropdown-button.md
+++ b/openframe-frontend-core/src/components/ui/.dropdown-button.md
@@ -1,30 +1,18 @@
-<!-- source-hash: 755936e5a23162889a0f4b377887a066 -->
-A styled dropdown trigger button that combines a labeled action area with a rotating chevron indicator, opening a `MoreActionsMenu` on click.
+<!-- source-hash: f200d2146a81060f8cc6dc2a88c6bc69 -->
+A compound trigger component that combines a labeled button with a trailing chevron to open an `ActionsMenuDropdown`. The button visually separates the label area from the chevron via a border seam, while acting as a single unified click target.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `DropdownButton` | Component | Main trigger button that wraps `MoreActionsMenu` |
-| `DropdownButtonProps` | Interface | Props definition for the component |
+- **`DropdownButton`** — Primary export; a stateful button that manages dropdown open/close state and delegates rendering to `ActionsMenuDropdown`
+- **`DropdownButtonProps`** — Interface defining label, optional icon, menu items, positioning (`align`/`side`), and accessibility props
+- **`ActionsMenuDropdown`** — Underlying dropdown primitive consumed internally
 
-### Props
+## Behavior Notes
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | — | Button label text |
-| `icon` | `ReactNode` | — | Optional leading icon |
-| `items` | `MoreActionsItem[]` | — | Dropdown menu items |
-| `align` | `'start' \| 'center' \| 'end'` | `'end'` | Menu alignment |
-| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Menu opening side |
-| `disabled` | `boolean` | — | Disables interaction |
-
-## Key Behaviors
-
-- **Single click target** — label and chevron areas are visually separated by a border seam but share one `<button>` element
-- **Open state styles** — background lightens (`ods-bg-hover`) when the menu is open or hovered
-- **Chevron rotation** — animates 180° when the dropdown is open
-- **Disabled guard** — blocks `onOpenChange` and prevents pointer events when `disabled` is set
+- Chevron rotates 180° when the menu is open
+- Background lightens (`ods-bg-hover`) both on hover and while open
+- `disabled` prop blocks pointer events and applies 50% opacity
+- Defaults: `align="end"`, `side="bottom"`
 
 ## Usage Example
 
@@ -38,8 +26,8 @@ import { SettingsIcon } from '../icons-v2-generated'
   align="end"
   side="bottom"
   items={[
-    { label: 'Edit', onClick: () => console.log('edit') },
-    { label: 'Delete', onClick: () => console.log('delete'), destructive: true },
+    { label: 'Edit', onClick: () => handleEdit() },
+    { label: 'Delete', onClick: () => handleDelete(), variant: 'danger' },
   ]}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.dropdown-menu.md b/openframe-frontend-core/src/components/ui/.dropdown-menu.md
index 2ac1bd396..620c37786 100644
--- a/openframe-frontend-core/src/components/ui/.dropdown-menu.md
+++ b/openframe-frontend-core/src/components/ui/.dropdown-menu.md
@@ -1,47 +1,67 @@
-<!-- source-hash: 34ce5c6ddfeca8bdfa20a5f6665b19da -->
-A comprehensive dropdown menu component built on top of Radix UI's dropdown menu primitives, providing a full suite of styled menu components with consistent theming using the OpenFrame Design System (ODS).
+<!-- source-hash: 0d6d36550b00f03453ca6b2d7b4b6cdf -->
+A themed dropdown menu component built on Radix UI primitives, providing accessible, animated dropdown menus with support for nested submenus, checkboxes, radio groups, and keyboard shortcuts. Integrates with `usePortalContainer` to correctly render within stacked contexts like drawers.
 
 ## Key Components
 
-- **DropdownMenu** - Root container component
-- **DropdownMenuTrigger** - Button that opens the dropdown
-- **DropdownMenuContent** - Main content container with portal rendering
-- **DropdownMenuItem** - Interactive menu items with hover states
-- **DropdownMenuCheckboxItem** - Checkable menu items with check indicators
-- **DropdownMenuRadioItem** - Radio button menu items for single selection
-- **DropdownMenuLabel** - Non-interactive section labels
-- **DropdownMenuSeparator** - Visual dividers between menu sections
-- **DropdownMenuShortcut** - Keyboard shortcut display component
-- **DropdownMenuSub/SubTrigger/SubContent** - Nested submenu components
-- **DropdownMenuGroup/RadioGroup** - Grouping containers
+| Export | Description |
+|--------|-------------|
+| `DropdownMenu` | Root component (Radix `Root`) |
+| `DropdownMenuTrigger` | Element that opens the menu |
+| `DropdownMenuContent` | Animated panel; portals into the active container via `usePortalContainer` |
+| `DropdownMenuItem` | Standard clickable menu entry |
+| `DropdownMenuCheckboxItem` | Item with a checkmark indicator |
+| `DropdownMenuRadioItem` | Item for single-select radio groups |
+| `DropdownMenuRadioGroup` | Wrapper for radio items |
+| `DropdownMenuSub` | Root for a nested submenu |
+| `DropdownMenuSubTrigger` | Trigger for a nested submenu (renders `ChevronRight`) |
+| `DropdownMenuSubContent` | Panel for the nested submenu |
+| `DropdownMenuLabel` | Non-interactive section heading |
+| `DropdownMenuSeparator` | Horizontal divider |
+| `DropdownMenuShortcut` | Right-aligned keyboard shortcut hint |
+| `DropdownMenuGroup` | Logical grouping of items |
+| `DropdownMenuPortal` | Raw Radix portal passthrough |
 
 ## Usage Example
 
 ```typescript
 import {
   DropdownMenu,
+  DropdownMenuTrigger,
   DropdownMenuContent,
   DropdownMenuItem,
-  DropdownMenuLabel,
+  DropdownMenuCheckboxItem,
   DropdownMenuSeparator,
-  DropdownMenuTrigger,
-} from "./dropdown-menu"
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+} from "@/components/ui/dropdown-menu"
 
-function UserMenu() {
+export function ActionsMenu() {
   return (
     <DropdownMenu>
-      <DropdownMenuTrigger>Open Menu</DropdownMenuTrigger>
+      <DropdownMenuTrigger asChild>
+        <button>Open Menu</button>
+      </DropdownMenuTrigger>
       <DropdownMenuContent>
-        <DropdownMenuLabel>My Account</DropdownMenuLabel>
-        <DropdownMenuSeparator />
-        <DropdownMenuItem>Profile</DropdownMenuItem>
-        <DropdownMenuItem>Settings</DropdownMenuItem>
+        <DropdownMenuItem>
+          New Ticket <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
+        </DropdownMenuItem>
+        <DropdownMenuCheckboxItem checked={true}>
+          Show Resolved
+        </DropdownMenuCheckboxItem>
         <DropdownMenuSeparator />
-        <DropdownMenuItem>Logout</DropdownMenuItem>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>Assign To</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>Alice</DropdownMenuItem>
+            <DropdownMenuItem>Bob</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
       </DropdownMenuContent>
     </DropdownMenu>
   )
 }
 ```
 
-All components use ODS tokens for consistent theming and include smooth animations, focus management, and accessibility features from Radix UI.
\ No newline at end of file
+> **Portal behavior:** `DropdownMenuContent` automatically portals into the nearest ancestor registered via `usePortalContainer` (e.g. a drawer), falling back to `document.body` — preventing z-index and clipping issues in nested layouts.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.filter-pill-row.md b/openframe-frontend-core/src/components/ui/.filter-pill-row.md
new file mode 100644
index 000000000..310592b67
--- /dev/null
+++ b/openframe-frontend-core/src/components/ui/.filter-pill-row.md
@@ -0,0 +1,48 @@
+<!-- source-hash: 02e1280b22ab592ae8fa2fa7ac91549e -->
+Responsive filter pill row component that renders a labeled set of toggle buttons inside a styled card container, used across catalog and admin views to filter lists by a single selected value.
+
+## Key Components
+
+**`FilterPillRow`** — Main export. Renders a horizontal (flex-wrap) row with a `Filter` icon, a label, pill-style toggle buttons, and an optional count label.
+
+**`FilterPillRowOption`** — Shape of each filter option: `{ value: string, label: string }`.
+
+**`FilterPillRowProps`** — Full prop interface:
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | ✅ | Text next to the filter icon (e.g. `"Section"`) |
+| `selectedValue` | `string` | ✅ | Currently active filter value |
+| `onValueChange` | `(value: string) => void` | ✅ | Selection change callback |
+| `options` | `FilterPillRowOption[]` | ✅ | Available filter pills |
+| `countLabel` | `string` | ❌ | Right-aligned summary (e.g. `"Showing 1–10 of 42"`) |
+| `children` | `ReactNode` | ❌ | Replaces `options` rendering for custom content |
+
+## Usage Example
+
+```typescript
+import { FilterPillRow } from '@/components/ui/filter-pill-row'
+
+const PLATFORM_OPTIONS = [
+  { value: 'all', label: 'All' },
+  { value: 'windows', label: 'Windows' },
+  { value: 'linux', label: 'Linux' },
+  { value: 'macos', label: 'macOS' },
+]
+
+export function PlatformFilter() {
+  const [platform, setPlatform] = useState('all')
+
+  return (
+    <FilterPillRow
+      label="Platform"
+      selectedValue={platform}
+      onValueChange={setPlatform}
+      options={PLATFORM_OPTIONS}
+      countLabel="Showing 12 of 48 scripts"
+    />
+  )
+}
+```
+
+> **Note:** Pass `children` instead of `options` when you need custom filter controls (e.g. a date range picker or search input) while keeping the shared card layout.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.index.md b/openframe-frontend-core/src/components/ui/.index.md
index 49858b3fc..d6586a87b 100644
--- a/openframe-frontend-core/src/components/ui/.index.md
+++ b/openframe-frontend-core/src/components/ui/.index.md
@@ -1,52 +1,46 @@
-<!-- source-hash: 69fabf50cc24470b1828f706f8765a69 -->
-Central barrel export file for the UI kit library, re-exporting all client-side UI components organized by category (form inputs, layout, navigation, feedback, tables, chat, and more).
+<!-- source-hash: 24e1d986595234f2c5091c2e570974f6 -->
+Central barrel export file for the `ui-kit` component library, re-exporting all UI components, layouts, and utilities as a single public API for client-side consumption.
 
 ## Key Components
 
-Organized into the following categories:
+Organized into logical categories:
 
-| Category | Notable Exports |
-|---|---|
-| **Form / Input** | `Button`, `Input`, `Select`, `Checkbox`, `DatePicker`, `TagsInput`, `RadioGroup`, `Switch` |
-| **Layout** | `Dialog`, `Modal`, `ModalV2`, `Sheet`, `Drawer`, `Tabs`, `Separator` |
-| **Navigation** | `Accordion`, `Breadcrumb`, `DropdownMenu`, `NavigationMenu`, `TabNavigation` |
-| **Feedback** | `Alert`, `Badge`, `Progress`, `StatusBadge`, `Toaster`, `StatusIndicator` |
-| **Table** | `Table`, `TableRow`, `TableCell`, `TableHeader`, `TableEmptyState`, `TableTimestampCell` |
-| **Query Report** | `QueryReportTable`, `deriveColumns`, `exportToCSV` |
-| **DataTable** | Headless TanStack Table-based replacement for legacy `Table` |
-| **Pagination** | `CursorPagination`, `CursorPaginationSimple` |
-| **Search / Filter** | `SearchInput`, `FilterList`, `TagSearchInput`, `TagKeyValueFilter` |
-| **Chat / Layout** | `chat`, `ListPageLayout`, `PageContainer`, `PageLayout` |
-| **Ticket** | `TicketStatusTag`, `AssigneeDropdown`, `TicketNoteCard`, `SimpleMarkdownRenderer` |
-| **Media / Upload** | `FileUpload`, `ImageUploader`, `MediaTypeSelector` |
-| **Misc** | `FloatingTooltip`, `TruncateText`, `CircularProgress`, `Skeleton`, `Slider` |
+- **Form inputs** — `Input`, `Select`, `Checkbox`, `DatePicker`, `TagsInput`, `PhoneInput`, `MarkdownEditor`, `FileUpload`
+- **Layout/Overlay** — `Dialog`, `Modal`, `ModalV2`, `Sheet`, `Drawer`, `AlertDialog`, `ImageGalleryModal`
+- **Navigation** — `Accordion`, `Breadcrumb`, `DropdownMenu`, `NavigationMenu`, `TabNavigation`
+- **Feedback** — `Alert`, `Badge`, `Toaster`, `StatusBadge`, `StatusIndicator`, `ProgressBar`
+- **Table** — `Table`, `DataTable` (TanStack-based), `QueryReportTable` (dynamic osquery columns), `CursorPagination`
+- **Ticket** — `TicketStatusTag`, `AssigneeDropdown`, `TicketNotesSection`, `TicketAttachmentsList`
+- **Search/Filter** — `SearchInput`, `FilterList`, `TagKeyValueFilter`, `HiddenTagsPopup`
+- **Layout pages** — `ListPageLayout`, `PageContainer`, `PageHeading`, `ArticleDetailLayout`
+- **Utilities** — `TruncateText`, `FloatingTooltip`, `exportToCSV`, `deriveColumns`
 
 ## Usage Example
 
 ```typescript
+// Import any component directly from the ui-kit barrel
 import {
   Button,
   Input,
-  Select,
   Table,
-  TableRow,
-  TableCell,
+  TableColumn,
   CursorPagination,
   StatusBadge,
   QueryReportTable,
   deriveColumns,
-} from '@your-org/ui-kit'
-
-function DeviceTable({ data, pagination }) {
-  const columns = deriveColumns(data)
-
-  return (
-    <>
-      <QueryReportTable columns={columns} rows={data} />
-      <CursorPagination {...pagination} />
-    </>
-  )
-}
+  exportToCSV,
+  TruncateText,
+  FloatingTooltip,
+  CheckIcon,
+} from '@flamingo/ui-kit'
+
+// Named type imports are also available
+import type {
+  TableProps,
+  RowAction,
+  QueryReportTableProps,
+  CursorPaginationProps,
+} from '@flamingo/ui-kit'
 ```
 
-> **Note:** This file is marked `"use client"` — all exported components are client-side only and require a React environment with client rendering support (e.g. Next.js App Router).
\ No newline at end of file
+> **Note:** This file is marked `"use client"` — all exported components are React client components and must be used within a Next.js Client Component boundary.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.info-row.md b/openframe-frontend-core/src/components/ui/.info-row.md
index 5f3107332..0c7504377 100644
--- a/openframe-frontend-core/src/components/ui/.info-row.md
+++ b/openframe-frontend-core/src/components/ui/.info-row.md
@@ -1,40 +1,41 @@
-<!-- source-hash: 841435ad2eb230c8516130a8d58de981 -->
-A reusable UI component that renders a single labeled row with a value, connected by a horizontal dotted separator line — commonly used for displaying key-value metadata in detail panels or cards.
+<!-- source-hash: 92cd16db89c0f4bff18d0727bf72d793 -->
+A reusable UI component that renders a labeled key-value row with a dotted/line separator, commonly used in detail panels and info cards.
 
 ## Key Components
 
 ### `InfoRow`
-A client-side React component that accepts the following props:
+A client-side React component that displays a label and value pair separated by a horizontal line, with an optional icon rendered beside the value.
+
+**Props (`InfoRowProps`):**
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `label` | `string` | ✅ | Left-aligned label text |
-| `value` | `string` | ✅ | Right-aligned value text |
-| `icon` | `React.ReactNode` | ❌ | Optional icon rendered inline after the value |
+| `label` | `string` | ✅ | Left-side descriptor text |
+| `value` | `string` | ✅ | Right-side display value |
+| `icon` | `React.ReactNode` | ❌ | Optional icon rendered next to the value |
 
 ## Usage Example
 
 ```typescript
 import { InfoRow } from "@/components/info-row"
-import { Globe } from "lucide-react"
-
-export function DeviceDetails() {
-  return (
-    <div className="flex flex-col gap-2">
-      <InfoRow label="Hostname" value="workstation-01" />
-      <InfoRow label="IP Address" value="192.168.1.100" />
-      <InfoRow
-        label="Status"
-        value="Online"
-        icon={<Globe className="w-4 h-4 text-green-400" />}
-      />
-    </div>
-  )
-}
+import { CheckCircle } from "lucide-react"
+
+// Basic usage
+<InfoRow label="Status" value="Active" />
+
+// With an icon
+<InfoRow
+  label="Uptime"
+  value="99.9%"
+  icon={<CheckCircle className="w-4 h-4 text-green-500" />}
+/>
+
+// In a detail card
+<div className="flex flex-col gap-2">
+  <InfoRow label="Hostname" value="server-01.local" />
+  <InfoRow label="IP Address" value="192.168.1.10" />
+  <InfoRow label="OS" value="Ubuntu 22.04" />
+</div>
 ```
 
-## Layout Behavior
-
-- **Label** — left side, truncates with ellipsis on overflow
-- **Separator** — flexible `1px` horizontal line that fills available space between label and value
-- **Value + Icon** — right side, truncates with ellipsis, icon rendered inline after text
\ No newline at end of file
+> The separator line (`flex-1 h-px`) stretches to fill available space between the label and value, ensuring consistent alignment regardless of text length. Both label and value use `text-ellipsis` to gracefully handle overflow.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.input.md b/openframe-frontend-core/src/components/ui/.input.md
index 4bdebe8db..cb188efb2 100644
--- a/openframe-frontend-core/src/components/ui/.input.md
+++ b/openframe-frontend-core/src/components/ui/.input.md
@@ -1,40 +1,35 @@
-<!-- source-hash: deeae07a7913733b844e875487c55c37 -->
-A client-side input component built with `React.forwardRef`, supporting labels, validation states, adornments, loading indicators, and a special range slider variant.
+<!-- source-hash: 17e7d505cff88b469b48662544ca7851 -->
+A styled, accessible input component that extends the native HTML `<input>` with support for labels, validation states, adornments, and a loading spinner. Handles both standard text inputs and range sliders with distinct rendering logic.
 
 ## Key Components
 
-- **`Input`** — Main exported component extending native `HTMLInputElement` attributes
-- **`InputProps`** — Interface adding `invalid`, `startAdornment`, `endAdornment`, `label`, `error`, `errorVariant`, and `loading` props
-- **`invalidBorderClasses`** — Tailwind class map for `"error"` (red) and `"warning"` (yellow) border states
-- **`FieldWrapper`** — Wraps the input with optional label and error message rendering
-
-## Behavior Notes
-
-- **Range type** renders a styled slider without borders or adornments; still supports `label` via `FieldWrapper`
-- **`loading`** replaces `endAdornment` with a spinning `Loader2` icon
-- **`isInvalid`** is derived from either the `invalid` prop or a truthy `error` string
-- Autofill background override applied via `-webkit-box-shadow` hack for consistent theming
+- **`Input`** — The primary `forwardRef` component wrapping a native `<input>` with ODS design tokens
+- **`InputProps`** — Extended interface adding `invalid`, `startAdornment`, `endAdornment`, `label`, `error`, `errorVariant`, and `loading` to standard HTML input attributes
+- **`FieldWrapper`** — Wraps content with optional label and error message display
+- **`invalidBorderClasses`** — Lookup map for `"error"` (red) and `"warning"` (yellow) border styling variants
+- **Range input branch** — Special-cased rendering for `type="range"` that skips the label wrapper and adornments, applying custom slider track/thumb styles
 
 ## Usage Example
 
 ```typescript
-// Basic input with label and error
-<Input
-  label="Email"
-  type="email"
-  placeholder="you@example.com"
-  error="Invalid email address"
-  errorVariant="error"
-/>
+import { Input } from "@/components/ui/input";
+import { Search, X } from "lucide-react";
 
-// Input with adornments and loading state
+// Basic usage with label
+<Input label="Email" type="email" placeholder="you@example.com" />
+
+// With adornments and error state
 <Input
-  label="Search"
-  startAdornment={<SearchIcon />}
-  loading={isFetching}
-  placeholder="Search tickets..."
+  label="Username"
+  startAdornment={<Search />}
+  endAdornment={<X />}
+  error="Username already taken"
+  errorVariant="warning"
 />
 
+// Loading state (replaces endAdornment)
+<Input label="Search" loading={true} />
+
 // Range slider
 <Input
   type="range"
@@ -43,11 +38,4 @@ A client-side input component built with `React.forwardRef`, supporting labels,
   max={100}
   defaultValue={50}
 />
-
-// Warning variant
-<Input
-  label="Username"
-  error="Username already taken"
-  errorVariant="warning"
-/>
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.modal-v2.md b/openframe-frontend-core/src/components/ui/.modal-v2.md
index cbb3ea609..aaa2d4ce6 100644
--- a/openframe-frontend-core/src/components/ui/.modal-v2.md
+++ b/openframe-frontend-core/src/components/ui/.modal-v2.md
@@ -1,15 +1,25 @@
-<!-- source-hash: 4e95a6a9f9ef814174b92059833949dc -->
-Accessible modal dialog component with keyboard navigation, backdrop click-to-close, and scroll locking. Built with React context to share close functionality across sub-components.
+<!-- source-hash: c4c2e754380fa98226ef792c8f409ece -->
+Animated modal dialog component with open/close transitions, keyboard support, and a composable sub-component API.
 
 ## Key Components
 
 | Export | Description |
 |--------|-------------|
-| `ModalV2` | Root modal container — manages open state, Escape key handling, and body scroll lock |
-| `ModalV2Header` | Header row with close button (desktop only); consumes `ModalContext` for `onClose` |
+| `ModalV2` | Root modal container — manages mount/unmount lifecycle, backdrop, Escape key handling, and scroll lock |
+| `ModalV2Header` | Header row with optional close button (desktop only) via `ModalContext` |
 | `ModalV2Title` | Styled `<h2>` heading for the modal title |
-| `ModalV2Content` | Scrollable content area with `overflow-y-auto` |
-| `ModalV2Footer` | Flex row container for action buttons |
+| `ModalV2Content` | Scrollable content area (`overflow-y-auto`, `flex-1`) |
+| `ModalV2Footer` | Flex row for action buttons |
+
+**Internal:** `ModalContext` passes `onClose` down to `ModalHeader` without prop drilling.
+
+## Behaviour Notes
+
+- **Animation** — backdrop and panel use `data-[state=open/closed]` + Tailwind animate-in/out utilities (200 ms). `fill-mode-forwards` prevents an opacity flash before unmount.
+- **Responsive motion** — mobile slides up from the bottom; desktop fades + zooms from center.
+- **Body scroll lock** — `document.body.style.overflow = 'hidden'` while open, restored on close.
+- **Keyboard** — `Escape` triggers `onClose`.
+- **Delayed unmount** — component stays mounted for 200 ms after `isOpen` becomes `false` so the exit animation completes.
 
 ## Usage Example
 
@@ -20,32 +30,24 @@ import {
   ModalV2Title,
   ModalV2Content,
   ModalV2Footer,
-} from "@/components/modal-v2"
-
-function ExampleModal() {
-  const [isOpen, setIsOpen] = React.useState(false)
+} from "@/components/ui/modal-v2"
 
+function DeleteDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
   return (
-    <ModalV2 isOpen={isOpen} onClose={() => setIsOpen(false)}>
+    <ModalV2 isOpen={open} onClose={onClose}>
       <ModalV2Header>
-        <ModalV2Title>Confirm Action</ModalV2Title>
+        <ModalV2Title>Confirm Delete</ModalV2Title>
       </ModalV2Header>
+
       <ModalV2Content>
-        <p>Are you sure you want to proceed?</p>
+        <p>This action cannot be undone.</p>
       </ModalV2Content>
+
       <ModalV2Footer>
-        <button onClick={() => setIsOpen(false)}>Cancel</button>
-        <button onClick={handleConfirm}>Confirm</button>
+        <button onClick={onClose}>Cancel</button>
+        <button onClick={() => { /* delete */ onClose() }}>Delete</button>
       </ModalV2Footer>
     </ModalV2>
   )
 }
-```
-
-## Behavior Notes
-
-- **Escape key** closes the modal automatically while open
-- **Backdrop click** dismisses via the overlay `div`
-- **Body scroll** is locked (`overflow: hidden`) while open and restored on close
-- **Close button** renders only on `md+` breakpoints; mobile relies on backdrop/Escape
-- All sub-components forward refs to their underlying DOM elements
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.more-actions-menu.md b/openframe-frontend-core/src/components/ui/.more-actions-menu.md
index 5f3db5b48..69740f8a3 100644
--- a/openframe-frontend-core/src/components/ui/.more-actions-menu.md
+++ b/openframe-frontend-core/src/components/ui/.more-actions-menu.md
@@ -1,54 +1,52 @@
-<!-- source-hash: d1c57ae6ae958d461aaf3fb171dd1d00 -->
-A compact, reusable dropdown menu component triggered by an ellipsis icon button, built on Radix UI's `DropdownMenu`. Supports both link-based and click-based menu items with optional icons, danger states, and controlled open/close behavior.
+<!-- source-hash: 1b9595070b200a15f0fd544276e73f2e -->
+A deprecated dropdown menu component that renders a list of action items triggered by an ellipsis icon button, built on top of Radix UI's `DropdownMenu`.
 
 ## Key Components
 
-### `MoreActionsItem`
-Type definition for individual menu entries:
+### `MoreActionsItem` *(deprecated)*
+Type definition for individual menu items. Supports:
 - `label` — display text
-- `onClick` — optional click handler
-- `href` — renders item as a `<Link>` (anchor tag) instead of a button
+- `onClick` — click handler
+- `href` — renders item as a Next.js `<Link>` (SEO-friendly)
 - `openInNewTab` — applies `target="_blank"` when using `href`
-- `icon` — optional React node rendered before the label
-- `disabled` — disables interaction and reduces opacity
+- `icon` — optional React node rendered left of the label
+- `disabled` — disables interaction
 - `danger` — applies error color styling to the icon
 
-### `MoreActionsMenuProps`
-Configuration interface for the menu:
-- `items` — array of `MoreActionsItem`
-- `align`, `side`, `sideOffset` — Radix positioning controls
-- `trigger` — optional custom trigger element (replaces default ellipsis button)
-- `open` / `onOpenChange` — controlled open state support
+### `MoreActionsMenuProps` *(deprecated)*
+Interface for the menu component, supporting controlled open state (`open` / `onOpenChange`), custom trigger override, alignment/positioning props, and focus management via `onCloseAutoFocus`.
 
-### `MoreActionsMenu`
-The exported component. Renders either a default ellipsis icon `Button` or a custom `trigger`, with a `DropdownMenuContent` list of items.
+### `MoreActionsMenu` *(deprecated)*
+The primary exported component. Renders an ellipsis icon button (or custom `trigger`) that opens a styled dropdown. Each item renders as either a `<Link>` (when `href` is set) or a button `DropdownMenuItem`.
 
 ## Usage Example
 
 ```typescript
 import { MoreActionsMenu } from './more-actions-menu'
-import { EditIcon, TrashIcon } from '../icons'
+import { TrashIcon } from '../icons-v2-generated'
 
 <MoreActionsMenu
   items={[
     {
-      label: 'Edit',
-      icon: <EditIcon />,
-      onClick: () => console.log('edit'),
+      label: 'View Details',
+      href: '/tickets/123',
+      icon: <InfoIcon />
     },
     {
-      label: 'View Details',
+      label: 'Open in new tab',
       href: '/tickets/123',
-      openInNewTab: true,
+      openInNewTab: true
     },
     {
       label: 'Delete',
+      onClick: () => handleDelete(),
       icon: <TrashIcon />,
-      danger: true,
-      onClick: () => console.log('delete'),
-    },
+      danger: true
+    }
   ]}
   align="end"
   side="bottom"
 />
-```
\ No newline at end of file
+```
+
+> **Deprecated:** Migrate to `ActionsMenuDropdown` from `./actions-menu`, which supports all the same features plus grouped items, checkboxes, and submenus.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.portal-container.md b/openframe-frontend-core/src/components/ui/.portal-container.md
new file mode 100644
index 000000000..6cee95962
--- /dev/null
+++ b/openframe-frontend-core/src/components/ui/.portal-container.md
@@ -0,0 +1,42 @@
+<!-- source-hash: cd6ef482a4e9898cb3090a6c0ba0b8ae -->
+Provides a React context for overriding the default Radix UI portal target, allowing overlay components (dropdowns, tooltips) to portal into a specific DOM node instead of `document.body`.
+
+## Key Components
+
+- **`PortalContainerContext`** — React context holding the target `HTMLElement` (or `null` to fall back to `document.body`)
+- **`usePortalContainer()`** — Hook that returns the active portal container from context
+
+## Usage Example
+
+```typescript
+// Wrap a high-z surface (e.g. chat drawer) with a ref-bound provider
+// so all Radix overlays inside it inherit the local stacking context.
+
+function ChatDrawer() {
+  const [container, setContainer] = React.useState<HTMLElement | null>(null)
+
+  return (
+    <PortalContainerContext.Provider value={container}>
+      <div ref={setContainer} className="chat-drawer">
+        <DropdownMenu>
+          {/* Portal targets the drawer div, not document.body */}
+          <DropdownMenuContent />
+        </DropdownMenu>
+      </div>
+    </PortalContainerContext.Provider>
+  )
+}
+
+// Inside any Radix component, pass the container to the Portal prop
+function MyDropdown() {
+  const portalContainer = usePortalContainer()
+
+  return (
+    <DropdownMenu.Portal container={portalContainer}>
+      <DropdownMenu.Content>...</DropdownMenu.Content>
+    </DropdownMenu.Portal>
+  )
+}
+```
+
+> **Why not `document.body`?** Portaling to `document.body` breaks z-index isolation — overlays inside a high-z surface must compete at the document root. A scoped portal node keeps z-indices small and local. Radix uses `position: fixed` internally, so `overflow: hidden` clipping is still escaped regardless of the portal target.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.simple-markdown-renderer.md b/openframe-frontend-core/src/components/ui/.simple-markdown-renderer.md
index 0dc408722..834a5b3e1 100644
--- a/openframe-frontend-core/src/components/ui/.simple-markdown-renderer.md
+++ b/openframe-frontend-core/src/components/ui/.simple-markdown-renderer.md
@@ -1,40 +1,38 @@
-<!-- source-hash: cb258dc120396ef8c715487b0cdc1022 -->
-Client-side React component that renders LLM-generated markdown safely, combining `react-markdown` with a custom XSS sanitization pipeline and support for GitHub-flavored markdown, syntax highlighting, and embedded media.
+<!-- source-hash: e7310557db0b784d7351a39daa2972fd -->
+A client-side React component that renders Markdown content safely with LLM/chat output in mind, combining `react-markdown`, GFM, syntax highlighting, and a layered XSS sanitization pipeline.
 
 ## Key Components
 
-### Security Pipeline
-- **`rehypeStripUnsafe()`** — Custom rehype plugin that strips dangerous HAST nodes after `rehype-raw` parsing. Removes `<script>`, `<style>`, `<object>`, event handler attributes (`on*`), `javascript:` / `data:` URIs, and `iframe srcdoc` vectors.
-- **`srcsetHasUnsafeCandidate()`** — Inspects every candidate URL in `srcset` attributes (not just the first), preventing multi-candidate injection attacks.
-- **`escapeUnknownHtmlTags()`** — Pre-processes markdown text to escape HTML tags not in the `SAFE_HTML_TAGS` allowlist, preventing LLM-emitted XML-style tags (e.g., `<ticket>`, `<their>`) from reaching React as unrecognized custom elements. Preserves code blocks and inline code spans.
-- **`cardAwareUrlTransform()`** — Extends `react-markdown`'s default URL sanitizer to allow the internal `card://` scheme for chat-card markers while keeping all other unsafe schemes blocked.
+### `rehypeStripUnsafe()`
+A custom rehype plugin (runs post `rehype-raw`) that strips dangerous HAST nodes and attributes:
+- Drops `<script>`, `<style>`, `<noscript>`, `<object>`, and related elements
+- Removes `on*` event handler attributes
+- Blocks `javascript:` and `data:` URI schemes on URL-bearing attributes (`href`, `src`, `srcset`, `formaction`, etc.)
+- Handles multi-candidate `srcset` strings via `srcsetHasUnsafeCandidate()`
+- Neutralizes root-level strip elements in-place
 
-### Constants & Regexes
-| Export | Purpose |
-|--------|---------|
-| `SAFE_HTML_TAGS` | Allowlist of permitted HTML5 tags forwarded to React |
-| `STRIP_ELEMENTS` | Tags removed entirely at the HAST level |
-| `EVENT_HANDLER_ATTR_RE` | Matches `on*` attribute names |
-| `JAVASCRIPT_URL_RE` / `DATA_URL_RE` | Detect unsafe URL schemes |
-| `TAG_LIKE_REGEX` | Parses HTML-like tags in markdown source |
+### `cardAwareUrlTransform(url, key)`
+Extends `react-markdown`'s default URL transformer to allow the internal `card://` scheme (used for inline chat-card markers) while keeping all other dangerous schemes (`javascript:`, `data:`, etc.) blocked.
 
-### Mermaid Support
-- `mermaidStyles` — Responsive CSS for Mermaid SVG diagrams using DM Sans font.
+### `escapeUnknownHtmlTags(text)`
+Pre-processes raw markdown text to escape non-allowlisted HTML tags before they reach `rehype-raw`, preventing LLM-emitted pseudo-tags (`<their>`, `<ticket>`) from reaching React as unrecognized custom elements. Uses a ReDoS-hardened, bounded regex (`TAG_LIKE_REGEX`) with hard limits on tag name length (63 chars) and attribute length (4096 chars).
+
+### `SAFE_HTML_TAGS`
+An allowlist of permitted HTML5 tags forwarded as-is through the pipeline (block/inline text, media, forms).
 
 ## Usage Example
 
 ```typescript
-import { SimpleMarkdownRenderer } from './simple-markdown-renderer';
+import { escapeUnknownHtmlTags } from './simple-markdown-renderer';
 
-// Basic usage — content is sanitized automatically
-<SimpleMarkdownRenderer
-  content="## Hello\n\nThis is **LLM-generated** markdown with `code`."
-/>
+// Pre-process LLM output before rendering
+const safeMarkdown = escapeUnknownHtmlTags(llmOutput);
 
-// The sanitizer prevents XSS from LLM output automatically:
-// "<script>alert(1)</script>" → stripped
-// "<their> tag" → escaped to &lt;their&gt;
-// "javascript:alert(1)" href → removed
+// The component internally applies:
+// 1. escapeUnknownHtmlTags (text pre-pass)
+// 2. rehype-raw (parse inline HTML)
+// 3. rehypeStripUnsafe (HAST sanitizer)
+// 4. rehype-highlight (syntax coloring)
 ```
 
-> **Note:** This renderer is designed specifically for untrusted LLM output. The sanitization pipeline runs in layers: text pre-processing → `rehype-raw` → `rehypeStripUnsafe` → `rehype-highlight`, ensuring no XSS vectors survive even if one layer is bypassed. Community support is available on the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA).
\ No newline at end of file
+> **Security note:** `rehypeStripUnsafe` is the authoritative security boundary. `escapeUnknownHtmlTags` is a best-effort pre-pass for React compatibility, not a security control.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.square-avatar.md b/openframe-frontend-core/src/components/ui/.square-avatar.md
index 058e7d479..433312ea2 100644
--- a/openframe-frontend-core/src/components/ui/.square-avatar.md
+++ b/openframe-frontend-core/src/components/ui/.square-avatar.md
@@ -1,49 +1,45 @@
-<!-- source-hash: 5ede4b179e76c93d7dbba4fcff5327a9 -->
-A flexible avatar component that displays a user image or falls back to initials, supporting both square and round variants with multiple size options.
+<!-- source-hash: 49fd4937ced9d6bd9f4f91e876250d30 -->
+A flexible avatar component that renders a user image with an automatic initials-based fallback, supporting square and round variants across four sizes.
 
 ## Key Components
 
-### `SquareAvatarProps`
-Extends `React.HTMLAttributes<HTMLDivElement>` with:
+### `SquareAvatar`
+
+A memoized, forwarded-ref React component with the following props:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `src` | `string` | — | Image URL |
-| `alt` | `string` | — | Image alt text (also used for initials fallback) |
+| `src` | `string` | — | Image URL to display |
+| `alt` | `string` | — | Alt text; also used to derive initials |
 | `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Controls dimensions (32/40/48/64px) |
-| `fallback` | `string` | — | Preferred string for generating initials |
+| `fallback` | `string` | — | Preferred string for deriving initials (overrides `alt`) |
 | `variant` | `'square' \| 'round'` | `'square'` | Border radius style |
+| `initialsClassName` | `string` | — | Tailwind overrides for initials font size/color |
+| `className` | `string` | — | Additional classes for the outer wrapper |
 
-### `SquareAvatar`
-A memoized, forwarded-ref component that renders an image with automatic graceful degradation to initials on load error or missing `src`.
+**Fallback behavior:** When `src` is absent or fails to load, the component displays initials extracted via `getFirstLastInitials()` (from `fallback` → `alt` → `'?'`). On image error, the `<img>` is hidden and the initials layer is revealed.
 
-**Fallback behavior:** Uses `getFirstLastInitials()` on `fallback ?? alt`, rendering `'?'` if neither yields initials. The initials layer uses `text-ods-text-primary` to maintain WCAG AA contrast across accent-fill backgrounds (e.g. Mingo cyan, current-user pink).
+**Accessibility note:** Initials use `text-ods-text-primary` to maintain WCAG AA contrast on both default and accent-fill backgrounds (e.g. `bg-ods-flamingo-pink`).
 
 ## Usage Example
 
 ```typescript
-// Image avatar
-<SquareAvatar
-  src="https://example.com/avatar.jpg"
-  alt="Jane Doe"
-  size="lg"
-  variant="round"
-/>
+// Basic image avatar
+<SquareAvatar src="/avatars/john.png" alt="John Doe" size="md" />
 
-// Initials-only avatar (no src)
+// Round variant with explicit fallback text
 <SquareAvatar
-  fallback="Jane Doe"
-  size="md"
-  variant="square"
+  variant="round"
+  size="lg"
+  fallback="Jane Smith"
+  alt="Jane Smith"
 />
 
-// With custom className and forwarded ref
-const ref = React.useRef<HTMLDivElement>(null);
+// Compact initials-only avatar with custom text size
 <SquareAvatar
-  ref={ref}
-  src={userAvatarUrl}
-  alt={userName}
-  size="xl"
-  className="ring-2 ring-ods-flamingo-pink"
+  size="sm"
+  alt="Mingo AI"
+  initialsClassName="text-[10px]"
+  className="bg-ods-flamingo-cyan"
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.tags-input.md b/openframe-frontend-core/src/components/ui/.tags-input.md
index 0d2cc4ba2..5c011eb90 100644
--- a/openframe-frontend-core/src/components/ui/.tags-input.md
+++ b/openframe-frontend-core/src/components/ui/.tags-input.md
@@ -1,51 +1,47 @@
-<!-- source-hash: 9eb10752292d24eee24cde4356bcc193 -->
-A React component that provides an interactive tags input interface, allowing users to add, remove, and manage a collection of string tags with keyboard shortcuts and validation.
+<!-- source-hash: 1d32b848693e89c30dcd375d01af0414 -->
+A controlled tags input component that allows users to add and remove string tags via keyboard or button interaction.
 
 ## Key Components
 
-- **TagsInput**: Main component that manages tag state and user interactions
-- **handleAddTag**: Adds new tags with duplicate checking and max limit validation
-- **handleRemoveTag**: Removes tags from the collection
-- **handleKeyPress**: Enables Enter key for adding tags
-- **TagsInputProps**: Interface defining component configuration options
+### `TagsInput`
+Main export — a form component managing a list of string tags with add/remove functionality.
+
+**Props (`TagsInputProps`):**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string[]` | `[]` | Controlled list of current tags |
+| `onChange` | `(tags: string[]) => void` | — | Callback fired on add/remove |
+| `placeholder` | `string` | `"Add a tag..."` | Input placeholder text |
+| `disabled` | `boolean` | `false` | Disables all interactions |
+| `maxTags` | `number` | — | Optional cap on number of tags |
+| `label` | `string` | — | Optional field label |
+| `inputClassName` | `string` | — | Extra classes for the text input |
+| `badgeClassName` | `string` | — | Extra classes for tag badges |
+
+**Behavior:**
+- Tags are added via **Enter** key or **Add** button
+- Duplicate tags are silently ignored
+- Tags are removed via the `X` button on each badge
+- Input and Add button disable automatically when `maxTags` is reached
+- Displays a `{current}/{max}` counter when `maxTags` is set
 
 ## Usage Example
 
 ```typescript
-import { TagsInput } from "./tags-input"
-import { useState } from "react"
+import { TagsInput } from "@/components/ui/tags-input"
 
-function MyForm() {
-  const [tags, setTags] = useState<string[]>([])
+function TicketForm() {
+  const [tags, setTags] = React.useState<string[]>(["urgent", "network"])
 
   return (
     <TagsInput
+      label="Ticket Tags"
       value={tags}
       onChange={setTags}
-      label="Skills"
-      placeholder="Add a skill..."
+      placeholder="Add a tag..."
       maxTags={5}
-      className="w-full"
-      badgeClassName="bg-blue-100 text-blue-800"
     />
   )
 }
-
-// With initial tags
-function PrefilledTags() {
-  const [technologies, setTechnologies] = useState([
-    "React", "TypeScript", "Node.js"
-  ])
-
-  return (
-    <TagsInput
-      value={technologies}
-      onChange={setTechnologies}
-      placeholder="Add technology..."
-      disabled={false}
-    />
-  )
-}
-```
-
-The component features duplicate prevention, optional tag limits, keyboard navigation, customizable styling, and accessibility support with proper ARIA labels.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.textarea.md b/openframe-frontend-core/src/components/ui/.textarea.md
index 70e6a7d89..67d27b09f 100644
--- a/openframe-frontend-core/src/components/ui/.textarea.md
+++ b/openframe-frontend-core/src/components/ui/.textarea.md
@@ -1,52 +1,54 @@
-<!-- source-hash: ec4ed0c801de7134f1ad25648dec0319 -->
-A client-side textarea component supporting labels, validation states, and optional end icons (as decorative spans or interactive buttons), built on top of `FieldWrapper`.
+<!-- source-hash: 373c15f710bf8978e55a34a0a25a6266 -->
+A client-side textarea component that extends the native HTML `<textarea>` with ODS design system styling, optional label/error display, and support for an end icon (static or interactive button).
 
 ## Key Components
 
-### `Textarea`
-A `React.forwardRef` component extending native `HTMLTextAreaElement` attributes with the following additional props:
+**`Textarea`** — The primary export; a `React.forwardRef` component with two layout modes:
+- **Without `endIcon`**: Renders a styled `<textarea>` directly inside `FieldWrapper` with resizable height and full border/hover/focus/error states.
+- **With `endIcon`**: Lifts border and background onto a `<label>` wrapper (mirroring the `Input` component layout), with the textarea as a transparent child and the icon anchored to the bottom-right. Uses CSS `field-sizing: content` for auto-grow behavior.
+
+**`FieldWrapper`** — Wraps both layouts to render the optional `label` above and `error` message below.
+
+**`TextareaProps`** — Interface extending `React.TextareaHTMLAttributes<HTMLTextAreaElement>`:
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `invalid` | `boolean` | Renders red error border/ring |
-| `label` | `string` | Label text above the textarea |
-| `error` | `string` | Error message below the textarea |
+| `invalid` | `boolean` | Forces red error border/ring |
+| `label` | `string` | Label rendered above the field |
+| `error` | `string` | Error message rendered below the field |
 | `endIcon` | `React.ReactNode` | Icon rendered at the right edge |
 | `endIconAsButton` | `boolean` | Wraps `endIcon` in a styled `<button>` |
 | `endIconButtonProps` | `ButtonHTMLAttributes` | Extra props for the end-icon button |
 
-**Two layout modes:**
-- **Without `endIcon`**: Border and background styles live directly on the `<textarea>` element.
-- **With `endIcon`**: A `<label>` wrapper hosts the border/background so the icon appears visually inside the field. The textarea uses `[field-sizing:content]` for native CSS auto-grow and caps height at `160px` with internal scroll.
-
 ## Usage Example
 
 ```typescript
-// Basic textarea with label and validation
+// Basic textarea with label and error
 <Textarea
   label="Message"
-  placeholder="Type your message..."
-  error="Message is required"
+  placeholder="Type here..."
+  error="This field is required"
 />
 
-// Auto-growing textarea with a submit button icon
+// Chat-style textarea with interactive send button
+import { SendIcon } from "lucide-react"
+
 <Textarea
-  label="Chat Input"
-  placeholder="Ask something..."
+  label="Message"
+  placeholder="Ask anything..."
   endIcon={<SendIcon />}
   endIconAsButton
   endIconButtonProps={{
-    'aria-label': 'Send message',
+    "aria-label": "Send message",
     onClick: handleSend,
     disabled: isLoading,
   }}
 />
 
-// Controlled with disabled state
+// Disabled state
 <Textarea
-  value={value}
-  onChange={(e) => setValue(e.target.value)}
+  label="Read-only notes"
+  value="Cannot edit this"
   disabled
-  rows={4}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.ticket-attachments-list.md b/openframe-frontend-core/src/components/ui/.ticket-attachments-list.md
index cd1c38a3b..470265958 100644
--- a/openframe-frontend-core/src/components/ui/.ticket-attachments-list.md
+++ b/openframe-frontend-core/src/components/ui/.ticket-attachments-list.md
@@ -1,45 +1,45 @@
-<!-- source-hash: 9fe959702866abb3d54c107fab70e0a4 -->
-Renders a styled list of file attachments for a support ticket, displaying thumbnail or file icon, name, size, and an optional download button per item.
+<!-- source-hash: 061aa5b351e6b7dbeac7c9631cc291b5 -->
+A client-side React component that renders a styled list of ticket file attachments, supporting thumbnail previews, file metadata, and optional download actions.
 
 ## Key Components
 
-- **`TicketAttachment`** — Interface describing a single attachment: `id`, `fileName`, `fileSize`, optional `thumbnailSrc`, and optional `onDownload` callback
-- **`TicketAttachmentsListProps`** — Props interface accepting an `attachments` array and optional `className`
-- **`TicketAttachmentsList`** — Main component that maps over attachments, rendering each row with a `SquareAvatar` (if thumbnail exists) or a fallback `FileIcon`, truncated filename, file size, and a download button
+**Interfaces**
+- `TicketAttachment` — Describes a single attachment: `id`, `fileName`, `fileSize`, `thumbnailSrc?`, `onDownload?`
+- `TicketAttachmentsListProps` — Component props: `attachments[]`, `className?`, `size?` (`'default' | 'compact'`)
+
+**Component**
+- `TicketAttachmentsList` — Renders a bordered list of attachments; returns `null` when the array is empty
+
+## Behavior Notes
+
+- **Thumbnail vs. icon:** Shows a `SquareAvatar` if `thumbnailSrc` is provided, otherwise falls back to a `FileIcon` placeholder
+- **Size variants:** `compact` reduces padding, icon size, and typography for inline use inside conversation feeds; `default` uses a roomier layout for standalone surfaces
+- **Download button:** Only rendered when `onDownload` is defined on the attachment; includes an accessible `aria-label`
+- **Dividers:** A bottom border is applied between rows (not after the last item)
 
 ## Usage Example
 
 ```typescript
-import { TicketAttachmentsList, TicketAttachment } from "./ticket-attachments-list"
+import { TicketAttachmentsList } from "./ticket-attachments-list"
 
-const attachments: TicketAttachment[] = [
+const attachments = [
   {
     id: "1",
     fileName: "screenshot.png",
     fileSize: "1.2 MB",
-    thumbnailSrc: "https://cdn.example.com/thumb.png",
-    onDownload: () => console.log("Downloading screenshot.png"),
+    thumbnailSrc: "/thumbs/screenshot.png",
+    onDownload: () => console.log("Downloading..."),
   },
   {
     id: "2",
-    fileName: "error-log.txt",
-    fileSize: "48 KB",
-    onDownload: () => console.log("Downloading error-log.txt"),
+    fileName: "report.pdf",
+    fileSize: "340 KB",
   },
 ]
 
-export default function TicketDetail() {
-  return (
-    <TicketAttachmentsList
-      attachments={attachments}
-      className="mt-4"
-    />
-  )
-}
-```
-
-## Notes
-
-- Returns `null` when the `attachments` array is empty — safe to render unconditionally
-- Long filenames are truncated with CSS and exposed via the `title` attribute for full visibility on hover
-- Download button only renders when `onDownload` is provided
\ No newline at end of file
+// Full-size layout (e.g. ticket detail page)
+<TicketAttachmentsList attachments={attachments} />
+
+// Compact layout (e.g. inside a message bubble)
+<TicketAttachmentsList attachments={attachments} size="compact" />
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.ticket-info-section.md b/openframe-frontend-core/src/components/ui/.ticket-info-section.md
index abffc36f6..1dd37efcd 100644
--- a/openframe-frontend-core/src/components/ui/.ticket-info-section.md
+++ b/openframe-frontend-core/src/components/ui/.ticket-info-section.md
@@ -1,56 +1,50 @@
-<!-- source-hash: 25c594905e7f584756ad751975cbc35e -->
-A collapsible ticket information panel that displays key ticket metadata (organization, assignee, device, status) in a header row, with an expandable section revealing additional details like description, attachments, tags, and notes.
+<!-- source-hash: 7ac50b47361449080e2ba3874b959c5f -->
+Collapsible ticket information panel component that displays and manages ticket metadata (organization, assignee, device, status) in a compact header row with an optional expanded view for additional details like description, attachments, tags, and notes.
 
 ## Key Components
 
-### `TicketInfoSection`
-Main export. Renders a bordered card with a responsive header grid and optional expanded content area.
-
-### `InfoCell` (internal)
-Reusable label/value display cell supporting an optional icon and clickable value.
-
-### `TicketInfoSectionProps`
-Full interface for the component:
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `organization` | `{ name, imageSrc? }` | Org name and avatar |
-| `device` | `{ name, icon?, onClick? }` | Device name with optional navigation |
-| `status` | `string` | Rendered via `TicketStatusTag` |
-| `assigned` | `AssignedConfig` | Assignee dropdown config |
-| `expanded` | `boolean` | Controls expanded section visibility |
-| `onExpand` | `() => void` | Expand/collapse toggle handler |
-| `description` | `string` | Markdown/HTML content |
-| `attachments` | `TicketAttachment[]` | Downloadable file list |
-| `tags` | `string[]` | Label tags |
-| `notes` | `TicketNote[]` | Notes with add/edit/delete handlers |
+- **`TicketInfoSection`** — Main export; renders the full panel with header and optional expanded content
+- **`InfoCell`** — Internal helper; renders a labeled value with optional icon and clickable behavior
+- **`TicketInfoSectionProps`** — Full prop interface for the component
+- **`TicketAssigneeOption`** — Re-exported type from `AssigneeDropdown`
 
 ## Usage Example
 
 ```typescript
 import { TicketInfoSection } from "./ticket-info-section"
 
-function TicketPage() {
-  const [expanded, setExpanded] = React.useState(false)
-
-  return (
-    <TicketInfoSection
-      organization={{ name: "Acme Corp", imageSrc: "/acme-logo.png" }}
-      device={{ name: "DESKTOP-XYZ01", onClick: () => router.push("/devices/1") }}
-      status="open"
-      expanded={expanded}
-      onExpand={() => setExpanded(prev => !prev)}
-      assigned={{
-        currentAssignee: { id: "u1", name: "Jane Doe" },
-        options: assigneeOptions,
-        onAssign: (userId) => handleAssign(userId),
-      }}
-      createdAt="Jan 15, 2025"
-      description="**Issue:** User cannot log in.\n\nSteps to reproduce..."
-      tags={["urgent", "auth"]}
-      notes={notes}
-      onAddNote={(text) => addNote(text)}
-    />
-  )
-}
-```
\ No newline at end of file
+<TicketInfoSection
+  organization={{ name: "Acme Corp", imageSrc: "/acme-logo.png" }}
+  device={{ name: "DESKTOP-001", onClick: () => navigate("/devices/1") }}
+  status="open"
+  statusLabel="Open"
+  statusColor="#4ECDC4"
+  statusOptions={[
+    { id: "open", label: "Open" },
+    { id: "closed", label: "Closed" },
+  ]}
+  onStatusSelect={(id) => updateTicketStatus(id)}
+  expanded={isExpanded}
+  onExpand={() => setIsExpanded(!isExpanded)}
+  assigned={{
+    currentAssignee: { id: "u1", name: "Jane Doe" },
+    options: assigneeList,
+    onAssign: (userId) => reassignTicket(userId),
+  }}
+  createdAt="Jan 15, 2025"
+  description="## Issue\nUser cannot log in after password reset."
+  attachments={[{ id: "a1", name: "screenshot.png", url: "/files/screenshot.png" }]}
+  tags={["vpn", "urgent"]}
+  notes={notesList}
+  onAddNote={(text) => addNote(text)}
+  onEditNote={(id, text) => editNote(id, text)}
+  onDeleteNote={(id) => deleteNote(id)}
+/>
+```
+
+## Behavior Notes
+
+- The header row is always visible; expanded content renders conditionally via the `expanded` prop
+- Status tag becomes an interactive dropdown when `statusOptions` is provided
+- Assignee section falls back to an "Unassigned" placeholder when `assigned` is not provided
+- Description renders via `SimpleMarkdownRenderer` supporting markdown/HTML content
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.ticket-status-config-row.md b/openframe-frontend-core/src/components/ui/.ticket-status-config-row.md
new file mode 100644
index 000000000..47548af57
--- /dev/null
+++ b/openframe-frontend-core/src/components/ui/.ticket-status-config-row.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 3da24d0b547a12dae742cd75f0269594 -->
+A configurable row component for managing individual ticket status entries in a settings/configuration UI, supporting both system-defined (read-only) and custom (editable, draggable) status variants.
+
+## Key Components
+
+### `TicketStatusConfigRow`
+Main exported component rendering a full-width row with:
+- **Drag handle** — active grab button for custom rows; disabled ghost icon for system rows
+- **Name input** — editable for custom rows, read-only for system rows
+- **Color controls** — `ColorPresetSelect` + `ColorPickerInput` for custom rows only
+- **Live preview** — `TicketStatusTag` reflecting current name/color in real time
+- **Action slot** — info tooltip icon (system) or delete button with optional disabled-reason tooltip (custom)
+
+### `TicketStatusConfigRowProps`
+Full interface controlling row behavior. Key props:
+
+| Prop | Type | Purpose |
+|------|------|---------|
+| `variant` | `'system' \| 'custom'` | Switches between read-only and editable modes |
+| `statusKey` | `string` | Canonical key forwarded to `TicketStatusTag` |
+| `onColorChange` | `(next: { color: string; preset?: string }) => void` | Color/preset change callback |
+| `dragHandleProps` / `dragHandleAttributes` | dnd-kit types | Wired to a `@dnd-kit` sortable context |
+| `deleteDisabledReason` | `string` | Tooltip shown when delete is blocked |
+
+### `WithLeftTooltip` (internal)
+Utility wrapper that conditionally wraps children in a left-aligned `TooltipProvider`; renders children directly when no content is provided.
+
+## Usage Example
+
+```typescript
+<TicketStatusConfigRow
+  variant="custom"
+  statusKey="IN_PROGRESS"
+  name={statusName}
+  onNameChange={setStatusName}
+  color="#4ECDC4"
+  presetKey={undefined}
+  onColorChange={({ color, preset }) => handleColorUpdate(color, preset)}
+  onDelete={handleDelete}
+  deleteDisabled={isLastStatus}
+  deleteDisabledReason="At least one custom status is required"
+  dragHandleProps={listeners}
+  dragHandleAttributes={attributes}
+  isDragging={isDragging}
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.ticket-status-tag.md b/openframe-frontend-core/src/components/ui/.ticket-status-tag.md
index e5d86048e..b8dbffe22 100644
--- a/openframe-frontend-core/src/components/ui/.ticket-status-tag.md
+++ b/openframe-frontend-core/src/components/ui/.ticket-status-tag.md
@@ -1,49 +1,56 @@
-<!-- source-hash: 5f8fd0a180217b9085f7ea5f038d319a -->
-Renders a styled badge for ticket statuses, normalizing any known status string (backend, chat, dialog-layer) into a canonical `TicketStatus` value with the correct color variant and optional icon.
+<!-- source-hash: 3e0480f55b0eb878756303aebfd30801 -->
+Renders a styled ticket status badge (`Tag`) that normalizes any status string format (backend enum, chat lowercase, HubSpot canonical, dialog-layer alias) to a canonical display with the correct color variant, icon, and optional inline status-change dropdown.
 
 ## Key Components
 
 ### Types & Exports
-| Export | Description |
-|--------|-------------|
-| `TicketStatus` | Canonical union type: `'ACTIVE' \| 'TECH_REQUIRED' \| 'ON_HOLD' \| 'RESOLVED' \| 'ARCHIVED'` |
-| `TicketStatusTagProps` | Props interface for the main component |
+- **`TicketStatus`** — Canonical union type: `'ACTIVE' | 'AI_ASSISTANCE' | 'TECH_REQUIRED' | 'ON_HOLD' | 'RESOLVED' | 'ARCHIVED'`
+- **`TicketStatusKind`** — Backend status-definition kinds including `'CUSTOM'`
+- **`TicketStatusInput`** — Unified input shape combining legacy `status`, `statusKind`, `statusName`, and `statusColor`
+- **`TicketStatusTagOption`** — Selectable option shape for the inline dropdown (`id`, `name`, `color`)
+- **`TicketStatusTagProps`** — Full component prop interface
 
 ### Utility Functions
-| Function | Description |
-|----------|-------------|
-| `resolveTicketStatus(status)` | Maps any known alias to a canonical `TicketStatus`; returns `null` for unknowns |
-| `getTicketStatusConfig(status)` | Returns `{ label, variant, icon }` for a given status string |
-| `getTicketStatusTag(status)` | Drop-in utility returning label/variant/icon for use outside the component |
+- **`resolveTicketStatus(status)`** — Resolves any string alias to a canonical `TicketStatus` or `null`
+- **`getTicketStatusConfig(status)`** — Returns `{ label, variant, icon }` for any known status format
+- **`getTicketStatusTag(status)`** — Drop-in utility returning `{ label, variant, icon }` for use with `<Tag>`
+- **`kindToCanonicalStatus(kind)`** — Maps backend kind to canonical status; returns `undefined` for `CUSTOM`
+- **`usesCanonicalStatusStyle(kind)`** — Returns `true` for kinds that use system styling (not custom color)
+- **`resolveStatusTagProps(input)`** — Maps `TicketStatusInput` fields to `TicketStatusTag` props
 
 ### Component
-- **`TicketStatusTag`** — Wraps the base `Tag` component with resolved status config. Supports label override, hex `color` override with automatic contrast text, `showIcon` toggle, and additional `className`.
+- **`TicketStatusTag`** — Main component; renders a `Tag` or an `ActionsMenuDropdown`-wrapped button with chevron when `options` + `onSelect` are provided
 
 ## Usage Example
 
 ```typescript
-// Basic usage
+// Basic status tag
 <TicketStatusTag status="ACTIVE" />
 
-// With alias from dialog layer
-<TicketStatusTag status="ACTION_REQUIRED" />
-
-// HubSpot pipeline stage — custom label, canonical color
-<TicketStatusTag status="OPEN" label="Waiting on Contact" />
-
-// Hex color override (e.g. from a custom pipeline stage)
-<TicketStatusTag status="ON_HOLD" color="#7C3AED" />
-
-// Utility usage outside JSX
-const { label, variant } = getTicketStatusTag('resolved')
-// → { label: 'Resolved', variant: 'outline', icon: <CheckCircleIcon /> }
-```
-
-### Status → Variant Map
-| Status | Variant | Icon |
-|--------|---------|------|
-| `ACTIVE` | `success` | — |
-| `TECH_REQUIRED` | `warning` | — |
-| `ON_HOLD` | `error` | — |
-| `RESOLVED` | `outline` | ✅ CheckCircle |
-| `ARCHIVED` | `grey` | — |
\ No newline at end of file
+// With legacy alias formats
+<TicketStatusTag status="action_required" />  // → "Tech Required" warning tag
+<TicketStatusTag status="OPEN" />              // → "Active" success tag
+
+// Custom color override (e.g. HubSpot pipeline stage)
+<TicketStatusTag
+  status="OPEN"
+  label="Waiting on Contact"
+  color="#7C3AED"
+/>
+
+// Inline status changer dropdown
+<TicketStatusTag
+  status={ticket.status}
+  options={statusOptions}
+  onSelect={(id) => updateStatus(ticket.id, id)}
+  isPending={isUpdating}
+/>
+
+// From lifecycle (custom-status) backend fields
+const props = resolveStatusTagProps({
+  statusKind: ticket.statusKind,
+  statusName: ticket.statusName,
+  statusColor: ticket.statusColor,
+})
+<TicketStatusTag {...props} />
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.toaster.md b/openframe-frontend-core/src/components/ui/.toaster.md
index 6b7f6a378..004026897 100644
--- a/openframe-frontend-core/src/components/ui/.toaster.md
+++ b/openframe-frontend-core/src/components/ui/.toaster.md
@@ -1,20 +1,20 @@
-<!-- source-hash: 1847d3dd263a7c340149cc9157774ef5 -->
-A client-side toast notification system built on top of [Sonner](https://sonner.emilkowal.ski/), providing styled toast components with variant support, progress indicators, and a specialized command approval flow.
+<!-- source-hash: 63ebf1cb836f9a68caa7d0b55338d5a5 -->
+Custom toast notification system built on top of [Sonner](https://sonner.emilkowal.ski/), providing styled `ToastCard` and `CommandApprovalToast` components with variant theming, progress indicators, and an approval workflow UI.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `Toaster` | Component | Root provider wrapping Sonner's `Toaster`; injects the `toast-progress` keyframe animation |
-| `ToastCard` | Component | Standard toast card with title, description, colored dot indicator, dismiss button, and animated progress bar |
-| `CommandApprovalToast` | Component | Expandable toast with Approve/Reject actions for AI command authorization flows |
-| `showToast` | Function | Imperative helper to fire a `ToastCard` toast |
+| `Toaster` | Component | Drop-in `<Toaster>` wrapper with ODS defaults (`bottom-right`, offset, gap, unstyled base) |
+| `ToastCard` | Component | Standard toast with title, description, colored dot, dismiss button, and animated progress bar |
+| `CommandApprovalToast` | Component | Expandable toast with approve/reject actions, command preview, and optional `ToolIcon` |
+| `showToast` | Function | Imperative helper to fire a `ToastCard` via Sonner's `custom` API |
 | `showCommandApprovalToast` | Function | Imperative helper to fire a `CommandApprovalToast` |
 | `ToastVariant` | Type | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` |
 
 ## Usage Example
 
-**Mount the provider once (root layout):**
+**Mount the toaster once at the app root:**
 
 ```typescript
 import { Toaster } from '@/components/toaster'
@@ -29,29 +29,30 @@ export default function RootLayout({ children }) {
 }
 ```
 
-**Fire a standard toast:**
+**Fire a simple toast:**
 
 ```typescript
 import { showToast } from '@/components/toaster'
 
 showToast({ title: 'Saved', description: 'Changes saved successfully.', variant: 'success' })
 
-// Shorthand
+// Shorthand string form
 showToast('Operation complete')
 ```
 
-**Request command approval (Mingo AI flow):**
+**Fire a command approval toast (e.g., Mingo AI tool execution):**
 
 ```typescript
 import { showCommandApprovalToast } from '@/components/toaster'
 
 showCommandApprovalToast({
-  command: 'apt-get upgrade -y',
-  toolType: 'terminal',
-  approvalDescription: 'This will upgrade all system packages.',
+  title: 'Tech Required',
+  command: 'Restart-Service -Name "Spooler"',
+  toolType: 'powershell',
+  approvalDescription: 'This will restart the Print Spooler on WORKSTATION-01.',
   onApprove: () => executeCommand(),
-  onReject: () => cancelJob(),
+  onReject: () => cancelCommand(),
 })
 ```
 
-> `CommandApprovalToast` defaults to `duration: Infinity` so it persists until the technician explicitly approves or rejects the action.
\ No newline at end of file
+> **Note:** `CommandApprovalToast` defaults to `duration: Infinity` — it persists until the technician explicitly approves, rejects, or dismisses it.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/components/ui/.tooltip.md b/openframe-frontend-core/src/components/ui/.tooltip.md
index a3493d36c..ec68924c2 100644
--- a/openframe-frontend-core/src/components/ui/.tooltip.md
+++ b/openframe-frontend-core/src/components/ui/.tooltip.md
@@ -1,14 +1,20 @@
-<!-- source-hash: 7a9da2d80c73e939b410ce27e719aa66 -->
-Accessible tooltip component built on Radix UI primitives, providing animated, portal-rendered tooltips with consistent ODS (OpenFrame Design System) styling.
+<!-- source-hash: e61305ff6a5939bc0be5cfa349c7d77b -->
+Accessible tooltip component built on Radix UI primitives, with portal-aware rendering that inherits the correct stacking context from parent containers like drawers.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `TooltipProvider` | Component | Context provider required at the app/layout level to manage tooltip state |
-| `Tooltip` | Component | Root wrapper controlling open/close behavior |
-| `TooltipTrigger` | Component | Element that activates the tooltip on hover/focus |
-| `TooltipContent` | Component | Styled content panel rendered in a portal with enter/exit animations |
+| `TooltipProvider` | Component | Radix `Provider` wrapper; wrap your app or section to enable tooltip functionality |
+| `Tooltip` | Component | Radix `Root`; manages open/close state |
+| `TooltipTrigger` | Component | Radix `Trigger`; the element that activates the tooltip on hover/focus |
+| `TooltipContent` | Component | Custom `forwardRef` content panel; portals into the active container via `usePortalContainer`, falls back to `document.body` |
+
+## Key Behaviors
+
+- **Portal container awareness** — uses `usePortalContainer()` to render inside the nearest active container (e.g. a drawer), preventing z-index conflicts
+- **Animated transitions** — enter/exit animations via Tailwind `animate-in`/`animate-out` with directional slide offsets per `data-[side=*]`
+- **Default `sideOffset`** — set to `4px` for consistent spacing out of the box
 
 ## Usage Example
 
@@ -20,15 +26,15 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip"
 
-export function ActionButton() {
+export function SaveButton() {
   return (
     <TooltipProvider>
       <Tooltip>
         <TooltipTrigger asChild>
-          <button>Hover me</button>
+          <button>💾</button>
         </TooltipTrigger>
         <TooltipContent side="top">
-          <p>Helpful context here</p>
+          Save changes
         </TooltipContent>
       </Tooltip>
     </TooltipProvider>
@@ -36,8 +42,4 @@ export function ActionButton() {
 }
 ```
 
-## Notes
-
-- `TooltipContent` defaults to `sideOffset={4}` and supports all four sides (`top`, `bottom`, `left`, `right`) with direction-aware slide-in animations via Tailwind data attributes.
-- Content is injected via a **portal**, ensuring correct stacking context (`z-[1400]`) above modals and overlays.
-- `TooltipProvider` should be placed high in the component tree (e.g., root layout) to avoid nesting multiple providers unnecessarily.
\ No newline at end of file
+> `TooltipProvider` should wrap the root of your app or layout once, rather than each individual tooltip instance.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/contexts/.chat-runtime-context.md b/openframe-frontend-core/src/contexts/.chat-runtime-context.md
index b7fca7042..530e6ee14 100644
--- a/openframe-frontend-core/src/contexts/.chat-runtime-context.md
+++ b/openframe-frontend-core/src/contexts/.chat-runtime-context.md
@@ -1,34 +1,33 @@
-<!-- source-hash: 246e5605bed712d2ecbfd71d23933d41 -->
-Provides the React context and typed interface that supply runtime configuration to the Flamingo/OpenFrame chat panel, decoupling API endpoints, navigation behavior, and identity source from the host environment.
+<!-- source-hash: c1dda72c4995f6cbb7b1e2ccf9251518 -->
+Provides a React context for configuring the chat panel's API endpoints, navigation behavior, and identity settings across different host environments (hub vs. embedded apps).
 
 ## Key Components
 
 ### `ChatRuntime` Interface
-The central config shape with three top-level concerns:
+The primary configuration shape with four top-level concerns:
 
-| Field | Description |
-|---|---|
-| `endpoints` | All API URLs: streaming chat, agent approval, slash-commands, attachment upload/view, identity, and optional image proxy |
-| `navigation` | Mode (`'host'` or `'embed'`), external URL handler, in-app router callback, and new-tab decision logic |
-| `source` | Required string used for `localStorage` namespacing (`mingo-chat-<source>-v1`) |
+- **`endpoints`** — All API URLs: `chatStreamUrl`, `approvalToolUrl`, `commandsUrl`, `buildListUrl`, attachment upload/view, identity, image proxy, and Supabase storage origin
+- **`navigation`** — Mode (`'host'` | `'embed'`), `defaultContentOrigin`, `openExternal`, `navigate`, and `decideNewTab` callbacks
+- **`resolvePlaceholderUrl`** — Optional OG placeholder URL builder
+- **`composeContentUrl`** — Optional platform-aware content href composer (single authority for all embeddable surfaces)
+- **`source`** — Optional platform identifier (hub only; embedders leave unset)
 
 ### `ChatRuntimeContext`
-Raw React context (`createContext<ChatRuntime | null>(null)`). Mount via `<ChatRuntimeContext.Provider value={...}>` at your tree root.
+A `React.createContext<ChatRuntime | null>(null)` — the single seam between host/embed environments and the chat panel internals.
 
 ### `useChatRuntime()`
-Nullable consumer hook. Returns `null` when no provider is mounted — signals unconfigured runtime. Use for optional/graceful-degradation consumers.
+Returns the active `ChatRuntime` or `null`. Null is a valid signal — optional consumers fall back to no-op behavior.
 
 ### `useRequiredChatRuntime()`
-Strict consumer hook used inside chat internals. Throws a descriptive error if called outside a provider. Use this inside the chat panel itself.
+Strict variant used inside the chat panel. Throws a descriptive error if called outside a provider, guiding developers to wrap with `<HubRuntimeProvider>` or a mock provider.
 
 ## Usage Example
 
 ```typescript
-// Host (hub) — already handled by <HubRuntimeProvider>
-// Embedded app — wire your own provider:
+// Hub: already handled by <HubRuntimeProvider>
 
+// Embedded app
 const runtime = useMemo<ChatRuntime>(() => ({
-  source: 'my-embedded-app',
   endpoints: {
     chatStreamUrl: 'https://hub.openframe.ai/api/docs/chat',
     approvalToolUrl: 'https://hub.openframe.ai/api/chat/agent/confirm-tool',
@@ -51,4 +50,4 @@ return (
 )
 ```
 
-> **Memoization is required.** Passing a new object reference on every render invalidates downstream `useMemo` consumers across the entire chat tree (slash-commands, nav links, stream factory). Always stabilize with `useMemo` and stable deps.
\ No newline at end of file
+> **Memoize the provider value.** Every reference change invalidates downstream `useMemo` consumers across the entire chat tree (slash-commands binding, `useNavLink`, `useDocChat` stream factory).
\ No newline at end of file
diff --git a/openframe-frontend-core/src/hooks/.use-self-fetch.md b/openframe-frontend-core/src/hooks/.use-self-fetch.md
new file mode 100644
index 000000000..2d9402409
--- /dev/null
+++ b/openframe-frontend-core/src/hooks/.use-self-fetch.md
@@ -0,0 +1,47 @@
+<!-- source-hash: 211938f100fcb337dd5db5dff5dea1ea -->
+A client-side data-fetching hook that GETs a URL into component state using plain `fetch` + `useEffect`, with no external query-client dependency. Designed as the single shared primitive for self-fetching content views (`ProductReleasesView`, `RoadmapView`, onboarding catalog/detail).
+
+## Key Components
+
+### `UseSelfFetchResult<T>` (interface)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `T \| null` | Fetched (or hydrated) payload |
+| `setData` | `Dispatch<SetStateAction<T \| null>>` | Imperative patch for optimistic updates |
+| `isLoading` | `boolean` | True while a fetch is in-flight |
+| `error` | `boolean` | True after a non-abort failure |
+| `reload` | `() => void` | Forces a retry of the current URL |
+
+### `useSelfFetch<T>(url, options?)` (hook)
+
+**Parameters:**
+- `url: string | null` — `null` disables fetching entirely (SSR/controlled mode)
+- `options.initialData?: T` — Hydrates state immediately and skips the first fetch; subsequent URL changes still re-fetch
+
+**Behaviour highlights:**
+- `url` is the cache key — all query params must be folded into it
+- Stale-response guard (`cancelled` flag + `AbortController`) prevents out-of-order writes
+- `dataUrlRef` comparison skips re-fetching SSR-hydrated data on mount, and survives React 18 StrictMode's double-invoke
+- `reload()` nulls `dataUrlRef` then bumps an internal `reloadKey` to force a retry of the same URL
+
+## Usage Example
+
+```typescript
+// Self-fetch mode (no SSR data)
+const { data, isLoading, error, reload } = useSelfFetch<Product[]>(
+  '/api/products?page=1'
+)
+
+// SSR-hydrated mode (skips first fetch, re-fetches on url change)
+const { data, setData } = useSelfFetch<RoadmapItem[]>(
+  `/api/roadmap?slug=${slug}`,
+  { initialData: serverData }
+)
+
+// Optimistic update
+setData((prev) => prev ? [...prev, newItem] : [newItem])
+
+// Disabled / controlled mode
+const { data } = useSelfFetch<Config>(null) // never fetches
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/hooks/ui/.use-auto-limit-tags.md b/openframe-frontend-core/src/hooks/ui/.use-auto-limit-tags.md
index 84324ac88..ce5c22a68 100644
--- a/openframe-frontend-core/src/hooks/ui/.use-auto-limit-tags.md
+++ b/openframe-frontend-core/src/hooks/ui/.use-auto-limit-tags.md
@@ -1,27 +1,27 @@
-<!-- source-hash: 4ddac380d848a0dcab830bec82a667f6 -->
-Calculates how many tags fit within a single-line container using real DOM measurements, supporting both a fixed numeric limit and an automatic layout-aware mode.
+<!-- source-hash: 3512572c1b5ae0dfa77abc80ec31167a -->
+Calculates how many tags fit in a single-line container using real DOM measurements, supporting both a fixed numeric limit and an automatic layout-based mode.
 
 ## Key Components
 
-### `useAutoLimitTags(options)`
-Main hook that returns layout refs and the computed `visibleCount`.
-
-**Options**
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `count` | `number` | — | Total number of tags |
-| `limitTags` | `number \| "auto"` | `"auto"` | Fixed cap or DOM-measured auto mode |
-| `placeholder` | `string` | `""` | Input placeholder used to reserve width |
-
-**Returns (`UseAutoLimitTagsReturn`)**
-| Ref | Element | Purpose |
-|---|---|---|
-| `middleRef` | `HTMLDivElement` | Container with tags + input (reads padding/gap from here) |
-| `measureRef` | `HTMLDivElement` | Off-screen container holding copies of all tags |
-| `textMeasureRef` | `HTMLSpanElement` | Hidden span measuring placeholder text width |
-| `badgeRef` | `HTMLButtonElement` | The `+N` overflow badge (measures its width) |
-| `inputRef` | `HTMLInputElement` | The text input (reads its `min-width`) |
-| `visibleCount` | `number` | How many tags to render visibly |
+**`UseAutoLimitTagsOptions`** — Configuration interface:
+- `count` — Total number of tags
+- `limitTags` — Fixed number or `"auto"` (default) for DOM-based measurement
+- `placeholder` — Text used to reserve input width in auto mode
+- `reserveInputWidth` — Whether to reserve trailing space for an autocomplete input (default `true`)
+
+**`UseAutoLimitTagsReturn`** — Returned refs and state:
+- `visibleCount` — Number of tags to render visibly
+- `middleRef` — Container div holding tags + input (must have `overflow-hidden`, `gap`, `padding`)
+- `measureRef` — Off-screen div holding measurement copies of all tags
+- `textMeasureRef` — Hidden `<span>` measuring placeholder text width
+- `badgeRef` — Ref to the `+N` overflow badge button
+- `inputRef` — Ref to the autocomplete input element
+
+**`useAutoLimitTags()`** — Core hook that:
+1. Reads real CSS metrics (`padding`, `gap`, `clientWidth`) from the container
+2. Measures each tag's `offsetWidth` from the off-screen clone container
+3. Greedily fits tags left-to-right, reserving space for the `+N` badge when overflow occurs
+4. Re-runs on input changes and container resize via `ResizeObserver`
 
 ## Usage Example
 
@@ -29,26 +29,18 @@ Main hook that returns layout refs and the computed `visibleCount`.
 const { visibleCount, middleRef, measureRef, textMeasureRef, badgeRef, inputRef } =
   useAutoLimitTags({ count: tags.length, placeholder: "Search..." })
 
-return (
-  <>
-    {/* Off-screen measurement container */}
-    <div ref={measureRef} style={{ position: "absolute", visibility: "hidden" }}>
-      {tags.map((tag) => <TagChip key={tag.id} tag={tag} />)}
-    </div>
-    <span ref={textMeasureRef} style={{ visibility: "hidden", position: "absolute" }}>
-      Search...
-    </span>
-
-    {/* Visible tag zone */}
-    <div ref={middleRef} className="flex overflow-hidden gap-1 px-2">
-      {tags.slice(0, visibleCount).map((tag) => <TagChip key={tag.id} tag={tag} />)}
-      {visibleCount < tags.length && (
-        <button ref={badgeRef}>+{tags.length - visibleCount}</button>
-      )}
-      <input ref={inputRef} placeholder="Search..." />
-    </div>
-  </>
-)
-```
-
-> **Note:** `middleRef` must have `overflow-hidden`, explicit `gap`, and `padding` set via CSS — the hook reads these values directly with `getComputedStyle` and uses a `ResizeObserver` to recalculate on container width changes.
\ No newline at end of file
+// Render container
+<div ref={middleRef} className="flex overflow-hidden gap-2 px-3">
+  {tags.slice(0, visibleCount).map(tag => <Chip key={tag.id} label={tag.name} />)}
+  {visibleCount < tags.length && (
+    <button ref={badgeRef}>+{tags.length - visibleCount}</button>
+  )}
+  <input ref={inputRef} placeholder="Search..." />
+</div>
+
+// Off-screen measurement container (hidden)
+<div ref={measureRef} className="absolute invisible flex gap-2">
+  {tags.map(tag => <Chip key={tag.id} label={tag.name} />)}
+</div>
+<span ref={textMeasureRef} className="absolute invisible whitespace-pre">Search...</span>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/nats/.index.md b/openframe-frontend-core/src/nats/.index.md
new file mode 100644
index 000000000..24a756e93
--- /dev/null
+++ b/openframe-frontend-core/src/nats/.index.md
@@ -0,0 +1,27 @@
+<!-- source-hash: c277685d024b3565e47f9f7688345fba -->
+Barrel export file that re-exports all public APIs from the NATS messaging module.
+
+## Key Components
+
+| Export Source | Description |
+|---|---|
+| `./nats` | Core NATS client utilities and types |
+| `./shared-connection` | Shared NATS connection management |
+| `./nats-provider` | React/Vue provider for NATS context |
+| `./use-nats-subscription` | Composable/hook for subscribing to NATS subjects |
+
+## Usage Example
+
+```typescript
+// Import anything from the NATS module via this single entry point
+import {
+  NatsProvider,
+  useNatsSubscription,
+  SharedConnection,
+} from '@flamingo/nats'
+
+// Subscribe to a NATS subject
+const { messages } = useNatsSubscription('tickets.>')
+```
+
+> All sub-modules are accessible through this single entry point, keeping imports clean across the codebase.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/nats/.nats-provider.md b/openframe-frontend-core/src/nats/.nats-provider.md
new file mode 100644
index 000000000..fa7ed6b28
--- /dev/null
+++ b/openframe-frontend-core/src/nats/.nats-provider.md
@@ -0,0 +1,55 @@
+<!-- source-hash: d82fa0e9089cd3b3be6e0615e463558b -->
+React context provider that manages a shared NATS WebSocket connection lifecycle, exposing connection state and client access to child components via context hooks.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `NatsProvider` | Component | Root provider managing connection lifecycle, reconnection backoff, and status tracking |
+| `useNats` | Hook | Returns `NatsContextValue`; throws if used outside `<NatsProvider>` |
+| `useOptionalNats` | Hook | Returns `NatsContextValue | null`; safe to call outside provider |
+| `NatsProviderProps` | Interface | Provider configuration including `getWsUrl`, `onBeforeReconnect`, `clientConfig`, `reconnectionBackoff`, `urlRevision` |
+| `NatsContextValue` | Interface | `{ client, status, isReady, reconnectionCount }` consumed by hooks |
+
+## Usage Example
+
+```typescript
+// 1. Wrap your app (or subtree) with NatsProvider
+function App() {
+  const { token } = useAuth()
+
+  return (
+    <NatsProvider
+      getWsUrl={() => token ? `wss://nats.example.com?token=${token}` : null}
+      onBeforeReconnect={async () => await refreshToken()}
+      reconnectionBackoff={{ initialMs: 500, maxMs: 30_000 }}
+      urlRevision={token} // forces re-evaluation when auth changes
+    >
+      <Dashboard />
+    </NatsProvider>
+  )
+}
+
+// 2. Consume in child components
+function Dashboard() {
+  const { client, isReady, status, reconnectionCount } = useNats()
+
+  if (!isReady) return <p>Connecting… ({status})</p>
+
+  return <p>Connected — reconnections: {reconnectionCount}</p>
+}
+
+// 3. Optional access (no throw outside provider)
+function MaybeSubscriber() {
+  const nats = useOptionalNats()
+  if (!nats?.isReady) return null
+  return <Subscriber client={nats.client} />
+}
+```
+
+## Notes
+
+- **URL laziness** — `getWsUrl()` returning `null` cleanly tears down any existing connection without error.
+- **`urlRevision` prop** — increment or change this value (e.g. pass the auth token itself) to trigger URL re-evaluation; the provider does not watch external auth state on its own.
+- **Shared connections** — delegates to `acquireClient` / `releaseClient` from `shared-connection`, so multiple provider instances pointing at the same URL share a single underlying connection.
+- All callback refs (`getWsUrl`, `onBeforeReconnect`, `reconnectionBackoff`) are kept in refs to avoid restarting the connection lifecycle on every render.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/nats/.nats.md b/openframe-frontend-core/src/nats/.nats.md
index 55a17a753..66627787f 100644
--- a/openframe-frontend-core/src/nats/.nats.md
+++ b/openframe-frontend-core/src/nats/.nats.md
@@ -1,25 +1,22 @@
-<!-- source-hash: 418321f518535eef27f0004848e1e1b3 -->
-A browser/Tauri-only NATS client factory for WebSocket-based NATS connections (`nats.ws`), providing typed pub/sub, request/reply, JetStream ordered consumer subscriptions, and connection lifecycle management.
+<!-- source-hash: 3c70c9787b187c39d0a52375ca9a46e1 -->
+A browser/WebSocket NATS client abstraction built on `nats.ws`, providing typed publish/subscribe, request/reply, JetStream ordered consumer support, and connection lifecycle management with exponential backoff reconnection.
 
 ## Key Components
 
 ### Interfaces & Types
-| Export | Description |
-|--------|-------------|
-| `NatsClient` | Core client interface with all pub/sub/request/JetStream methods |
-| `NatsClientOptions` | Connection config: servers, auth, reconnect, exponential backoff, ping |
-| `NatsSubscribeOptions` | Per-subscription options: queue group, max messages, abort signal |
-| `NatsPublishOptions` / `NatsRequestOptions` | Optional headers and timeout per operation |
-| `JetStreamOrderedSubscribeOptions` | JetStream ephemeral consumer config: stream, filter, deliver policy, start sequence |
-| `NatsStatus` / `NatsStatusEvent` | Connection state machine: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
+- **`NatsClient`** — Main client interface with publish, subscribe, request/reply, JetStream, and status methods
+- **`NatsClientOptions`** — Connection configuration including servers, auth, reconnect behavior, and exponential backoff
+- **`JetStreamOrderedSubscribeOptions`** — Options for ephemeral JetStream ordered consumer subscriptions
+- **`NatsStatusEvent`** / **`NatsStatus`** — Connection lifecycle event types (`connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error`)
+- **`NatsSubscribeOptions`** / **`NatsPublishOptions`** / **`NatsRequestOptions`** — Per-operation options
 
 ### Factory Function
-- **`createNatsClient(options)`** — Returns a `NatsClient` instance. Lazily imports `nats.ws` (browser-safe). All methods are lazy-connected and browser-only (throws if `window` is undefined).
+- **`createNatsClient(options)`** — Returns a `NatsClient` instance; lazily imports `nats.ws` (browser/Tauri only, throws if `window` is undefined)
 
-### Internal Helpers
-- **`createExponentialBackoffHandler`** — Configurable exponential backoff with optional crypto jitter for reconnect delays.
-- **`toNatsHeaders`** — Converts `Record<string, string>` or native `NatsHeaders` into a `nats.ws` headers object.
-- **`mapNatsTypeToStatus`** — Normalizes raw `nats.ws` status events to the typed `NatsStatus` union.
+### Internal Utilities
+- **`createExponentialBackoffHandler`** — Configurable backoff with optional jitter using `crypto.getRandomValues`
+- **`toNatsHeaders`** — Converts `Record<string, string>` or existing `NatsHeaders` into a `nats.ws` headers object
+- **`mapNatsTypeToStatus`** — Normalizes raw `nats.ws` status strings to `NatsStatus` values
 
 ## Usage Example
 
@@ -28,36 +25,36 @@ import { createNatsClient } from './nats'
 
 const client = createNatsClient({
   servers: 'wss://nats.example.com:443',
-  name: 'flamingo-ui',
-  token: 'my-token',
+  name: 'my-app',
+  token: 'secret-token',
   exponentialBackoff: {
-    initialDelayMs: 500,
-    maxDelayMs: 15_000,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
     multiplier: 2,
     jitter: true,
   },
 })
 
 // Listen for connection status changes
-const off = client.onStatus((event) => {
+client.onStatus((event) => {
   console.log('NATS status:', event.status)
 })
 
 await client.connect()
 
-// Typed JSON publish
-client.publishJson('telemetry.events', { deviceId: 'abc', value: 42 })
+// Publish & subscribe JSON
+client.publishJson('events.created', { id: 1, name: 'test' })
 
-// Typed JSON request/reply
-const response = await client.requestJson<{ ok: boolean }>(
-  'devices.query',
-  { id: 'abc' },
-  { timeoutMs: 3000 },
-)
+client.subscribeJson<{ id: number; name: string }>('events.created', (payload) => {
+  console.log('Received:', payload)
+})
+
+// Request/reply
+const response = await client.requestJson<{ ok: boolean }>('rpc.ping', {})
 
 // JetStream ordered consumer (live-tail)
 const handle = await client.subscribeJetStreamOrdered(
-  (msg) => console.log('JetStream msg:', msg.seq),
+  (msg) => console.log('JetStream msg seq:', msg.seq),
   {
     streamName: 'EVENTS',
     filterSubject: 'events.>',
@@ -67,6 +64,7 @@ const handle = await client.subscribeJetStreamOrdered(
 
 // Cleanup
 handle.unsubscribe()
-off()
 await client.close()
-```
\ No newline at end of file
+```
+
+> **Note:** This client is browser/Tauri-only. Importing in a Next.js server bundle is safe, but calling `connect()` server-side will throw.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/nats/.shared-connection.md b/openframe-frontend-core/src/nats/.shared-connection.md
new file mode 100644
index 000000000..c33f649c2
--- /dev/null
+++ b/openframe-frontend-core/src/nats/.shared-connection.md
@@ -0,0 +1,38 @@
+<!-- source-hash: de660f5e8849d591b2c858d99d1d9921 -->
+Manages a singleton NATS WebSocket connection shared across multiple consumers, handling reference counting, deferred cleanup, and coordinated reconnection with exponential backoff.
+
+## Key Components
+
+**`NATS_DEFAULTS`** — Compile-time constants for timeouts, ping intervals, and retry backoff parameters.
+
+**`SharedConnection`** — Interface representing the singleton connection state, including the `NatsClient`, `refCount`, deferred close/retry timers, and `retryOwner` (prevents multiple consumers racing to reconnect simultaneously).
+
+**`acquireClient(url, opts?)`** — Increments `refCount` and returns the shared connection, creating a new one if the URL differs. Cancels any pending deferred close on re-acquire.
+
+**`releaseClient(url, opts?)`** — Decrements `refCount` and schedules a deferred `close()` (default 3s) when the last consumer releases, allowing fast re-acquisition without a full reconnect cycle.
+
+**`getSharedConnection()` / `getSharedConnectionFor(url)`** — Accessors for the current singleton, useful for status checks without affecting the ref count.
+
+**`startConnectionLifecycle(options)`** — Attaches a status observer and retry loop to a shared connection. The first caller claims `retryOwner` and drives reconnect; subsequent callers observe only, preventing concurrent connect races. Returns a `stop()` handle to unsubscribe and release ownership.
+
+**`NatsReconnectionBackoff`** — Configures the retry strategy: optional fast-retry phase (fixed delay) followed by a jittered exponential backoff capped at `maxDelayMs`.
+
+## Usage Example
+
+```typescript
+import { acquireClient, releaseClient, startConnectionLifecycle } from './shared-connection'
+
+const conn = acquireClient('wss://nats.example.com')
+
+const lifecycle = startConnectionLifecycle({
+  conn,
+  wsUrl: 'wss://nats.example.com',
+  getFreshUrl: () => 'wss://nats.example.com',
+  backoff: { fastRetries: 2, fastRetryDelayMs: 500, maxDelayMs: 15_000 },
+  onStatusChange: (status) => console.log('NATS status:', status),
+})
+
+// On teardown:
+lifecycle.stop()
+releaseClient('wss://nats.example.com')
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/nats/.use-nats-subscription.md b/openframe-frontend-core/src/nats/.use-nats-subscription.md
new file mode 100644
index 000000000..6c5df3b90
--- /dev/null
+++ b/openframe-frontend-core/src/nats/.use-nats-subscription.md
@@ -0,0 +1,41 @@
+<!-- source-hash: ec30097feafd8e14e66c0760d7da51a3 -->
+React hooks for subscribing to NATS subjects using the shared connection from `NatsProvider`. Provides both raw byte and JSON-decoded subscription variants with automatic re-subscription on reconnection.
+
+## Key Components
+
+- **`useNatsSubscription`** — Core hook that subscribes to a NATS subject, accepting raw `Msg` callbacks. Automatically resubscribes when the subject changes, the connection becomes ready, or a reconnection occurs.
+- **`useNatsJsonSubscription`** — Wrapper around `useNatsSubscription` that decodes incoming byte payloads as JSON before invoking the callback. Silently ignores malformed messages.
+- **`UseNatsSubscriptionOptions`** — Extends `NatsSubscribeOptions` with an `enabled` flag to conditionally pause subscriptions.
+- **`UseNatsSubscriptionReturn`** — Returns `isSubscribed` (active subscription state) and `isReady` (underlying NATS connection readiness).
+
+## Usage Example
+
+```typescript
+// Raw bytes subscription
+function MyComponent() {
+  const { isSubscribed } = useNatsSubscription(
+    'events.alerts',
+    (msg) => console.log('Received:', msg.data),
+    { enabled: true, queue: 'workers' }
+  )
+  return <span>{isSubscribed ? 'Listening' : 'Disconnected'}</span>
+}
+
+// JSON subscription with typed payload
+interface AlertPayload {
+  level: 'info' | 'warn' | 'error'
+  message: string
+}
+
+function AlertListener() {
+  const { isSubscribed, isReady } = useNatsJsonSubscription<AlertPayload>(
+    'events.alerts',
+    (payload, msg) => {
+      console.log(`[${payload.level}] ${payload.message}`)
+    },
+    { enabled: isReady }
+  )
+}
+```
+
+> **Note:** Both hooks use a stable `handlerRef` to avoid resubscribing when only the callback reference changes. Pass `enabled: false` or `subject: null` to cleanly unsubscribe.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ActionsMenu.stories.md b/openframe-frontend-core/src/stories/.ActionsMenu.stories.md
new file mode 100644
index 000000000..ab1bae6df
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.ActionsMenu.stories.md
@@ -0,0 +1,50 @@
+<!-- source-hash: 42e64113d86d5eae0ead175437c52358 -->
+Storybook stories for the `ActionsMenu` and `ActionsMenuDropdown` UI components, covering all supported item variants and interaction patterns.
+
+## Key Components
+
+- **`Default`** — Single group with icon-labeled action items
+- **`GroupedWithDanger`** — Multi-group layout with a separator and a destructive (danger) delete row
+- **`WithCheckboxes`** — Toggle-style items that maintain a `checked` state without closing the menu
+- **`WithSubmenu`** — Nested submenu via `ActionsMenuDropdown` (requires Radix DropdownMenu context)
+- **`WithDisabledItem`** — Demonstrates dimmed, non-interactive row behavior
+- **`WithSecondaryAction`** — Row with an independent secondary icon button (e.g., "open in new tab")
+- **`Dropdown`** — Full `ActionsMenuDropdown` attached to a default ellipsis trigger
+
+## Usage Example
+
+```typescript
+import { ActionsMenu, ActionsMenuDropdown } from '../components/ui/actions-menu';
+import { PencilIcon, TrashBlankIcon } from '../components/icons-v2-generated';
+
+// Inline panel
+<ActionsMenu
+  groups={[
+    {
+      id: 'primary',
+      separator: true,
+      items: [
+        { id: 'edit', label: 'Edit', icon: <PencilIcon />, onClick: () => {} },
+      ],
+    },
+    {
+      id: 'destructive',
+      items: [
+        { id: 'delete', label: 'Delete', icon: <TrashBlankIcon />, danger: true, onClick: () => {} },
+      ],
+    },
+  ]}
+/>
+
+// Dropdown (attaches to a trigger button)
+<ActionsMenuDropdown
+  groups={groups}
+  onItemClick={(id) => console.log(id)}
+/>
+```
+
+## Notes
+
+- Use `ActionsMenu` to render the panel inline; use `ActionsMenuDropdown` to attach it to a trigger
+- Submenus require `ActionsMenuDropdown` — they depend on the Radix DropdownMenu context
+- `iconAction` on a row renders a separate 40px button on the right with its own `href` or `onClick`
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.AppLayoutDrawer.stories.md b/openframe-frontend-core/src/stories/.AppLayoutDrawer.stories.md
new file mode 100644
index 000000000..1c0030c30
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.AppLayoutDrawer.stories.md
@@ -0,0 +1,55 @@
+<!-- source-hash: eb65307855df2f5b364327378b10b165 -->
+Storybook stories for `AppLayoutDrawer`, demonstrating an in-layout drawer component that renders within `AppLayout`'s main content area without covering the sidebar or header.
+
+## Key Components
+
+- **`Right`** — Default right-side drawer; persistent (only closes via X button or Escape, not by clicking app chrome)
+- **`ResizableRight`** — Right-side drawer with drag-to-resize handle; clamped to the main content area bounds, opens by default
+- **`Left`** — Left-side drawer variant, suitable for filters or secondary navigation panels
+
+## Usage Example
+
+```typescript
+import { useState } from 'react'
+import {
+  AppLayout,
+  AppLayoutDrawer,
+  AppLayoutDrawerBody,
+  AppLayoutDrawerContent,
+  AppLayoutDrawerHeader,
+  AppLayoutDrawerTitle,
+} from '../components/navigation'
+
+function MyPage() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <AppLayout
+      sidebarConfig={{ items: navigationItems, onNavigate: () => {} }}
+      drawer={
+        <AppLayoutDrawer open={open} onOpenChange={setOpen}>
+          {/* Resizable right-side panel */}
+          <AppLayoutDrawerContent
+            side="right"
+            resizable
+            minSize={360}
+            defaultSize={560}
+            storageKey="my-app:drawer:right"
+          >
+            <AppLayoutDrawerHeader>
+              <AppLayoutDrawerTitle>Chat</AppLayoutDrawerTitle>
+            </AppLayoutDrawerHeader>
+            <AppLayoutDrawerBody>
+              <p>Panel content here.</p>
+            </AppLayoutDrawerBody>
+          </AppLayoutDrawerContent>
+        </AppLayoutDrawer>
+      }
+    >
+      <button onClick={() => setOpen(true)}>Open Drawer</button>
+    </AppLayout>
+  )
+}
+```
+
+> **Note:** Use `AppLayoutDrawer` for page-scoped panels (chat, details, filters). For app-level overlays that should cover the full viewport (e.g. auth modals, notifications), use the standard `Drawer` from `components/ui` instead.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.AppLayoutSidebar.stories.md b/openframe-frontend-core/src/stories/.AppLayoutSidebar.stories.md
new file mode 100644
index 000000000..610bb07bb
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.AppLayoutSidebar.stories.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 99e6880161138f9d238720bc80b322d2 -->
+Storybook stories for the `AppLayoutSidebar` component, demonstrating how `AppLayout` integrates with `AppLayoutDrawer` to render a toggleable Mingo AI chat sidebar within the main content area.
+
+## Key Components
+
+- **`Default`** — Story showing the Mingo AI header button toggling a right-side `AppLayoutDrawer`; navigation sidebar and header remain interactive while the drawer is open
+- **`Resizable`** — Story demonstrating a draggable/resizable chat sidebar with configurable `minSize`, `defaultSize`, and `storageKey` persistence; starts open by default
+- **`DashboardChildren`** — Internal helper component rendering a mock dashboard with device stats and a prompt to open the Mingo AI panel
+- **`navigationItems`** — Shared `NavigationSidebarConfig` fixture with Dashboard, Customers, Devices, Scripts, and Settings entries
+
+## Usage Example
+
+```typescript
+// Default: toggle Mingo AI sidebar via header button
+const [open, setOpen] = useState(false)
+
+<AppLayout
+  sidebarConfig={{ items: navigationItems, onNavigate: fn() }}
+  headerProps={{
+    showMingoAI: true,
+    onMingoAI: () => setOpen((prev) => !prev),
+    isMingoAIActive: open,
+  }}
+  drawer={
+    <AppLayoutDrawer open={open} onOpenChange={setOpen}>
+      <AppLayoutDrawerContent side="right">
+        <AppLayoutDrawerHeader>
+          <AppLayoutDrawerTitle>Mingo AI</AppLayoutDrawerTitle>
+        </AppLayoutDrawerHeader>
+        <AppLayoutDrawerBody>Chat content here.</AppLayoutDrawerBody>
+      </AppLayoutDrawerContent>
+    </AppLayoutDrawer>
+  }
+>
+  <DashboardContent />
+</AppLayout>
+
+// Resizable variant — add resizable props to AppLayoutDrawerContent
+<AppLayoutDrawerContent
+  side="right"
+  resizable
+  minSize={360}
+  defaultSize={560}
+  storageKey="app:mingo-sidebar"
+/>
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.BlogCard.stories.md b/openframe-frontend-core/src/stories/.BlogCard.stories.md
new file mode 100644
index 000000000..cb02080e1
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.BlogCard.stories.md
@@ -0,0 +1,45 @@
+<!-- source-hash: f25255e37142438b85c6b2df6de4a52f -->
+Storybook stories for the `BlogCard` entity card component, covering both compact chat-inline (`sm`) and full vertical catalog (`default`) display densities.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `meta` | Storybook metadata — registers `BlogCard` under `Chat/EntityCards/BlogCard`, wraps stories in `ChatColumnDecorator` |
+| `ChatInlineSm` | Compact horizontal card (~80px tall) used inline in chat responses |
+| `ChatInlineWithVideoBadge` | `sm` variant with `hasEmbeddedVideo: true` to render the video badge overlay |
+| `Default` | Full vertical catalog card used in related-content rails (not dispatched inline in chat) |
+
+## Usage Example
+
+```typescript
+// Render the compact chat-inline card
+<BlogCard
+  post={blogPostSummary}
+  href={`/blog/${blogPostSummary.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Render the full catalog card with video badge
+<BlogCard
+  post={blogPostSummary}
+  href={`/blog/${blogPostSummary.slug}`}
+  size="sm"
+  hasEmbeddedVideo={true}
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Full vertical card for related-content rail
+<BlogCard
+  post={blogPostSummary}
+  href={`/blog/${blogPostSummary.slug}`}
+  size="default"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+> **Note:** The card renders its own `<a>` tag internally. Callers are responsible for resolving the `href` value via `buildContentURL` or `useNavLink` before passing it as a prop.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.Board.stories.md b/openframe-frontend-core/src/stories/.Board.stories.md
index df3f40e4e..6349ed19a 100644
--- a/openframe-frontend-core/src/stories/.Board.stories.md
+++ b/openframe-frontend-core/src/stories/.Board.stories.md
@@ -1,35 +1,39 @@
-<!-- source-hash: eded9627e041539da9106ebd71cd1d56 -->
-Storybook stories for the `Board` component, demonstrating all major configuration variants including drag-and-drop, column types, pagination, loading states, and collapse behavior.
+<!-- source-hash: 8939b0ce480239cfb76e028389e4824d -->
+Storybook stories for the `Board` component, covering drag-and-drop kanban board layouts with various column configurations, loading states, pagination, and collapse behavior.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `Default` | Five canonical ticket-status columns with seeded tickets and full drag-and-drop wired up |
-| `SystemAndCustom` | Mixed system and custom columns mirroring the OpenFrame Tickets layout, with DnD restrictions |
-| `CustomColumns` | Fully custom columns proving column color is decoupled from `TicketStatus` |
-| `Collapsible` | Columns with collapse toggle persisted to `localStorage` via `collapseStorageKey` |
-| `Pagination` | Demonstrates `onLoadMore` with a 600ms simulated delay, appending 10 tickets per page from a pool of 50 |
-| `InitialLoading` | All columns start in `isLoading` skeleton state, resolving to seeded data after 1 second |
-| `Empty` | Empty columns to verify the drop placeholder render |
-
-**Helpers used internally:**
-
-- `buildSeedColumns()` — generates five default status columns with varied ticket data
-- `applyChange()` — immutably applies a `BoardChange` (move/reorder) to the column state
+- **`Default`** — Five canonical ticket-status columns (`ACTIVE`, `TECH_REQUIRED`, `ON_HOLD`, `RESOLVED`, `ARCHIVED`) with full DnD wired up
+- **`SystemAndCustom`** — Mixed system + custom columns matching the OpenFrame Tickets layout; AI-Assistance blocks drops, Resolved tickets are drag-disabled
+- **`CustomColumns`** — Fully custom columns (`Backlog`, `In Review`, `Blocked`, `Done`), demonstrating column color is decoupled from `TicketStatus`
+- **`Collapsible`** — Column collapse toggle that persists via `localStorage` using `collapseStorageKey`
+- **`Pagination`** — Single column starts with 10 of 50 tickets; `onLoadMore` appends 10 more after a 600ms simulated delay
+- **`InitialLoading`** — All columns render skeleton/loading state, resolving to seeded data after 1 second
+- **`Empty`** — Empty columns to verify the drop placeholder UI
 
 ## Usage Example
 
 ```typescript
-// Minimal interactive board with DnD and immutable state update
+// Minimal interactive board with immutable change handling
 const [columns, setColumns] = React.useState(buildSeedColumns())
 
+function applyChange(columns: BoardColumnDef[], change: BoardChange): BoardColumnDef[] {
+  const next = columns.map(c => ({ ...c, tickets: [...c.tickets] }))
+  const fromCol = next.find(c => c.id === change.fromColumnId)
+  const toCol   = next.find(c => c.id === change.toColumnId)
+  if (!fromCol || !toCol) return columns
+
+  const [moved] = fromCol.tickets.splice(
+    fromCol.tickets.findIndex(t => t.id === change.ticketId), 1
+  )
+  toCol.tickets.splice(0, 0, moved)
+  return next
+}
+
 <Board
   columns={columns}
-  onChange={change => setColumns(prev => applyChange(prev, change))}
-  onTicketClick={id => console.log('clicked', id)}
+  onChange={c => setColumns(prev => applyChange(prev, c))}
+  getTicketHref={id => `/tickets/${id}`}
   onAddTicket={colId => console.log('add to', colId)}
-  collapseStorageKey="my-board-collapse"
-  onLoadMore={columnId => fetchNextPage(columnId)}
 />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.CampaignCardAdmin.stories.md b/openframe-frontend-core/src/stories/.CampaignCardAdmin.stories.md
new file mode 100644
index 000000000..c1a68dcd7
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.CampaignCardAdmin.stories.md
@@ -0,0 +1,36 @@
+<!-- source-hash: 62d0fd5af004b0935685d20d4d932ddc -->
+Storybook stories for the `CampaignCardAdmin` chat-inline entity card, covering default display and edge cases where optional campaign fields are absent.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Default` | `Story` | Full campaign card with name, start date, goal count, and description |
+| `NoDescription` | `Story` | Card rendered when `description` is `null` |
+| `NoGoals` | `Story` | Card rendered when `goals` is an empty array |
+
+## Usage Example
+
+```typescript
+import { CampaignCardAdmin } from '../components/chat/entity-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+import { campaignItem } from './__fixtures__/chat-cards'
+
+// Minimal usage
+<CampaignCardAdmin
+  campaign={campaignItem}
+  anchorProps={makeAnchorProps('/admin/campaigns/' + campaignItem.id)}
+/>
+
+// With missing optional fields
+<CampaignCardAdmin
+  campaign={{ ...campaignItem, description: null, goals: [] }}
+  anchorProps={makeAnchorProps('/admin/campaigns/' + campaignItem.id)}
+/>
+```
+
+## Notes
+
+- All stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
+- This card is the **chat-only projection** of the `marketing_campaign` doc type — the full admin card with delete/manage actions lives in the hub.
+- Displayed fields: campaign name, start date, goal count, and a one-line description.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.CaseStudyCard.stories.md b/openframe-frontend-core/src/stories/.CaseStudyCard.stories.md
new file mode 100644
index 000000000..e1b405233
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.CaseStudyCard.stories.md
@@ -0,0 +1,38 @@
+<!-- source-hash: 75ac7c181bdd6e2ff693703757ed5c57 -->
+Storybook stories for the `CaseStudyCard` component, covering both inline chat (`sm`) and catalog grid (`default`) size variants.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `meta` | `Meta<CaseStudyCard>` | Storybook metadata — registers component under `Chat/EntityCards/CaseStudyCard` with `fullscreen` layout |
+| `ChatInlineSm` | `Story` | Compact card variant used inline within chat messages (`size: 'sm'`) |
+| `Default` | `Story` | Full catalog grid card variant (`size: 'default'`) |
+
+## Usage Example
+
+```typescript
+// Render the compact chat-inline variant
+<CaseStudyCard
+  study={caseStudy}
+  href={`/case-studies/${caseStudy.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Render the catalog grid variant
+<CaseStudyCard
+  study={caseStudy}
+  href={`/case-studies/${caseStudy.slug}`}
+  size="default"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Notes
+
+- Both stories share the same `caseStudy` fixture from `__fixtures__/chat-cards` and are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
+- The `sm` size renders a compact inline card; `default` renders the full catalog grid card — both display the user + MSP badge overlay.
+- Component lives at `Chat/EntityCards/CaseStudyCard` in the Storybook hierarchy.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ChatContainer.stories.md b/openframe-frontend-core/src/stories/.ChatContainer.stories.md
new file mode 100644
index 000000000..fe5de43bb
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.ChatContainer.stories.md
@@ -0,0 +1,43 @@
+<!-- source-hash: 70ec7f7883bd65ea9a20c5edf8dd8cc8 -->
+Storybook stories for the `ChatContainer` component, demonstrating the Fae client-facing chat shell across four layout and feature variants.
+
+## Key Components
+
+- **`FaeChatShell`** — Interactive story shell that wires up controlled state for `ChatInput` and `ChatMessageList`, allowing message sending (user bubbles only, no assistant reply transport)
+- **`FAE_MESSAGES`** — Mock conversation seed data simulating a Fae/client printer-support exchange
+- **`Fae`** — Default story: standard centered layout with Fae persona header
+- **`FaeWithTicket`** — Story with `ticketInfo` populated on the header, showing active ticket title, meta, and status badge
+- **`FaeFullWidth`** — Full-width variant for narrow side panels or slide-in drawers
+- **`FaeBareHeader`** — Headerless-chrome variant for embedding inside a host-supplied card or drawer
+
+## Usage Example
+
+```typescript
+// Render the default Fae chat shell in a story
+export const Fae: Story = {
+  render: () => <FaeChatShell />,
+}
+
+// With an active ticket displayed in the header
+export const FaeWithTicket: Story = {
+  render: () => <FaeChatShell withTicketInfo />,
+}
+
+// Full-width layout for narrow containers (mobile / drawer)
+export const FaeFullWidth: Story = {
+  render: () => <FaeChatShell fullWidth />,
+}
+
+// Bare header — no card chrome, flush with host container
+export const FaeBareHeader: Story = {
+  render: () => <FaeChatShell bare fullWidth />,
+}
+```
+
+### `FaeChatShell` Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `withTicketInfo` | `boolean` | `false` | Adds ticket title, meta, and status to the header |
+| `bare` | `boolean` | `false` | Removes card chrome (background, border, shadow) from the header |
+| `fullWidth` | `boolean` | `false` | Drops the centered 600px column constraint on header, messages, and footer |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ChatInlineVideoPill.stories.md b/openframe-frontend-core/src/stories/.ChatInlineVideoPill.stories.md
new file mode 100644
index 000000000..6a83316d6
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.ChatInlineVideoPill.stories.md
@@ -0,0 +1,24 @@
+<!-- source-hash: b79b2c8f9f7df800c6a753d097091a12 -->
+Storybook stories for `ChatInlineVideoPill`, an inline span component that renders a small video sentinel pill alongside markdown text in chat assistant turns.
+
+## Key Components
+
+- **`ChatInlineVideoPill`** — Local re-implementation of the `video` doc-type inline pill from `dispatch.tsx` (lines 318–326). Renders a `▶` icon + truncated title in a bordered pill; stays inline within paragraph text rather than breaking into a card.
+- **`Default`** — Baseline story with a short video title rendered mid-sentence.
+- **`LongTitleTruncates`** — Verifies that long titles truncate cleanly (`max-w-[220px]`) without wrapping adjacent paragraph text.
+
+## Usage Example
+
+```typescript
+// Matches the source component in dispatch.tsx
+<ChatInlineVideoPill title="On-call rotation walkthrough" />
+
+// Renders as an inline span within a paragraph:
+// "Here is the demo from last week's call: [▶ On-call rotation walkthrough] — watch the part..."
+```
+
+## Notes
+
+- This pill is the **only entity card** designed to remain inline — all other entity cards use a card wrapper with Ask/Display affordances.
+- The actual video player is **hoisted out** of the paragraph by the chat pre-scan pipeline and rendered above the assistant turn; this pill acts purely as a sentinel.
+- Wrapped with `ChatColumnDecorator` to simulate realistic chat column width constraints during story rendering.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ChatMingoInfoCards.stories.md b/openframe-frontend-core/src/stories/.ChatMingoInfoCards.stories.md
new file mode 100644
index 000000000..21d86ed93
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.ChatMingoInfoCards.stories.md
@@ -0,0 +1,29 @@
+<!-- source-hash: 72bc4b44eb59f863ebc8b29a59c67d77 -->
+Storybook stories file that documents and renders visual variants of `MingoInfoCard` as in-chat entity cards, mirroring the field mappings (icon, status pill, description, overflow menu) from the `CHAT_CARD_REGISTRY` dispatch without requiring the chat runtime.
+
+## Key Components
+
+- **`meta`** — Storybook `Meta` config registering stories under `Chat/ChatMingoInfoCards`, with `fullscreen` layout and `ChatColumnDecorator` wrapping all stories to replicate chat column width/background
+- **`openMenu(href, openDetails?)`** — Shared overflow menu factory producing the standard "Ask Mingo" + "Open Details" (with ↗ new-tab side button) menu group used across all card stories
+- **`HubspotTicket`** — Story covering `hubspot_ticket` registry types; renders four card states (Open → amber, Closed → green, Waiting → grey, no status)
+- **`GithubActivity`** — Story covering `github_commit`, `github_pull_request`, and `github_pr_review` types; demonstrates per-kind icons and review state pills (Approved → green, Changes → red, Comment → grey)
+- **`SlackMessage`** — Story covering `slack_message`; no status pill, author+channel title format, message preview as description
+
+## Usage Example
+
+```typescript
+// All stories use the shared openMenu helper and makeAnchorProps fixture
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+
+<MingoInfoCard
+  title="fix(auth): guard SSO redirect"
+  description="a1b2c3d · May 28, 2026"
+  icon={<CodingCommitIcon size={24} />}
+  status={{ label: 'Commit', variant: 'grey' }}
+  anchorProps={makeAnchorProps('https://github.com/...')}
+  menuGroups={openMenu('https://github.com/...')}
+  menuAriaLabel="Activity actions"
+/>
+```
+
+> Each story's `render` function directly reproduces the icon/status/description mapping from `entity-cards/dispatch.tsx`, so visual regressions in card appearance are caught in Storybook before touching the chat runtime.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ChatTicketList.stories.md b/openframe-frontend-core/src/stories/.ChatTicketList.stories.md
index b6747a0e2..6b25bd97b 100644
--- a/openframe-frontend-core/src/stories/.ChatTicketList.stories.md
+++ b/openframe-frontend-core/src/stories/.ChatTicketList.stories.md
@@ -1,33 +1,32 @@
-<!-- source-hash: 995995dfe9715311703dcbbfc0fbba0b -->
-Storybook stories for the `ChatTicketList` component, providing visual test cases across different ticket counts, statuses, and scroll/fade behaviors.
+<!-- source-hash: 247fd4575e4d9ddc493d6b5ac63537e9 -->
+Storybook stories for the `ChatTicketList` component, providing visual test cases covering ticket list rendering across different data sets, ticket counts, and scroll/fade behaviors.
 
 ## Key Components
 
-- **`meta`** — Storybook metadata registering the component under `Chat/ChatTicketList` with autodocs and a `ticketClicked` action handler
-- **`mockTickets`** — 5-item fixture dataset covering all ticket statuses: `ACTIVE`, `ON_HOLD`, `TECH_REQUIRED`, and `RESOLVED`
-- **`manyTickets`** — 15-item extended dataset (includes `mockTickets`) for testing scroll and fade overflow scenarios
-- **`constrainedDecorator`** — Factory returning a story decorator that wraps the component in a max-width 600px container with an optional fixed height, used to simulate real layout constraints
+- **`meta`** — Storybook metadata registering `ChatTicketList` under the `Chat/ChatTicketList` title with `onTicketClick` action logging
+- **`mockTickets`** — Dataset of 5 tickets covering all status variants: `ACTIVE`, `ON_HOLD`, `TECH_REQUIRED`, and `RESOLVED`
+- **`manyTickets`** — Extended 15-ticket dataset for testing scroll and fade UI behavior
+- **`constrainedDecorator`** — Factory that wraps stories in a max-width 600px container with an optional fixed height to simulate real chat panel constraints
 
-## Exported Stories
+## Stories
 
 | Story | Description |
 |---|---|
 | `Default` | 5 tickets, unconstrained height |
-| `SingleTicket` | Only the first ticket rendered |
-| `AllStatuses` | First 4 tickets showing each distinct status |
-| `ScrollFading` | 15 tickets in a 400px container to demonstrate scroll fade |
-| `ScrollFadingCompact` | 15 tickets in a 280px container for more pronounced fade |
+| `SingleTicket` | Single ticket rendering |
+| `AllStatuses` | First 4 tickets showing all 4 status types |
+| `ScrollFading` | 15 tickets in a 400px container; tests top/bottom fade scroll indicators |
+| `ScrollFadingCompact` | 15 tickets in a 280px container; exaggerates fade visibility |
 
 ## Usage Example
 
 ```typescript
-// Replicate the ScrollFading story manually
-import { ChatTicketList } from "../components/chat/chat-ticket-list";
-
-<div style={{ maxWidth: 600, height: 400 }}>
-  <ChatTicketList
-    tickets={manyTickets}
-    onTicketClick={(ticket) => console.log(ticket)}
-  />
-</div>
+// Reuse mock data in other stories or tests
+import { Default, ScrollFading } from "./ChatTicketList.stories";
+
+// Render the default list story
+<Default />
+
+// Simulate a constrained panel with scroll fading
+<ScrollFading />
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.CustomerInterviewCard.stories.md b/openframe-frontend-core/src/stories/.CustomerInterviewCard.stories.md
new file mode 100644
index 000000000..7c36a888b
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.CustomerInterviewCard.stories.md
@@ -0,0 +1,31 @@
+<!-- source-hash: fbb7728f24a18cda956623e4fa987806 -->
+Storybook stories for the `CustomerInterviewCard` component, covering both `sm` and `default` size variants within a chat column layout.
+
+## Key Components
+
+- **`meta`** — Storybook metadata registering the component under `Chat/EntityCards/CustomerInterviewCard` with fullscreen layout
+- **`ChatColumnDecorator`** — Wraps each story in a chat-column context to simulate real rendering environment
+- **`customerInterview`** — Shared fixture providing mock interview data for all stories
+- **`ChatInlineSm`** — Story rendering the card at `size: 'sm'` (inline/compact variant)
+- **`Default`** — Story rendering the card at `size: 'default'` (standard variant)
+
+## Usage Example
+
+```typescript
+// Render the CustomerInterviewCard in a story
+export const Default: Story = {
+  args: {
+    interview: customerInterview,
+    href: '/customer-interviews/' + customerInterview.slug,
+    size: 'default',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+}
+```
+
+## Notes
+
+- The `main_video_url` field on the interview fixture controls whether the play-button overlay appears on the card cover
+- Both stories open links in a new tab via `target: '_blank'` and `rel: 'noopener noreferrer'`
+- The User + MSP badge overlay renders in both `sm` and `default` sizes
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.DataRoomDocCard.stories.md b/openframe-frontend-core/src/stories/.DataRoomDocCard.stories.md
new file mode 100644
index 000000000..6e544a53f
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.DataRoomDocCard.stories.md
@@ -0,0 +1,35 @@
+<!-- source-hash: f7d4866713e90d4e1df564c5e131e04d -->
+Storybook stories for the `DataRoomDocCard` chat entity card component, covering both `data_room_doc` and `markdown` doc types rendered inline in a chat column layout.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `DataRoom` | `Story` | Card variant for data room documents with "Data room" badge |
+| `KnowledgeBaseMarkdown` | `Story` | Card variant for OpenFrame Docs markdown files with "OpenFrame Docs" badge |
+
+## Usage Example
+
+```typescript
+import { DataRoomDocCard } from '../components/chat/entity-cards'
+
+// badgeText is REQUIRED — resolved via SOURCE_LABELS_BY_TABLE in dispatch
+<DataRoomDocCard
+  item={dataRoomDocItem}
+  badgeText="Data room"
+  anchorProps={makeAnchorProps(dataRoomDocItem.url ?? '#')}
+/>
+
+// Markdown doc type — same component, different badge driven by sourceRepo
+<DataRoomDocCard
+  item={openframeDocsMarkdownItem}
+  badgeText="OpenFrame Docs"
+  anchorProps={makeAnchorProps(openframeDocsMarkdownItem.url ?? '#')}
+/>
+```
+
+## Notes
+
+- `sourceRepo` on the item drives the badge label (e.g. `"openframe-docs"` → `"OpenFrame Docs"`)
+- `badgeText` must be pre-resolved by the caller via `SOURCE_LABELS_BY_TABLE` before passing to the component — it is not derived internally
+- Both stories use `ChatColumnDecorator` to simulate the constrained chat column width context
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.DataTable.stories.md b/openframe-frontend-core/src/stories/.DataTable.stories.md
index 9dbcb5573..ac3cbcd6a 100644
--- a/openframe-frontend-core/src/stories/.DataTable.stories.md
+++ b/openframe-frontend-core/src/stories/.DataTable.stories.md
@@ -1,41 +1,41 @@
-<!-- source-hash: 4b92799da5c1a1952b02f5fb9273c343 -->
-Storybook showcase for the `DataTable` component, demonstrating all interactive features (sorting, filtering, row selection, column visibility, pagination, and row actions) using a mock device dataset built on TanStack Table.
+<!-- source-hash: 1418595ce659e1e4eb5d1f8bd779051a -->
+Storybook showcase for the `DataTable` component, demonstrating all interactive features (sorting, filtering, row selection, column visibility) built on TanStack Table with a card-row UI.
 
 ## Key Components
 
-- **`Basic`** — Minimal setup with data and columns; no extra state
-- **`WithSorting`** — Consumer-owned sort cycle with `DataTableSortState`, supporting server-side or in-memory sorting
-- **`useDataTable`** — Hook wrapping TanStack Table; accepts `data`, `columns`, and flags like `clientSideSorting` / `clientSideFiltering`
-- **`baseColumns()`** — Reusable `ColumnDef<Device>[]` factory shared across stories, with responsive `hideAt` breakpoints
-- **Cell renderers** — `StatusTag`, `OSBadge`, `OwnerCell`, `TagsCell`, `LoadCell`, `LastSeenCell` — composable display-only cells
-- **`multiSelectFilterFn`** — Column filter function for multi-value faceted filtering (OS, Status)
-- **`makeDevices(count, startId?)`** — Deterministic fake device data generator seeded by index
+- **`Basic`** — Minimal setup story: data + columns only, using `useDataTable` defaults
+- **`WithSorting`** — Consumer-controlled sort state with manual toggle cycle and client-side data sorting
+- **`baseColumns()`** — Reusable column factory covering hostname, IP, OS, status, owner, tags, CPU, memory, and last-seen
+- **Cell renderers** — `StatusTag`, `OSBadge`, `OwnerCell`, `TagsCell`, `LoadCell`, `LastSeenCell` — composable display components for each data type
+- **`makeDevices()`** — Deterministic fixture generator producing `Device[]` datasets of varying sizes (`DEVICES_6` through `DEVICES_50`)
 
 ## Usage Example
 
 ```typescript
-import { DataTable, useDataTable, type ColumnDef } from '@/components/ui/data-table'
-
-const columns: ColumnDef<Device>[] = [
-  { accessorKey: 'hostname', header: 'Hostname', meta: { width: 'w-[200px]' } },
-  { accessorKey: 'status',   header: 'Status',   cell: ({ row }) => <StatusTag status={row.original.status} /> },
-]
-
-export function DevicesTable({ data }: { data: Device[] }) {
-  const table = useDataTable<Device>({
-    data,
-    columns,
-    clientSideSorting: true,
-    clientSideFiltering: true,
+// Minimal table
+const columns = useMemo<ColumnDef<Device>[]>(() => [
+  { accessorKey: 'hostname', header: 'Hostname', meta: { width: 'w-[260px]' } },
+  { accessorKey: 'status', header: 'Status', cell: ({ row }) => <StatusTag status={row.original.status} />, meta: { width: 'w-[140px]' } },
+], [])
+
+const table = useDataTable<Device>({ data: devices, columns })
+
+return (
+  <DataTable table={table}>
+    <DataTable.Header />
+    <DataTable.Body emptyMessage="No devices" />
+  </DataTable>
+)
+
+// Consumer-owned sorting (manual/server-side)
+const [sort, setSort] = useState<DataTableSortState | null>({ id: 'hostname', desc: false })
+const handleSortChange = useCallback((columnId: string) => {
+  setSort(prev => {
+    if (prev?.id !== columnId) return { id: columnId, desc: false }
+    if (!prev.desc) return { id: columnId, desc: true }
+    return null
   })
-
-  return (
-    <DataTable table={table}>
-      <DataTable.Header />
-      <DataTable.Body emptyMessage="No devices found" />
-    </DataTable>
-  )
-}
+}, [])
 ```
 
-> **Note:** Row actions, checkboxes, and chevron links are regular `ColumnDef` entries — not magic props. Use `data-no-row-click` on interactive cell wrappers to prevent click-event bubbling to `onRowClick`.
\ No newline at end of file
+> **Note:** Use `data-no-row-click` on interactive cell wrappers to prevent click events from bubbling to `onRowClick`. Pass `clientSideSorting: true` / `clientSideFiltering: true` to `useDataTable` for non-server-side tables.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.EmbeddableChat.stories.md b/openframe-frontend-core/src/stories/.EmbeddableChat.stories.md
index 769cd68be..83ce0d8cf 100644
--- a/openframe-frontend-core/src/stories/.EmbeddableChat.stories.md
+++ b/openframe-frontend-core/src/stories/.EmbeddableChat.stories.md
@@ -1,41 +1,56 @@
-<!-- source-hash: 928a4aa8278d9b5dca88c4e94782c25c -->
-Storybook stories for the `EmbeddableChat` component, covering three chat surface configurations: Guide-only, Mingo-only, and dual-mode (both transports enabled with a toggle).
+<!-- source-hash: 67038b2479103569868991cf0a58b864 -->
+Brief description of the file's purpose: Storybook story file for the `EmbeddableChat` component, providing mock runtimes, NATS adapter configs, and interactive story scenarios covering loading, error, empty, and active chat states.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `GuideOnly` | `Story` | Legacy single-mode Guide consumer matching `multi-platform-hub` mount pattern |
-| `MingoOnly` | `Story` | NATS agent transport surface with no mode toggle |
-| `BothModes` | `Story` | Dual-mode consumer with segmented Guide/Mingo header toggle |
-| `StoryShell` | Decorator | Wraps stories with `QueryClientProvider` + `ChatRuntimeContext` + canvas background |
-| `createMockRuntime()` | Helper | Returns a `ChatRuntime` with stub endpoints (all `/__story__/*`) |
-| `createMockMingoConfig()` | Helper | Returns a `UseNatsChatAdapterConfig` with `getNatsWsUrl: () => null` (no WS handshake) |
-| `SAMPLE_SLASH_COMMANDS` | Constant | 13 mock slash commands used to populate the empty-state chip grid |
+| Export / Symbol | Description |
+|----------------|-------------|
+| `createMockRuntime()` | Builds a minimal `ChatRuntime` with stub endpoints (no real server calls) |
+| `createMockMingoConfig()` | Base NATS adapter config with a null WS URL and canned message thread |
+| `createMockMingoConfigWithDialogs()` | Extends base config with paginated dialog history, rename, archive, and unarchive callbacks |
+| `createMockMingoConfigChatsLoading()` | Config where `fetchDialogs` never resolves — pins the history skeleton |
+| `createMockMingoConfigChatLoading()` | Config where `fetchDialogMessages` never resolves — pins the message-list skeleton |
+| `createMockMingoConfigChatsError()` | Config where `fetchDialogs` rejects — triggers the load-error + retry UI |
+| `createMockMingoConfigArchiveEmpty()` | Config with an empty archived-dialogs page — renders the archive empty state |
+| `SAMPLE_DIALOGS` | Eight canned `DialogItem` objects split across Today / Yesterday groups |
+| `SAMPLE_QUICK_ACTIONS` | Five `MingoQuickAction` chip definitions (Search, Script, Health, Tickets, Patch) |
+| `SAMPLE_SLASH_COMMANDS` | Six `SlashCommandSummary` entries served via a `window.fetch` shim at `/__story__/commands` |
+| `pending<T>()` | Helper returning a never-settling Promise — keeps any loading flag pinned `true` |
+| `COMMANDS_URL` | Shared constant (`/__story__/commands`) used by both the runtime mock and the fetch shim |
 
 ## Usage Example
 
 ```typescript
-// Minimal dual-mode story using the same pattern as BothModes
-export const MyStory: Story = {
-  render: (args) => (
-    <EmbeddableChat
-      {...args}
-      modes={{
-        guide: {},
-        mingo: createMockMingoConfig(),
-      }}
-      defaultActiveMode="mingo"
-      defaultOpen
-      showInternalTrigger={false}
-    />
-  ),
-  args: {},
+// Returning-user story (dialogs populated, quick-actions rendered)
+const meta: Meta<typeof EmbeddableChat> = {
+  component: EmbeddableChat,
+  decorators: [
+    (Story) => {
+      const runtime = useMemo(createMockRuntime, [])
+      const queryClient = new QueryClient()
+      return (
+        <QueryClientProvider client={queryClient}>
+          <ChatRuntimeContext.Provider value={runtime}>
+            <Story />
+          </ChatRuntimeContext.Provider>
+        </QueryClientProvider>
+      )
+    },
+  ],
 }
-```
 
-## Notes
+export const ReturningUser: StoryObj<typeof EmbeddableChat> = {
+  args: {
+    mingoConfig: createMockMingoConfigWithDialogs(),
+    quickActions: SAMPLE_QUICK_ACTIONS,
+  },
+  // play function uses `within` + `userEvent` to click the first dialog
+  // and verify the conversation view loads with canned messages.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    await userEvent.click(canvas.getByText('PowerShell script for bulk user creation'))
+  },
+}
+```
 
-- The `window.fetch` shim is installed **at module level** (not inside an effect) so the mock is in place before `EmbeddableChat`'s `useEffect` fires. A `__embeddableChatStoriesMockInstalled__` flag prevents double-patching across hot reloads.
-- All story endpoints resolve to `/__story__/*` — accidental real fetches return 404, not real server data.
-- `getNatsWsUrl: () => null` keeps the NATS dialog subscription idle in all stories.
\ No newline at end of file
+> **Note:** All fetch calls inside stories are intercepted by a `window.fetch` shim that serves `SAMPLE_SLASH_COMMANDS` for `COMMANDS_URL` and returns `404` for any other story-scoped path — no real network traffic is produced.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.GenericEntityCard.stories.md b/openframe-frontend-core/src/stories/.GenericEntityCard.stories.md
new file mode 100644
index 000000000..1f4031251
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.GenericEntityCard.stories.md
@@ -0,0 +1,34 @@
+<!-- source-hash: b13dc32d405e2d773dba9e6f3c613739 -->
+Storybook stories for `GenericEntityCard`, a fallback chat entity card renderer covering financial document types that don't require bespoke UI treatment.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `meta` | `Meta` | Storybook configuration for `Chat/EntityCards/GenericEntityCard` |
+| `FinancialKpi` | `Story` | Renders a financial KPI card |
+| `CapTable` | `Story` | Renders a cap table card |
+| `ProfitLoss` | `Story` | Renders a profit & loss card |
+| `BalanceSheet` | `Story` | Renders a balance sheet card |
+| `CashFlow` | `Story` | Renders a cash flow card |
+
+## Design Notes
+
+- **Decorator:** All stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
+- **Anchor props:** Each story uses `makeAnchorProps` to wire up navigation from the card's URL.
+- **Supported doc types:** `financial_kpi`, `cap_table`, `profit_loss`, `balance_sheet`, `cash_flow` — all driven by a shared `facts` key-value strip and a `badge` colored chip.
+
+## Usage Example
+
+```typescript
+import { GenericEntityCard } from '../components/chat/entity-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+import { financialKpiItem } from './__fixtures__/chat-cards'
+
+<GenericEntityCard
+  item={financialKpiItem}
+  anchorProps={makeAnchorProps(financialKpiItem.url ?? '#')}
+/>
+```
+
+> **Note:** `GenericEntityCard` acts as a catch-all renderer. Prefer bespoke card components for doc types with richer display requirements; use this component when a `facts` array + `badge` chip is sufficient.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.GitHubActivityCard.stories.md b/openframe-frontend-core/src/stories/.GitHubActivityCard.stories.md
new file mode 100644
index 000000000..7ab32a1e4
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.GitHubActivityCard.stories.md
@@ -0,0 +1,42 @@
+<!-- source-hash: ec96cdad8bd44e2cf349d694fdfcb820 -->
+Storybook stories for `GitHubActivityCard`, covering GitHub commit, pull request, and PR review entity cards rendered in a chat column layout.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Commit` | Compact card for `github_commit` doc type |
+| `PullRequest` | Compact card for `github_pull_request` doc type |
+| `PullRequestReview` | Compact card for `github_pr_review` doc type with `[review:STATE]` badge parsing |
+| `RowVariant` | Row-layout variant using the pull request fixture |
+
+## Usage Example
+
+```typescript
+import { GitHubActivityCard } from '../components/chat/entity-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+import { githubCommitItem } from './__fixtures__/chat-cards'
+
+// Compact commit card
+<GitHubActivityCard
+  item={githubCommitItem}
+  variant="compact"
+  anchorProps={makeAnchorProps(githubCommitItem.url ?? '#')}
+/>
+
+// Row layout for pull requests
+<GitHubActivityCard
+  item={githubPullRequestItem}
+  variant="row"
+  anchorProps={makeAnchorProps(githubPullRequestItem.url ?? '#')}
+/>
+```
+
+## Notes
+
+- Supports `compact` and `row` variants
+- `owner/repo` is derived from the item URL when `item.repo` is omitted
+- Long commit SHAs are automatically shortened
+- PR review titles with `[review:STATE]` markers drive the state badge color
+- Wrapped in `ChatColumnDecorator` to simulate the chat column layout
+- Covers `_public` doc type variants implicitly through the same component
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.GuideWelcome.stories.md b/openframe-frontend-core/src/stories/.GuideWelcome.stories.md
new file mode 100644
index 000000000..61ec13345
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.GuideWelcome.stories.md
@@ -0,0 +1,44 @@
+<!-- source-hash: efd42b7951b9364bba2e80f38794e5df -->
+Storybook stories for the `GuideWelcome` component, covering the guide-mode chat empty state with configurable quick actions, slash-command onboarding lists, and greeting copy variants.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Default` | Full empty state with slash-command list and quick-action chips |
+| `NoCommands` | Greeting and quick actions only, no slash-command list |
+| `NoQuickActions` | Slash-command list only, chip row omitted |
+| `CustomCopy` | Custom `title` and `subtitle` overriding default greeting text |
+
+**Supporting fixtures:**
+- `SAMPLE_QUICK_ACTIONS` — seven action chips demonstrating inline display and `⋯` overflow menu
+- `SAMPLE_LIST` — three `MingoOnboardingCard` entries (`/release-notes`, `/blogs`, `/getting-started`)
+- `ACTIONS` — shared Recent / Search / Find callbacks passed to each card
+
+## Usage Example
+
+```typescript
+import { GuideWelcome } from '../components/chat/guide-welcome'
+import { GuideModeBanner } from '../components/chat/guide-mode-banner'
+
+<div className="flex h-[760px] w-[440px] flex-col">
+  <GuideModeBanner />
+  <GuideWelcome
+    title="Ask the Guide"
+    subtitle="Explore docs and tickets."
+    quickActions={[
+      { id: 'how-to-start', label: 'How to start' },
+      { id: 'connect-device', label: 'Connect device' },
+    ]}
+    onQuickAction={(action) => console.log(action.id)}
+  >
+    {/* Optional slash-command list */}
+  </GuideWelcome>
+</div>
+```
+
+## Notes
+
+- Decorator wraps every story in a `440×760px` dark `ods-bg` panel with `GuideModeBanner` pinned at the top, matching the Figma node `7532:328214` drawer layout.
+- `quickActions` and `children` are both optional; omitting either removes that UI region entirely.
+- `onQuickAction` and `quickActions` controls are disabled in Storybook (`control: false`) — pass them programmatically.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.HubspotTicketCard.stories.md b/openframe-frontend-core/src/stories/.HubspotTicketCard.stories.md
new file mode 100644
index 000000000..40f5bbc90
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.HubspotTicketCard.stories.md
@@ -0,0 +1,46 @@
+<!-- source-hash: 358ffdf181cff4b3e4624b75c91df29a -->
+Storybook stories for the `HubspotTicketCard` chat entity card, covering the three server-side doc types (`hubspot_ticket`, `hubspot_ticket_anon`, `hubspot_ticket_self`) and both visual variants.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Full` | Complete ticket card with company, URL, and anchor navigation |
+| `Anon` | Anonymous variant — `customerCompany` and `url` nulled server-side, renders non-clickable shell |
+| `SelfTicket` | User's own ticket — admin URL stripped, status `NEW`, priority `MEDIUM` |
+| `ClosedTicket` | `CLOSED` / `LOW` priority state with clickable anchor |
+| `RowVariant` | Same full data rendered in `row` layout instead of `compact` |
+
+## Usage Example
+
+```typescript
+import { HubspotTicketCard } from '../components/chat/entity-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+import { hubspotTicketItem } from './__fixtures__/chat-cards'
+
+// Full ticket (technician view)
+<HubspotTicketCard
+  item={hubspotTicketItem}
+  variant="compact"
+  anchorProps={makeAnchorProps(hubspotTicketItem.url ?? '#')}
+/>
+
+// Anonymous variant (server redacts PII before sending)
+<HubspotTicketCard
+  item={{ ...hubspotTicketItem, customerCompany: null, url: null }}
+  variant="compact"
+/>
+
+// Row layout
+<HubspotTicketCard
+  item={hubspotTicketItem}
+  variant="row"
+  anchorProps={makeAnchorProps(hubspotTicketItem.url ?? '#')}
+/>
+```
+
+## Notes
+
+- All stories use `ChatColumnDecorator` to simulate the chat column width context.
+- The single `HubspotTicketCard` component handles all three doc types — redaction of `customerCompany` (anon) and `url` (anon + self) happens server-side before the payload reaches the card.
+- Status/priority badge appearance is driven by the `status` / `statusLabel` / `priority` fields on the item.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.InvestorUpdateCard.stories.md b/openframe-frontend-core/src/stories/.InvestorUpdateCard.stories.md
new file mode 100644
index 000000000..d4d423925
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.InvestorUpdateCard.stories.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 8a28e7f09b42f9392270067eafb565cd -->
+Storybook stories for the `InvestorUpdateCard` entity card component, covering both compact chat-inline (`sm`) and full (`default`) size variants.
+
+## Key Components
+
+- **`ChatInlineSm`** — Compact `sm` size variant intended for inline display within chat messages
+- **`Default`** — Full-size card variant for standard display contexts
+- **`ChatColumnDecorator`** — Wraps each story in a simulated chat column layout
+- **`investorUpdate`** — Shared fixture providing mock investor update data
+
+## Usage Example
+
+```typescript
+import { InvestorUpdateCard } from '../components/chat/entity-cards'
+
+// Compact chat-inline variant
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Default full-size variant
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  size="default"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Notes
+
+- Period badge (e.g. `"Mar 2025 - May 2025"`) is formatted via `formatInvestorUpdatePeriod` internally
+- Both stories link to `/investor-updates/<slug>` and open in a new tab via `target="_blank"`
+- Stories are registered under the `Chat/EntityCards/InvestorUpdateCard` Storybook path with `fullscreen` layout
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.MingoChatModals.stories.md b/openframe-frontend-core/src/stories/.MingoChatModals.stories.md
new file mode 100644
index 000000000..8ff7afffb
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.MingoChatModals.stories.md
@@ -0,0 +1,42 @@
+<!-- source-hash: eeac5fa6d99d16a54c9e7e71931d0495 -->
+Storybook stories for the `RenameChatModal` and `ArchiveChatModal` components, providing interactive previews of the chat header modals triggered from the `⋯` menu and dialog-history row menus.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Rename` | Story for `RenameChatModal` — pre-seeded input with current chat name, Cancel + Save actions |
+| `Archive` | Story for `ArchiveChatModal` — destructive confirmation dialog with a red action button |
+
+**Meta config:**
+- `title`: `Chat/MingoChatModals`
+- `layout`: `fullscreen` with a `bg-ods-bg` decorator wrapper
+- References Figma frames `7592:225962` (Rename) and `7592:226181` (Archive)
+- Both modals are built on `ModalV2` (Azeret Mono title, `p-40` / `gap-24`, in-house overlay)
+
+## Usage Example
+
+```typescript
+// Rename story — toggle open via button, logs saved name to console
+<RenameChatModal
+  isOpen={open}
+  initialName="Troubleshooting Exchange Online connection issues"
+  onClose={() => setOpen(false)}
+  onSave={(name) => {
+    console.log('save', name)
+    setOpen(false)
+  }}
+/>
+
+// Archive story — destructive confirmation, logs on confirm
+<ArchiveChatModal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  onConfirm={() => {
+    console.log('archive confirmed')
+    setOpen(false)
+  }}
+/>
+```
+
+Both stories render an **"Open … modal"** trigger button so the modal can be reopened after closing during interactive testing in Storybook.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.MingoInfoCard.stories.md b/openframe-frontend-core/src/stories/.MingoInfoCard.stories.md
new file mode 100644
index 000000000..8f483b00d
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.MingoInfoCard.stories.md
@@ -0,0 +1,44 @@
+<!-- source-hash: 3ba205c8b3aec59e3fa2ed5249902509 -->
+Storybook stories for the `MingoInfoCard` chat component, covering all Figma-defined variants and edge cases including media type, optional elements, status pill variants, clickability, and text truncation behavior.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `WithImage` | Card with a 40px avatar image as the leading media element |
+| `WithIcon` | Card with a boxed glyph icon instead of an avatar |
+| `WithoutStatus` | Omits the status pill |
+| `WithoutDescription` | Omits the subtitle/description line |
+| `WithoutMenu` | Omits the trailing overflow "⋯" menu |
+| `Clickable` | Full card acts as a clickable row (logs to console) |
+| `StatusVariants` | Renders all four `Tag` palette variants: `success`, `warning`, `error`, `grey` |
+| `LongContentTruncates` | Validates that long titles and descriptions truncate cleanly |
+
+## Usage Example
+
+```typescript
+import { MingoInfoCard } from '../components/chat/mingo-info-card'
+import { MonitorIcon } from '../components/icons-v2-generated/devices/monitor-icon'
+
+<MingoInfoCard
+  title="Production Host"
+  description="All systems operational"
+  icon={<MonitorIcon size={24} />}
+  status={{ label: 'Online', variant: 'success' }}
+  menuGroups={[
+    {
+      items: [
+        {
+          id: 'copy',
+          label: 'Copy link',
+          icon: <Copy01Icon size={16} />,
+          onClick: () => console.log('copy'),
+        },
+      ],
+    },
+  ]}
+  onClick={() => console.log('card clicked')}
+/>
+```
+
+> **Layout note:** The card is `w-full` and must be placed inside a block container. The Storybook layout is set to `fullscreen` (not `centered`) so the card can fill 100% width and reflow correctly on viewport resize.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.MingoOnboardingCard.stories.md b/openframe-frontend-core/src/stories/.MingoOnboardingCard.stories.md
index da38077fe..0e1267483 100644
--- a/openframe-frontend-core/src/stories/.MingoOnboardingCard.stories.md
+++ b/openframe-frontend-core/src/stories/.MingoOnboardingCard.stories.md
@@ -1,42 +1,36 @@
-<!-- source-hash: 3d1f4ac24e4bcadba43f4bdf62347d8d -->
-Storybook stories for `MingoOnboardingCard`, the single-row card used in Mingo's chat empty-state list. Covers isolated prop variants and a full stacked list mirroring the Figma empty-state layout.
+<!-- source-hash: d11741abff27bcd4ba15123ae5c368bd -->
+Storybook stories for the `MingoOnboardingCard` component, covering all prop combinations and a full chip-command stack that mirrors the chat empty-state UI (Figma node `7363:205938`).
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
+|---|---|
 | `Default` | Base card with icon, title, slash command, and description |
-| `WithoutDescription` | Card omitting the description field |
-| `WithoutSlashCommand` | Card omitting the slash command badge |
-| `LongTitleTruncates` | Validates truncation behavior for long titles and commands |
+| `WithoutDescription` | Card omitting the optional description field |
+| `WithoutSlashCommand` | Card omitting the optional slash command badge |
+| `LongTitleTruncates` | Validates truncation behavior for long titles and slash commands |
 | `Clickable` | Card with an `onClick` handler wired to console output |
-| `WithActions` | Card with multiple outline-chip action buttons (Recent, Search, Find) |
-| `ChipCommands` | Full stacked list of 13 cards driven by `SAMPLE_CHIP_COMMANDS`, mirroring Figma node `7363:205938` |
+| `WithActions` | Card rendering inline outline-chip action buttons |
+| `ChipCommands` | Full stacked list using `resolveOnboardingIcon` to mirror runtime rendering |
 
 ## Usage Example
 
 ```typescript
-// Single card with actions
+// Render a card with actions
 <MingoOnboardingCard
   icon={<CompassIcon size={16} />}
   title="ClickUp Roadmap"
   slashCommand="/roadmap"
   description="Public product roadmap with upcoming features and releases"
   actions={[
-    { id: 'recent', label: 'Recent', onClick: () => {} },
-    { id: 'search', label: 'Search', onClick: () => {} },
+    { id: 'recent', label: 'Recent', onClick: () => console.log('recent') },
+    { id: 'search', label: 'Search', onClick: () => console.log('search') },
   ]}
 />
-
-// Stacked list — icons resolved from the shared registry
-const Icon = resolveOnboardingIcon('rocket-02')
-<MingoOnboardingCard
-  icon={<Icon size={16} />}
-  title="Product Releases"
-  slashCommand="/release-notes"
-  description="OpenFrame version releases, changelogs, and update notes"
-  actions={[{ id: 'recent', label: 'Recent', onClick: () => {} }]}
-/>
 ```
 
-> **Decorator context:** All stories wrap cards inside a `rounded-md` border container. The bottom border on each card acts as a 1-px divider between siblings, collapsed on the last row via `last:border-b-0`.
\ No newline at end of file
+## Notes
+
+- All stories are wrapped in a `w-[520px]` decorator that replicates the `rounded-md` container used in the live chat UI
+- The `ChipCommands` story sources icons via `resolveOnboardingIcon`, keeping it in sync with the runtime icon registry — add new slash commands to `SAMPLE_CHIP_COMMANDS` to preview them
+- The `icon` and `onClick` argTypes have `control: false` set, as they accept React nodes/functions rather than serializable values
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.MingoWelcome.stories.md b/openframe-frontend-core/src/stories/.MingoWelcome.stories.md
new file mode 100644
index 000000000..60afc2905
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.MingoWelcome.stories.md
@@ -0,0 +1,41 @@
+<!-- source-hash: cd831549353e5399baf0e351532dbc08 -->
+Storybook stories for the `MingoWelcome` component, covering the chat empty-state UI across its key display variants and configurations.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Default` | Full welcome state with Guide CTA (promo card + chip) wired |
+| `WithUserName` | Personalised greeting with a first name passed via `userName` |
+| `WithoutGuide` | Guide mode disabled — promo card and "Start Guide Chat" chip suppressed |
+| `WithQuickActions` | Additional quick-action chips appended after the built-in Guide chip |
+| `ReturningUser` | Returning user state (`hasExistingChats: true`) — hides promo notification, mutes Guide chip, shows dialog history |
+| `Wide` | Wide panel layout (960px) for desktop/in-layout rendering |
+
+## Usage Example
+
+```typescript
+import { MingoWelcome } from '../components/chat/mingo-welcome'
+
+// First-time user with Guide CTA
+<MingoWelcome
+  onStartGuideChat={() => switchToGuideMode()}
+/>
+
+// Returning user with chat history and quick actions
+<MingoWelcome
+  userName="Grace"
+  hasExistingChats={true}
+  dialogHistory={<MingoChatHistory dialogs={[...]} />}
+  onStartGuideChat={() => switchToGuideMode()}
+  quickActions={[
+    { id: 'weekly', label: 'Weekly Log Summary' },
+  ]}
+/>
+```
+
+## Notes
+
+- All stories render inside a `440×760px` constrained flex container mimicking the narrow drawer panel; the `Wide` story overrides this to `960px`
+- `SAMPLE_HISTORY` provides a reusable `MingoChatHistory` fixture with 6 sample dialogs for the `ReturningUser` story
+- Figma reference: node `7532:222444`
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.Modal.stories.md b/openframe-frontend-core/src/stories/.Modal.stories.md
index ae476c6c4..cce771f33 100644
--- a/openframe-frontend-core/src/stories/.Modal.stories.md
+++ b/openframe-frontend-core/src/stories/.Modal.stories.md
@@ -1,23 +1,25 @@
-<!-- source-hash: a814b843aeaf82abd73ff945b405ef13 -->
-Storybook stories for the `Modal` UI component, demonstrating two interaction patterns: a basic modal with header/content/footer, and a modal containing an `Autocomplete` dropdown with portal-aware rendering.
+<!-- source-hash: f30f001db374caa2804f9c6e873f3b59 -->
+Storybook stories for the `Modal` UI component, demonstrating interactive open/close behavior and composition with sub-components (`ModalHeader`, `ModalContent`, `ModalFooter`).
 
 ## Key Components
 
 | Export | Description |
-|---|---|
-| `Default` | Basic modal story with open/close toggle, header, body text, and Cancel/Confirm footer buttons |
-| `WithAutocomplete` | Modal story embedding an `Autocomplete` multi-select with `overflow-visible` and a `ref` callback to capture the modal DOM node for portal containment |
+|--------|-------------|
+| `Default` | Basic modal with header, body text, Cancel and Confirm footer buttons |
+| `WithAutocomplete` | Modal containing a multi-select `Autocomplete` dropdown; uses a `ref`-based `portalContainer` pattern to avoid z-index conflicts |
 
 ## Usage Example
 
 ```typescript
 // Default modal pattern
+const [isOpen, setIsOpen] = useState(false)
+
 <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
   <ModalHeader>
     <ModalTitle>Modal Title</ModalTitle>
   </ModalHeader>
   <ModalContent className="px-6 py-4">
-    <p>Modal body content</p>
+    <p>Content goes here.</p>
   </ModalContent>
   <ModalFooter>
     <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
@@ -25,25 +27,23 @@ Storybook stories for the `Modal` UI component, demonstrating two interaction pa
   </ModalFooter>
 </Modal>
 
-// Autocomplete inside modal — capture modal ref to avoid z-index conflicts
+// Autocomplete inside modal — capture modal DOM node via ref
 const [modalElement, setModalElement] = useState<HTMLDivElement | null>(null)
 const modalRef = useCallback((node: HTMLDivElement | null) => {
   setModalElement(node)
 }, [])
 
-<Modal ref={modalRef} isOpen={isOpen} onClose={...} className="max-w-lg overflow-visible">
+<Modal ref={modalRef} isOpen={isOpen} onClose={...} className="overflow-visible">
   <ModalContent className="px-6 py-4">
     <Autocomplete
+      multiple
       options={options}
       value={selected}
       onChange={setSelected}
-      placeholder="Search..."
+      portalContainer={modalElement}
     />
   </ModalContent>
 </Modal>
 ```
 
-## Notes
-
-- `WithAutocomplete` uses `useCallback` ref to capture the modal DOM node, enabling dropdown portals to render inside the modal's subtree and avoid z-index stacking issues.
-- Both stories manage `isOpen` via local `useState`, decoupled from Storybook's `args.isOpen` control after initial render.
\ No newline at end of file
+> **Note:** When rendering dropdowns inside a modal, pass the modal's DOM node as `portalContainer` to the `Autocomplete` component. This keeps the dropdown within the modal's stacking context and prevents z-index conflicts with the backdrop.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.NotificationDrawer.stories.md b/openframe-frontend-core/src/stories/.NotificationDrawer.stories.md
index 4ffde8f5f..8f9b0ec50 100644
--- a/openframe-frontend-core/src/stories/.NotificationDrawer.stories.md
+++ b/openframe-frontend-core/src/stories/.NotificationDrawer.stories.md
@@ -1,55 +1,51 @@
-<!-- source-hash: fd9f374934342611a000534ff097b06e -->
-Storybook stories for the `NotificationDrawer` feature, providing interactive visual tests for notification tile variants, drawer states, and live notification dispatching via the `useNotifications` hook.
+<!-- source-hash: c33e9f17ea374ca449e12acde60a4d30 -->
+Storybook stories for the `NotificationDrawer` feature, covering all tile variants, live animation states, drawer open/close behavior, and an interactive playground for firing notifications programmatically.
 
 ## Key Components
 
-| Export | Description |
-|---|---|
-| `AllTileVariants` | Static preview of all five `NotificationVariant` tile styles (`default`, `success`, `error`, `warning`, `info`) in a settled/read state |
-| `LiveTile` | Demonstrates the animated progress-bar lifecycle of a freshly arrived tile, with a replay button |
-| `DrawerEmpty` | Drawer rendered with zero notifications (empty state), auto-opened on mount |
-| `DrawerWithSeedData` | Drawer pre-seeded with six notifications mirroring the Figma reference design |
-| `LivePlayground` | Interactive sandbox for firing notifications of any variant, toggling the drawer, and testing `markAllRead`/`clear` |
+| Export | Type | Description |
+|--------|------|-------------|
+| `AllTileVariants` | `Story` | Static render of all five `NotificationVariant` tile states (`default`, `success`, `error`, `warning`, `info`) |
+| `LiveTile` | `Story` | Animated tile showing the 4-second progress bar / dismiss phase before settling; includes a replay button |
+| `DrawerEmpty` | `Story` | Drawer auto-opened with no notifications (empty state) |
+| `DrawerWithSeedData` | `Story` | Drawer pre-populated with six seeded notifications mirroring the Figma reference |
+| `LivePlayground` | `Story` | Full interactive sandbox — fires all variants, toggles the drawer, marks-all-read, and clears notifications |
+| `AutoOpen` | Helper | Calls `useNotifications().open()` on mount so drawer stories open immediately |
+| `PlaygroundControls` | Helper | Internal panel exposing buttons for every `addNotification` variant and drawer actions |
 
 ## Usage Example
 
 ```typescript
-// Minimal setup mirroring how stories bootstrap the notification system
-import {
-  NotificationsProvider,
-  NotificationDrawer,
-  useNotifications,
-} from '../components/features/notifications';
-
-function App() {
+// Simulating how a NATS/realtime source would push notifications
+import { NotificationsProvider, NotificationDrawer, NotificationPopups, useNotifications } from '../components/features/notifications';
+
+function AppRoot() {
   return (
-    <NotificationsProvider
-      initialNotifications={[]}
-      onHistoryClick={() => router.push('/notifications')}
-      onShowPopupsChange={(enabled) => console.log('popups:', enabled)}
-    >
+    <NotificationsProvider onHistoryClick={() => router.push('/notifications')}>
       <NotificationDrawer />
-      <FireButton />
+      <NotificationPopups />
+      <App />
     </NotificationsProvider>
   );
 }
 
-function FireButton() {
+// From any child component or subscription handler:
+function NatsListener() {
   const { addNotification } = useNotifications();
-  return (
-    <button
-      onClick={() =>
-        addNotification({
-          variant: 'success',
-          title: 'Deployment Complete',
-          description: 'HP EliteBook deployed to Marketing Dept',
-        })
-      }
-    >
-      Fire notification
-    </button>
-  );
+
+  useEffect(() => {
+    nats.subscribe('alerts', (msg) => {
+      addNotification({
+        variant: 'error',
+        title: msg.title,
+        description: msg.body,
+        onClick: () => router.push(`/alerts/${msg.id}`),
+      });
+    });
+  }, [addNotification]);
+
+  return null;
 }
 ```
 
-> Mount `<NotificationsProvider>` once at the app root. The `<NotificationDrawer>` can be placed anywhere within the provider tree; the bell button in `AppHeader` toggles it automatically.
\ No newline at end of file
+> The `LivePlayground` story mirrors this exact pattern — `addNotification` is called externally while `<NotificationPopups>` surfaces incoming items as top-right toasts. Opening the drawer automatically suppresses pop-ups to avoid duplicate display.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.OnboardingGuideCard.stories.md b/openframe-frontend-core/src/stories/.OnboardingGuideCard.stories.md
new file mode 100644
index 000000000..7ff72807f
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.OnboardingGuideCard.stories.md
@@ -0,0 +1,40 @@
+<!-- source-hash: 158823868f1a6fa08bcd360e6e3fc0c6 -->
+Storybook stories for the `OnboardingGuideCard` component, covering all three display densities used across the Flamingo/OpenFrame UI.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `ChatInlineSm` | Compact `sm` size — used by the chat dispatch with `displayAction: true` for Ask/Display affordance |
+| `Default` | Horizontal step-card layout at `default` density |
+| `Catalog` | Full hero + author grid layout at `catalog` density |
+
+## Usage Example
+
+```typescript
+import { OnboardingGuideCard } from '../components/chat/entity-cards'
+
+// Chat inline (dispatch default)
+<OnboardingGuideCard
+  guide={onboardingGuide}
+  href={`/guides/${onboardingGuide.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Catalog hero layout
+<OnboardingGuideCard
+  guide={onboardingGuide}
+  href={`/guides/${onboardingGuide.slug}`}
+  size="catalog"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Notes
+
+- All stories are wrapped in `ChatColumnDecorator` to simulate the chat column width constraint
+- The `sm` size mirrors exactly what the chat dispatch renders — always paired with `displayAction: true` in production
+- Fixture data (`onboardingGuide`) lives in `./__fixtures__/chat-cards`
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.PageActions.stories.md b/openframe-frontend-core/src/stories/.PageActions.stories.md
index 757fa4343..fd843a2eb 100644
--- a/openframe-frontend-core/src/stories/.PageActions.stories.md
+++ b/openframe-frontend-core/src/stories/.PageActions.stories.md
@@ -1,30 +1,26 @@
-<!-- source-hash: cad0666dc893f948d0160200a40d9384 -->
-Storybook stories file for the `PageActions` component, documenting all interactive variants and states for use in the Flamingo/OpenFrame UI library.
+<!-- source-hash: c2ab0103ae9c6603a7acd3db11530c37 -->
+Storybook stories for the `PageActions` UI component, covering all layout variants, action states, and responsive behaviors.
 
 ## Key Components
 
 **Exported Stories:**
+- `IconButtons` — Icon-labeled buttons that collapse to a dropdown menu on mobile
+- `PrimaryButtons` / `PrimaryButtonsWithIcons` / `SinglePrimaryButton` — Accent + outline button combos for form/detail pages
+- `SingleIconButton` — Single action rendered as icon (not collapsed to menu) on mobile
+- `ThreeIconButtons` — Multiple icon actions
+- `WithStates` — Loading and disabled button states
+- `MenuPrimary` / `MenuPrimarySingleAction` / `MenuPrimaryLoading` — `ActionsMenuDropdown ("...")` + primary button pattern
+- `MobileOnlyActions` — Actions hidden on desktop via `showOnlyMobile`
+- `LinkActions` — Actions rendered as Next.js `<Link>` using `href`
+- `SplitButtonWithMenu` — Primary button with chevron submenu alongside `menuActions`
+- `SplitButtonTwoActions` — Two independently clickable halves via `iconAction`
 
-| Story | Variant | Description |
-|---|---|---|
-| `IconButtons` | `icon-buttons` | Icon + label buttons, collapses to dropdown on mobile |
-| `PrimaryButtons` | `primary-buttons` | Accent + outline buttons, fixed bottom bar on mobile |
-| `PrimaryButtonsWithIcons` | `primary-buttons` | Primary buttons with leading icons |
-| `SinglePrimaryButton` | `primary-buttons` | Single accent CTA |
-| `SingleIconButton` | `icon-buttons` | Single icon button (stays visible on mobile, no menu collapse) |
-| `ThreeIconButtons` | `icon-buttons` | Three-action icon row |
-| `WithStates` | `primary-buttons` | `loading` and `disabled` prop states |
-| `MenuPrimary` | `menu-primary` | `...` overflow menu + primary button |
-| `MenuPrimaryLoading` | `menu-primary` | Loading state on primary button |
-| `MobileOnlyActions` | `icon-buttons` | `showOnlyMobile` prop — hides specific actions on desktop |
-| `LinkActions` | `menu-primary` | `href`-based actions rendering as `<a>` elements |
-| `SplitButtonWithMenu` | `menu-primary` | `submenu` chevron split button pattern |
-| `SplitButtonTwoActions` | `menu-primary` | `iconAction` dual-target split button |
+**Variants covered:** `icon-buttons`, `primary-buttons`, `menu-primary`
 
 ## Usage Example
 
 ```typescript
-// Basic icon-buttons usage in a page header
+// Basic icon-buttons variant
 <PageActions
   variant="icon-buttons"
   actions={[
@@ -33,28 +29,20 @@ Storybook stories file for the `PageActions` component, documenting all interact
   ]}
 />
 
-// menu-primary with split button and overflow menu
+// menu-primary with split button and submenu
 <PageActions
   variant="menu-primary"
-  actions={[
-    {
-      label: 'Remote Shell',
-      variant: 'outline',
-      submenu: [
-        { id: 'cmd', label: 'CMD', onClick: openCmd, icon: <TerminalIcon size={24} /> },
-        { id: 'powershell', label: 'Power Shell', onClick: openPs, icon: <TerminalIcon size={24} /> },
-      ],
-    },
-  ]}
-  menuActions={[
-    {
-      items: [
-        { id: 'edit', label: 'Edit Device', onClick: handleEdit, icon: <PenEditIcon size={24} /> },
-        { id: 'delete', label: 'Delete Device', onClick: handleDelete, icon: <TrashIcon size={24} /> },
-      ],
-    },
-  ]}
+  actions={[{
+    label: 'Remote Shell',
+    variant: 'outline',
+    submenu: [
+      { id: 'cmd', label: 'CMD', onClick: handleCmd, icon: <TerminalIcon size={24} /> },
+    ],
+  }]}
+  menuActions={[{
+    items: [{ id: 'edit', label: 'Edit Device', onClick: handleEdit }],
+  }]}
 />
 ```
 
-> **Tip:** Use `PageActions` via the `headerActions` prop on `PageContainer` for consistent page-level layouts across the Flamingo platform.
\ No newline at end of file
+Use with `PageContainer`'s `headerActions` prop for consistent page-level layouts.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.PageContainer.stories.md b/openframe-frontend-core/src/stories/.PageContainer.stories.md
index 1ff694227..566213327 100644
--- a/openframe-frontend-core/src/stories/.PageContainer.stories.md
+++ b/openframe-frontend-core/src/stories/.PageContainer.stories.md
@@ -1,36 +1,39 @@
-<!-- source-hash: f72131cedcde7906c303bc3ea8538959 -->
-Storybook stories for the `PageContainer` layout component, covering legacy and advanced usage variants including list, detail, form, and content page layouts.
+<!-- source-hash: 6f5a95b06338851dcc16b8ce6b05192a -->
+Storybook stories for the `PageContainer` layout component, covering legacy usage, variant configurations, header customization, and padding/background options.
 
 ## Key Components
 
-- **`Legacy`** — Basic container with full-width background and no structured header
-- **`LegacyCustomBackground`** / **`LegacyContentWidthBackground`** — Legacy mode with custom background and content-width options
-- **`ListPage`** / **`ListPageMultipleActions`** — List variant with title, subtitle, and action buttons
-- **`DetailPage`** / **`DetailPageWithActions`** — Detail variant with back button navigation and optional actions
-- **`FormPage`** — Form variant with cancel/save/publish actions
-- **`ContentPage`** — Generic content layout variant
-- **`CustomHeaderContent`** / **`WithHeaderActions`** / **`HiddenHeader`** — Header customization stories
-- **`WithPaddingAndBackground`** — Demonstrates `padding` and `background` prop combinations
+- **`meta`** — Storybook metadata registering `PageContainer` under `Layout/PageContainer` with `argType` controls for `variant`, `padding`, `background`, and `showHeader`
+- **`PlaceholderContent`** — Internal helper component rendering a styled card placeholder to fill story layouts
 
-## Storybook Controls
+## Exported Stories
 
-| Control | Options |
-|---------|---------|
-| `variant` | `list`, `detail`, `form`, `content` |
-| `padding` | `none`, `sm`, `md`, `lg` |
-| `background` | `default`, `card`, `transparent` |
-| `showHeader` | `boolean` |
+| Story | Description |
+|---|---|
+| `Legacy` | Basic container with full-width background and custom className |
+| `LegacyCustomBackground` | Legacy mode with custom `backgroundClassName` |
+| `LegacyContentWidthBackground` | Legacy mode with content-scoped background only |
+| `ListPage` | List variant with title, subtitle, and a single action button |
+| `ListPageMultipleActions` | List variant with multiple header actions (Edit + Create) |
+| `DetailPage` | Detail variant with back button navigation |
+| `DetailPageWithActions` | Detail variant combining back button and action buttons |
+| `FormPage` | Form variant with Cancel back button and Save/Publish actions |
+| `ContentPage` | Generic content variant with a title |
+| `CustomHeaderContent` | List variant with a fully custom `headerContent` ReactNode |
+| `WithHeaderActions` | List variant combining `headerActions` and `actions` props |
+| `HiddenHeader` | Content variant with `showHeader: false` |
+| `WithPaddingAndBackground` | Content variant demonstrating `padding: 'lg'` and `background: 'card'` |
 
 ## Usage Example
 
 ```typescript
-// List page with actions
+// Typical list page usage
 <PageContainer
   variant="list"
   title="Devices"
   subtitle="24 devices found"
   actions={[
-    { label: 'Add Device', onClick: handleAdd, icon: <Plus />, variant: 'primary' }
+    { label: 'Add Device', onClick: () => {}, icon: <Plus />, variant: 'accent' }
   ]}
 >
   <DeviceTable />
@@ -40,11 +43,8 @@ Storybook stories for the `PageContainer` layout component, covering legacy and
 <PageContainer
   variant="detail"
   title="Device Details"
-  backButton={{ label: 'Back to Devices', onClick: handleBack }}
-  actions={[
-    { label: 'Delete', onClick: handleDelete, variant: 'outline' }
-  ]}
+  backButton={{ label: 'Back to Devices', onClick: () => router.back() }}
 >
-  <DeviceDetails />
+  <DeviceDetail />
 </PageContainer>
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.PageLayout.stories.md b/openframe-frontend-core/src/stories/.PageLayout.stories.md
index 951bb1ec1..42e096f32 100644
--- a/openframe-frontend-core/src/stories/.PageLayout.stories.md
+++ b/openframe-frontend-core/src/stories/.PageLayout.stories.md
@@ -1,32 +1,32 @@
-<!-- source-hash: 3e5784b9b627d4143a0bac991ef6fb48 -->
-Storybook stories for the `PageLayout` component, covering all major layout variants including title-only, subtitle/image combinations, mobile responsive behavior, and action button configurations.
+<!-- source-hash: b09fa95f839417d0e19c0699fdf0b67c -->
+Storybook stories for `PageLayout`, demonstrating all supported layout configurations including titles, subtitles, thumbnail images, back buttons, header actions, tab selectors, and responsive mobile behavior.
 
 ## Key Components
 
 | Export | Description |
 |--------|-------------|
-| `TitleOnly` | Minimal header with title and content only |
-| `WithSubtitleAndImage` | Full organization detail header with back button, thumbnail, subtitle, and icon-button actions |
-| `MobileActionsMenu` | Same as `WithSubtitleAndImage` at mobile viewport — actions collapse to `…` dropdown |
-| `WithSubtitleOnly` | Title + one-line context note with primary-button actions |
+| `TitleOnly` | Baseline header with title and table content |
+| `WithSubtitleAndImage` | Full org detail header with logo, subtitle, back button, and icon-button actions |
+| `MobileActionsMenu` | `WithSubtitleAndImage` at mobile viewport — actions collapse into a `…` dropdown |
+| `WithSubtitleOnly` | Title + one-line context note, primary-button actions |
 | `WithImageOnly` | Branded entity header without a subtitle line |
-| `WithSelector` | Desktop tab selector (table/grid toggle) rendered before action buttons |
+| `WithSelector` | Desktop `TabSelector` for table/grid toggle rendered before action buttons |
 | `WithSelectorMobile` | `WithSelector` at mobile viewport — selector hidden, only `…` dropdown remains |
-| `LongTitleTruncates` | Verifies ellipsis truncation when title/subtitle overflow the header |
+| `LongTitleTruncates` | Verifies ellipsis truncation when title/subtitle overflow |
 
 ## Usage Example
 
 ```typescript
-// Minimal usage
+// Minimal title-only layout
 <PageLayout title="Devices">
   <Table data={devices} columns={columns} rowKey="id" />
 </PageLayout>
 
-// Full organization detail page
+// Full org detail layout with image, subtitle, and icon-button actions
 <PageLayout
   title="TechFlow Solutions"
   subtitle="techflow.com • Software Development"
-  image={{ src: logoSrc, alt: 'TechFlow logo' }}
+  image={{ src: logoUri, alt: 'TechFlow Solutions logo' }}
   backButton={{ label: 'Back to Organizations', onClick: handleBack }}
   actionsVariant="icon-buttons"
   actions={[
@@ -37,7 +37,7 @@ Storybook stories for the `PageLayout` component, covering all major layout vari
   <Table data={devices} columns={columns} rowKey="id" />
 </PageLayout>
 
-// With desktop tab selector (hidden on mobile)
+// With a desktop-only tab selector (hidden on mobile)
 <PageLayout
   title="Devices"
   actionsVariant="icon-buttons"
@@ -53,8 +53,8 @@ Storybook stories for the `PageLayout` component, covering all major layout vari
     />
   }
 >
-  <Table data={devices} columns={columns} rowKey="id" />
+  {content}
 </PageLayout>
 ```
 
-**`actionsVariant` options:** `icon-buttons` (labeled outline buttons → `…` menu on mobile), `primary-buttons` (always visible primary buttons), `menu-primary` (menu trigger with primary style).
\ No newline at end of file
+> The `actionsVariant` prop controls rendering: `icon-buttons` collapses to a `…` dropdown on mobile, `primary-buttons` renders accent/outline buttons at all breakpoints, and `menu-primary` combines a menu trigger with a primary action button.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ProductReleaseCard.stories.md b/openframe-frontend-core/src/stories/.ProductReleaseCard.stories.md
new file mode 100644
index 000000000..0d5c15068
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.ProductReleaseCard.stories.md
@@ -0,0 +1,32 @@
+<!-- source-hash: 290738d76bac6ec31d0611cc77b0adc1 -->
+Storybook stories for the `ProductReleaseCard` component, covering the two supported density variants (`sm` and `lg`) of the `product_release` entity card.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `ChatInlineSm` | Compact inline card used within chat responses |
+| `ChatInlineSmWithVideoCover` | Compact variant with video cover thumbnail enabled |
+| `Large` | Rich catalog-row card used on `/releases`, DevCenter tab, and investor-update related-content sections |
+
+## Usage Example
+
+```typescript
+// Render the large variant programmatically
+import { ProductReleaseCard } from '../components/chat/entity-cards'
+import { productReleaseLgProps } from './__fixtures__/chat-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+
+<ProductReleaseCard
+  {...productReleaseLgProps}
+  size="lg"
+  anchorProps={makeAnchorProps('/releases/2-5-0')}
+/>
+```
+
+## Notes
+
+- Both `sm` and `lg` share a **flat prop signature** — no `item` wrapper object required.
+- The `lg` variant renders a hero cover, version pill, changelog stats strip, and a 4-cell metadata grid footer (`Type / Status / Released / Author`).
+- The `sm` variant optionally accepts `hasVideoCover: true` to display a video thumbnail.
+- All stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.ProgramCard.stories.md b/openframe-frontend-core/src/stories/.ProgramCard.stories.md
new file mode 100644
index 000000000..475f9d544
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.ProgramCard.stories.md
@@ -0,0 +1,34 @@
+<!-- source-hash: abf8ccf174f6c325f8b6a86c8368e747 -->
+Storybook stories for the `ProgramCard` entity card component, covering the three supported program doc types (`podcast`, `webinar`, `event`) at both `sm` (chat-dispatch) and `default` density sizes.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `PodcastSm` | Podcast card at `sm` size — matches chat dispatch rendering |
+| `WebinarSm` | Webinar card at `sm` size — matches chat dispatch rendering |
+| `EventSm` | Event card at `sm` size — matches chat dispatch rendering |
+| `PodcastDefault` | Podcast card at `default` density — catalog page layout |
+
+## Usage Example
+
+```typescript
+// Rendering ProgramCard with minimum safe config for chat
+import { ProgramCard } from '../components/chat/entity-cards'
+import { DEFAULT_PROGRAM_CONFIGS } from '../components/chat/entity-cards/program-card-defaults'
+
+<ProgramCard
+  config={DEFAULT_PROGRAM_CONFIGS.podcast}
+  item={podcastItem}
+  size="sm"
+  href={`/podcasts/${podcastItem.id}`}
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Notes
+
+- All stories are wrapped in `ChatColumnDecorator` to simulate the chat column width context
+- `DEFAULT_PROGRAM_CONFIGS[type]` provides safe minimum config for compact chat rendering; embedders can override per type with a full catalog config
+- `sm` size is the canonical size used by the chat dispatch; `default` size targets catalog page rendering
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.RoadmapCard.stories.md b/openframe-frontend-core/src/stories/.RoadmapCard.stories.md
new file mode 100644
index 000000000..2da502a78
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.RoadmapCard.stories.md
@@ -0,0 +1,39 @@
+<!-- source-hash: 72d41aa10f4798e2928e546b0358d618 -->
+Storybook stories for the `RoadmapCard` component, covering all three roadmap doc types (`roadmap_item`, `delivery_item`, `internal_task`) in both `sm` (chat-inline) and `default` (full rich card) size variants.
+
+## Key Components
+
+- **`RoadmapItemSm`** — Compact inline card for a roadmap feature item, used inside chat responses
+- **`DeliveryItemSm`** — Compact inline card for a delivery/release item
+- **`InternalTaskSm`** — Compact inline card for an internal task
+- **`RoadmapItemDefault`** — Full rich card with vote buttons, screenshot gallery, status pill, and target version; used on the public roadmap page
+
+## Usage Example
+
+```typescript
+import { RoadmapCard } from '../components/chat/entity-cards'
+
+// Chat-inline compact variant
+<RoadmapCard
+  item={roadmapFeatureItem}
+  href={`/roadmap/${roadmapFeatureItem.id}`}
+  size="sm"
+  cardType="roadmap_item"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Full rich card (public roadmap page)
+<RoadmapCard
+  item={roadmapFeatureItem}
+  size="default"
+  cardType="roadmap_item"
+/>
+```
+
+## Notes
+
+- The `cardType` prop controls the icon rendered in the `sm` variant (`Feature` / `Delivery` / `Bug`-shaped task)
+- All `sm` stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout
+- In the `default` size, vote handlers are real; in chat (`sm`) they are stubbed
+- Fixture data is sourced from `./__fixtures__/chat-cards`
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.SlackMessageCard.stories.md b/openframe-frontend-core/src/stories/.SlackMessageCard.stories.md
new file mode 100644
index 000000000..8bd830f58
--- /dev/null
+++ b/openframe-frontend-core/src/stories/.SlackMessageCard.stories.md
@@ -0,0 +1,36 @@
+<!-- source-hash: c2739c86036e406bd419b03f561d1e70 -->
+Storybook stories for `SlackMessageCard`, a chat entity card component that renders Slack message previews inline. Covers both display variants used across the Flamingo/OpenFrame chat UI.
+
+## Key Components
+
+- **`Compact` story** — renders the card as it appears inline within a chat message bubble
+- **`RowVariant` story** — renders the card in list/row contexts (e.g., search results, grouped entity lists)
+- **`ChatColumnDecorator`** — wraps stories in a realistic chat column layout for accurate sizing
+- **`slackMessageItem`** — shared fixture representing a `slack_message` doc type with PII-sanitized preview data
+- **`makeAnchorProps`** — helper that generates link props from the item's URL
+
+## Usage Example
+
+```typescript
+import { SlackMessageCard } from '../components/chat/entity-cards'
+
+// Inline chat usage
+<SlackMessageCard
+  item={slackMessageItem}
+  variant="compact"
+  anchorProps={makeAnchorProps(slackMessageItem.url ?? '#')}
+/>
+
+// List/row context
+<SlackMessageCard
+  item={slackMessageItem}
+  variant="row"
+  anchorProps={makeAnchorProps(slackMessageItem.url ?? '#')}
+/>
+```
+
+## Notes
+
+- Component is **pure presentation** — no side effects or data fetching
+- Slack message previews are **PII-sanitized server-side** before reaching this component
+- Both variants share the same `item` and `anchorProps` interface; only layout differs
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.TabSelector.stories.md b/openframe-frontend-core/src/stories/.TabSelector.stories.md
index 6fb3b0607..ae909e309 100644
--- a/openframe-frontend-core/src/stories/.TabSelector.stories.md
+++ b/openframe-frontend-core/src/stories/.TabSelector.stories.md
@@ -1,23 +1,23 @@
-<!-- source-hash: eea14186773eb206e54d1ffb8e785935 -->
-Storybook stories for the `TabSelector` UI component, showcasing all supported variants, states, and composition patterns.
+<!-- source-hash: 60b03abb76c9523e1bee39c6f559e738 -->
+Storybook stories for the `TabSelector` UI component, showcasing all supported variants, states, and real-world usage patterns.
 
 ## Key Components
 
-### Exported Stories
+### Story Exports
 
 | Story | Description |
 |-------|-------------|
-| `Primary` | Accent background on active tab (default variant) |
-| `Secondary` | Soft grey background on active tab |
-| `FiveTabs` | Full 5-tab layout matching Figma spec |
-| `WithIcons` | Tabs with Lucide icon prefixes |
+| `Primary` | Active tab with amber/accent background (`primary` variant) |
+| `Secondary` | Active tab with soft grey background (`secondary` variant) |
+| `FiveTabs` | Five-tab layout matching Figma design spec |
+| `WithIcons` | Tabs with Lucide icons (Monitor, Tablet, Smartphone) |
 | `WithLabel` | Optional label rendered above the selector |
-| `WithDisabled` | Single tab disabled via `disabled` item property |
+| `WithDisabled` | Single tab item marked `disabled: true` |
 | `Disabled` | Entire selector disabled via top-level `disabled` prop |
-| `TwoTabs` | Minimal two-tab configuration |
-| `PlatformExample` | Real-world OS platform picker with icons and label |
-| `VariantComparison` | Side-by-side `accent` vs `secondary` rendering |
-| `WithBadges` | Tabs with badge slots (e.g., "Soon" pill on Enterprise) |
+| `TwoTabs` | Minimal two-tab toggle (Enabled / Disabled) |
+| `PlatformExample` | Real-world OS picker with icons and label |
+| `VariantComparison` | Side-by-side primary vs. secondary rendering |
+| `WithBadges` | Tabs with custom badge elements (e.g., "Soon" pill) |
 
 ### `TabSelectorItem` Shape
 
@@ -25,22 +25,23 @@ Storybook stories for the `TabSelector` UI component, showcasing all supported v
 interface TabSelectorItem {
   id: string;
   label: string;
-  icon?: React.ReactNode;
-  disabled?: boolean;
-  badge?: React.ReactNode;
+  icon?: React.ReactNode;       // Optional Lucide or custom icon
+  disabled?: boolean;           // Disables individual tab
+  badge?: React.ReactNode;      // Custom badge element (e.g., "Soon" pill)
 }
 ```
 
 ## Usage Example
 
 ```typescript
-import { TabSelector, type TabSelectorItem } from '../components/ui/tab-selector';
+import { TabSelector, type TabSelectorItem } from '@/components/ui/tab-selector';
 import { useState } from 'react';
+import { Monitor, Apple, Globe } from 'lucide-react';
 
-const platforms: TabSelectorItem[] = [
+const items: TabSelectorItem[] = [
   { id: 'windows', label: 'Windows', icon: <Monitor className="w-5 h-5" /> },
-  { id: 'macos',   label: 'macOS',   icon: <Apple   className="w-5 h-5" /> },
-  { id: 'linux',   label: 'Linux',   icon: <Globe   className="w-5 h-5" />, disabled: true },
+  { id: 'macos',   label: 'macOS',   icon: <Apple className="w-5 h-5" /> },
+  { id: 'linux',   label: 'Linux',   icon: <Globe className="w-5 h-5" />, disabled: true },
 ];
 
 export function PlatformPicker() {
@@ -49,17 +50,11 @@ export function PlatformPicker() {
   return (
     <TabSelector
       label="Select Platform"
-      variant="primary"       // 'primary' | 'secondary'
+      variant="primary"      // 'primary' | 'secondary'
       value={platform}
       onValueChange={setPlatform}
-      items={platforms}
+      items={items}
     />
   );
 }
-```
-
-## Notes
-
-- All stories use a controlled `useState` render function to ensure interactive tab switching works correctly in Storybook.
-- The decorator wraps every story in a `600px` wide container to match typical usage contexts.
-- Badge content accepts any `React.ReactNode`, allowing custom pills, icons, or counters per tab.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.Tag.stories.md b/openframe-frontend-core/src/stories/.Tag.stories.md
index c7df6e22d..d4ad8efc5 100644
--- a/openframe-frontend-core/src/stories/.Tag.stories.md
+++ b/openframe-frontend-core/src/stories/.Tag.stories.md
@@ -1,22 +1,18 @@
-<!-- source-hash: 6142d73d82bfcb3ba377d2f80cb29999 -->
-Storybook stories for the `Tag` UI component, covering all visual variants, icon/close button combinations, disabled states, and composite showcase renders.
+<!-- source-hash: f18130ebfbca951caf39d3dd0646a0a4 -->
+Storybook stories for the `Tag` UI component, showcasing all variants, icon combinations, close button behavior, and disabled states.
 
 ## Key Components
 
 | Export | Description |
 |--------|-------------|
-| `Primary` | Default primary variant |
-| `Outline` | Outline/bordered variant |
-| `Success` / `Warning` / `Error` / `Critical` / `Grey` | Semantic status variants |
-| `WithIcon` | Tag with a leading icon |
-| `WithCloseButton` | Tag with dismissible close handler |
-| `WithIconAndClose` | Tag combining icon and close button |
-| `Disabled` / `AllDisabled` | Disabled state across all variants |
-| `AllVariants` | Showcase of every variant side-by-side |
-| `AllWithIcons` | All variants with icons |
-| `AllWithClose` | All variants with close buttons |
-| `AllWithIconAndClose` | All variants with both icon and close |
-| `DisabledWithIconAndClose` | Disabled state with full feature set |
+| `Primary` | Default amber/primary variant |
+| `Outline` | Outlined style variant |
+| `Success` / `Warning` / `Error` / `Critical` / `Grey` | Semantic color variants |
+| `WithIcon` | Tag with a leading icon slot |
+| `WithCloseButton` | Tag with an `onClose` dismiss handler |
+| `WithIconAndClose` | Combined icon + close button |
+| `Disabled` / `DisabledWithIconAndClose` | Disabled state stories |
+| `AllVariants` / `AllWithIcons` / `AllWithClose` / `AllWithIconAndClose` / `AllDisabled` | Gallery stories rendering every variant side-by-side |
 
 ## Usage Example
 
@@ -28,25 +24,23 @@ import { Smile } from 'lucide-react';
 <Tag variant="success" label="Active" />
 
 // With icon
-<Tag variant="primary" label="Category" icon={<Smile className="size-5" />} />
-
-// Dismissible
-<Tag variant="warning" label="Pending" onClose={() => handleRemove()} />
-
-// Full featured
-<Tag
-  variant="error"
-  label="Failed"
-  icon={<Smile className="size-5" />}
-  onClose={() => handleRemove()}
-  disabled={false}
-/>
+<Tag variant="primary" label="Label" icon={<Smile className="size-5" />} />
+
+// With close handler
+<Tag variant="warning" label="Pending" onClose={() => removeTag(id)} />
+
+// Disabled
+<Tag variant="error" label="Inactive" disabled />
 ```
 
 ## Variants
 
-The `Tag` component supports 7 variants controlled via the Storybook `select` control:
-
-```text
-primary | outline | success | warning | error | critical | grey
-```
\ No newline at end of file
+| Variant | Use Case |
+|---------|----------|
+| `primary` | General purpose / default |
+| `outline` | Subtle / secondary emphasis |
+| `success` | Positive / completed state |
+| `warning` | Cautionary state |
+| `error` | Non-critical failure |
+| `critical` | High-priority alert |
+| `grey` | Neutral / inactive |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.TicketInfoSection.stories.md b/openframe-frontend-core/src/stories/.TicketInfoSection.stories.md
index 4e6122b88..c943fc09f 100644
--- a/openframe-frontend-core/src/stories/.TicketInfoSection.stories.md
+++ b/openframe-frontend-core/src/stories/.TicketInfoSection.stories.md
@@ -1,40 +1,47 @@
-<!-- source-hash: 82f8ca355b8119e08afe608bf0b4cf05 -->
-Storybook stories for the `TicketInfoSection` component, covering collapsed, expanded, interactive, and minimal display states of the collapsible ticket info bar.
+<!-- source-hash: 9c86c7c558b8e84471d042872e05ba8a -->
+Storybook stories for the `TicketInfoSection` component, covering collapsed, expanded, interactive, and minimal states of the collapsible ticket info bar.
 
 ## Key Components
 
-- **`Collapsed`** — Default header-only view showing organization, user, device, and status fields
-- **`Expanded`** — Fully populated view with description, attachments, tags, knowledge base articles, and notes
-- **`Interactive`** — Stateful story demonstrating expand/collapse toggle with `useState`, device click handler, and note CRUD callbacks
-- **`Minimal`** — Expanded state with all fields set to "Unassigned", useful for empty-state validation
+- **`Collapsed`** — Default header-only view showing organization, user, device, and status fields without expanded content
+- **`Expanded`** — Fully populated state including assignee selector, description, attachments, tags, and notes
+- **`Interactive`** — Stateful story using `useState` to demonstrate real expand/collapse toggling with all note CRUD handlers wired
+- **`Minimal`** — Expanded state with all fields set to "Unassigned", useful for empty/default data validation
 
 ## Usage Example
 
 ```typescript
+// Interactive expand/collapse with full data
 import { TicketInfoSection } from '../components/ui/ticket-info-section';
+import { useState } from 'react';
+import { Monitor } from 'lucide-react';
 
-// Basic collapsed header
-<TicketInfoSection
-  organization={{ name: 'Acme Corp' }}
-  user="John Doe"
-  device={{ name: 'WIN-SERVER-01', icon: <Monitor className="size-4" /> }}
-  status="TECH_REQUIRED"
-  expanded={false}
-/>
+function Example() {
+  const [expanded, setExpanded] = useState(false);
 
-// Expanded with notes and attachments
-<TicketInfoSection
-  organization={{ name: 'Acme Corp' }}
-  user="John Doe"
-  device={{ name: 'WIN-SERVER-01' }}
-  status="ACTIVE"
-  expanded={true}
-  notes={mockNotes}
-  attachments={mockAttachments}
-  knowledgeBaseArticles={mockArticles}
-  tags={['Client-onboarding']}
-  onAddNote={(text) => console.log('Add note:', text)}
-  onEditNote={(id) => console.log('Edit note:', id)}
-  onDeleteNote={(id) => console.log('Delete note:', id)}
-/>
-```
\ No newline at end of file
+  return (
+    <TicketInfoSection
+      organization={{ name: 'Acme Corp' }}
+      user="John Doe"
+      device={{ name: 'WIN-SERVER-01', icon: <Monitor className="size-4" /> }}
+      status="ACTIVE"
+      expanded={expanded}
+      onExpand={() => setExpanded(prev => !prev)}
+      assigned={{
+        currentAssignee: { id: 'u1', name: 'Roman Smith' },
+        options: [{ value: 'u1', label: 'Roman Smith' }],
+        onAssign={(userId) => console.log('Assigned to', userId)}
+      }}
+      createdAt="2025/07/12, 22:27"
+      description="Ticket description here."
+      tags={['urgent', 'production']}
+      notes={[]}
+      onAddNote={(text) => console.log('New note:', text)}
+      onEditNote={(id) => console.log('Edit:', id)}
+      onDeleteNote={(id) => console.log('Delete:', id)}
+    />
+  );
+}
+```
+
+> **Note:** The `Interactive` story is the primary reference for wiring expand/collapse state — all other stories use static `expanded` props for snapshot/visual testing purposes.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/.Toaster.stories.md b/openframe-frontend-core/src/stories/.Toaster.stories.md
index d50505866..02beb4c88 100644
--- a/openframe-frontend-core/src/stories/.Toaster.stories.md
+++ b/openframe-frontend-core/src/stories/.Toaster.stories.md
@@ -1,40 +1,44 @@
-<!-- source-hash: 8385ab6a043167836b17b6b41deb0581 -->
-Storybook stories for the `Toaster` / `ToastCard` component system, covering static previews, interactive playground, command-approval flows, and live Sonner-powered triggers.
+<!-- source-hash: 0ce97edfd86f7e149fbf7c04ced76c89 -->
+Storybook stories for the `Toaster` component system, providing interactive and static previews of toast notification variants, command approval flows, and live trigger behavior.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `AllVariants` | Story | Static grid of every `ToastVariant` (`default`, `success`, `warning`, `error`, `info`) plus edge cases (title-only, description-only, non-dismissible, persistent) |
-| `Playground` | Story | Arg-driven interactive card — use Storybook Controls to tweak `variant`, `title`, `description`, `duration`, and `dismissible` |
-| `CommandApprovalCollapsed` | Story | `CommandApprovalToast` in its default collapsed state |
-| `CommandApprovalExpanded` | Story | `CommandApprovalToast` with `defaultExpanded` showing the command preview and Approve/Reject actions |
-| `CommandApprovalPerTool` | Story | One expanded approval toast per supported tool type (`FLEET_MDM`, `TACTICAL_RMM`, `MESHCENTRAL`, `AUTHENTIK`, `OSQUERY`, `OPENFRAME`) to verify icon mapping |
-| `CommandApprovalLive` | Story | Fires real Sonner toasts via `showCommandApprovalToast()` with `onApprove`/`onReject` callbacks |
-| `LiveTriggers` | Story | Button panel that fires every variant as a live Sonner toast using both `toast()` and `showToast()` |
+| `AllVariants` | `Story` | Static grid of all `ToastCard` variant states (default, success, warning, error, info) plus edge cases |
+| `Playground` | `Story` | Interactive args-driven preview; tweak variant, title, description, duration, and dismissible via Storybook controls |
+| `CommandApprovalCollapsed` | `Story` | Command approval toast in its collapsed (header-only) state |
+| `CommandApprovalExpanded` | `Story` | Command approval toast with details panel pre-opened via `defaultExpanded` |
+| `CommandApprovalPerTool` | `Story` | Renders one approval toast per supported tool type to verify icon mapping (Fleet MDM, TacticalRMM, MeshCentral, Authentik, osquery, OpenFrame) |
+| `CommandApprovalLive` | `Story` | Fires real Sonner command approval toasts with `onApprove` / `onReject` callbacks |
+| `LiveTriggers` | `Story` | Buttons that invoke `toast()` and `showToast()` at runtime, covering all variants and edge cases |
 
 ## Usage Example
 
 ```typescript
-// Render once near your app root
+// Render the Toaster once near your app root
 import { Toaster } from '@/components/ui/toaster';
-<Toaster />
+export default function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <Toaster />
+    </>
+  );
+}
 
-// Fire a standard toast from anywhere
-import { toast } from '@/hooks/use-toast';
-toast({ variant: 'success', title: 'Saved', description: 'All changes committed.' });
-
-// Fire a command-approval toast requiring tech sign-off
+// Fire a toast from anywhere
+import { showToast } from '@/components/ui/toaster';
 import { showCommandApprovalToast } from '@/components/ui/toaster';
+
+showToast({ variant: 'success', title: 'Saved', description: 'Changes applied.' });
+
 showCommandApprovalToast({
   title: 'Tech Required',
-  description: 'Approval is required to execute the command.',
-  command: 'fleetctl query --hosts mac-* "SELECT * FROM system_info"',
-  toolType: ToolTypeValues.FLEET_MDM,
-  approvalDescription: 'Queries system info across all macOS endpoints.',
-  onApprove: () => toast({ variant: 'success', title: 'Command approved' }),
-  onReject:  () => toast({ variant: 'error',   title: 'Command rejected' }),
+  description: 'Approval required to execute.',
+  command: 'fleetctl query --hosts mac-*',
+  toolType: 'fleet_mdm',
+  onApprove: () => console.log('approved'),
+  onReject: () => console.log('rejected'),
 });
-```
-
-> **Note:** `<Toaster />` must be mounted in the render tree for live stories (`CommandApprovalLive`, `LiveTriggers`) — both stories include it inline so the Storybook canvas is self-contained.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/__fixtures__/.chat-card-decorator.md b/openframe-frontend-core/src/stories/__fixtures__/.chat-card-decorator.md
new file mode 100644
index 000000000..164c530f3
--- /dev/null
+++ b/openframe-frontend-core/src/stories/__fixtures__/.chat-card-decorator.md
@@ -0,0 +1,37 @@
+<!-- source-hash: 2dd85c4676b5b84547c130a41316a737 -->
+Storybook decorator and helper utilities for rendering chat entity-card stories in an isolated, realistic context without the full chat runtime.
+
+## Key Components
+
+**`ChatColumnDecorator`** — A React wrapper component that reproduces the assistant message column layout (constrained `max-w-[420px]`, chat background `bg-ods-bg`, ODS padding). Use this as a Storybook decorator to preview entity-cards at their real rendered width.
+
+**`makeAnchorProps`** — Factory function that builds the `{ href, onClick }` pair expected by card inner `<a>` elements. The `onClick` calls `preventDefault` to prevent iframe navigation in Storybook while preserving anchor semantics (hover, copy-link, etc.).
+
+## Usage Example
+
+```typescript
+import { ChatColumnDecorator, makeAnchorProps } from './chat-card-decorator'
+import type { Meta, StoryObj } from '@storybook/react'
+import { TicketCard } from './ticket-card'
+
+const meta: Meta<typeof TicketCard> = {
+  component: TicketCard,
+  decorators: [
+    (Story) => (
+      <ChatColumnDecorator>
+        <Story />
+      </ChatColumnDecorator>
+    ),
+  ],
+}
+export default meta
+
+export const Default: StoryObj<typeof TicketCard> = {
+  args: {
+    title: 'Printer not working',
+    anchorProps: makeAnchorProps('https://example.com/tickets/42'),
+  },
+}
+```
+
+> The decorator targets the assistant message column width (`420px`) so card stories reflect their true production layout without spinning up the dispatch pipeline or chat runtime.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/stories/__fixtures__/.chat-cards.md b/openframe-frontend-core/src/stories/__fixtures__/.chat-cards.md
new file mode 100644
index 000000000..141c21543
--- /dev/null
+++ b/openframe-frontend-core/src/stories/__fixtures__/.chat-cards.md
@@ -0,0 +1,53 @@
+<!-- source-hash: ea192ba8b81881945199a19aa584fd9c -->
+Shared fixtures providing typed mock data for all chat entity-card Storybook stories, covering every `docType` in `CHAT_CARD_REGISTRY` without requiring the chat runtime.
+
+## Key Components
+
+### Constants & Helpers
+- `NOW` / `DAY` — baseline timestamp and day offset for relative dates
+- `isoDaysAgo(days)` — returns an ISO string N days before the fixture baseline
+- `SAMPLE_AUTHOR` — reusable author object (name, avatar, job title)
+
+### Exported Fixtures
+
+| Export | Type | Description |
+|---|---|---|
+| `githubCommitItem` | `GitHubActivityItem` | Sample commit activity |
+| `githubPullRequestItem` | `GitHubActivityItem` | Sample PR activity |
+| `githubPrReviewItem` | `GitHubActivityItem` | Sample PR review |
+| `slackMessageItem` | `SlackMessageItem` | Sample Slack message |
+| `hubspotTicketItem` | `HubspotTicketItem` | HIGH priority in-progress ticket |
+| `dataRoomDocItem` | `DataRoomDocCardItem` | Board deck document |
+| `openframeDocsMarkdownItem` | `DataRoomDocCardItem` | Knowledge base article |
+| `financialKpiItem` | `GenericEntityCardItem` | ARR KPI snapshot |
+| `capTableItem` | `GenericEntityCardItem` | SAFE instrument entry |
+| `profitLossItem` | `GenericEntityCardItem` | Q1 P&L summary |
+| `balanceSheetItem` | `GenericEntityCardItem` | Month-end balance sheet |
+| `cashFlowItem` | `GenericEntityCardItem` | Q1 cash flow summary |
+| `blogPostSummary` | `BlogPostSummary` | Engineering blog post |
+| `caseStudy` | `CaseStudy` | MSP consolidation case study |
+| `customerInterview` | `CustomerInterview` | Video interview fixture |
+
+## Usage Example
+
+```typescript
+import {
+  githubCommitItem,
+  hubspotTicketItem,
+  financialKpiItem,
+  blogPostSummary,
+} from '@/stories/fixtures/chat-cards'
+
+// Storybook story
+export const HubSpotTicketCard: Story = {
+  args: {
+    item: hubspotTicketItem,
+    href: hubspotTicketItem.url,
+  },
+}
+
+// Multiple cards preview
+const allItems = [githubCommitItem, hubspotTicketItem, financialKpiItem]
+```
+
+> **Note:** Server-only fields (status timestamps, AI flags, view counts) are populated with type-correct placeholders. These values are not read at render time but are required by the wire types.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/types/.product-release.md b/openframe-frontend-core/src/types/.product-release.md
index f1e558aa7..06cced264 100644
--- a/openframe-frontend-core/src/types/.product-release.md
+++ b/openframe-frontend-core/src/types/.product-release.md
@@ -1,82 +1,60 @@
-<!-- source-hash: 5a845a31a46ea7c6d1945d44c5a712fa -->
-Defines the complete TypeScript type system for the Flamingo product release module, including data shapes for releases, changelog entries, media assets, and external integrations (GitHub, ClickUp, Knowledge Base).
+<!-- source-hash: eba113d69dbb594003cdf1eced15e5ee -->
+Defines all TypeScript types, interfaces, and constants for the Flamingo product release system, modeling release metadata, changelog entries, media assets, external integrations, and filtering options.
 
 ## Key Components
 
-### Core Interfaces
+### Interfaces
 
 | Interface | Purpose |
 |-----------|---------|
-| `ProductRelease` | Primary entity — full release record with video, SEO, AI, analytics, and relation fields |
-| `ChangelogEntry` | Single changelog item with optional per-entry `visibility` (supports investor update use case) |
-| `ReleaseMedia` | Attached media assets (`image`, `video`, `screenshot`, `demo`) |
-| `CreateProductReleaseData` | Input shape for creating a new release |
-| `UpdateProductReleaseData` | Partial version of create data for updates |
-| `ProductReleaseFilters` | Query filter bag for list endpoints (pagination, tags, type, status, search) |
+| `ProductRelease` | Core entity with versioning, changelog arrays, video/media fields, AI confidence scores, SEO, and hydrated relations |
+| `ChangelogEntry` | Single changelog item with optional per-entry `visibility` flag (`public` \| `internal`) |
+| `ReleaseMedia` | Attached media assets (image, video, screenshot, demo) |
+| `ProductReleaseGitHubLink` | Links to GitHub release tags |
+| `KnowledgeBaseLink` | References to KB article paths |
+| `ClickUpRoadmapTask` / `ClickUpDeliveryTask` | ClickUp task associations from roadmap and delivery lists |
+| `CreateProductReleaseData` | Input shape for creating a release |
+| `UpdateProductReleaseData` | Partial of create shape for updates |
+| `ProductReleaseFilters` | Query filter options (platform, tags, type, status, pagination) |
 | `ProductReleaseListResponse` | Paginated list response wrapper |
+| `GitHubRelease` | GitHub release shape used in the release wizard |
 
-### External Link Interfaces
+### Constants
 
-| Interface | Links To |
-|-----------|---------|
-| `ProductReleaseGitHubLink` | GitHub release URLs |
-| `KnowledgeBaseLink` | Internal KB article paths |
-| `ClickUpRoadmapTask` | ClickUp roadmap task IDs |
-| `ClickUpDeliveryTask` | ClickUp delivery list task IDs |
-| `GitHubRelease` | GitHub API release shape (wizard import) |
-
-### Constants & Utilities
-
-- `releaseTypeOptions` — dropdown metadata for `major`, `minor`, `patch`, `beta`, `alpha`
-- `releaseStatusOptions` — dropdown metadata for `alpha`, `beta`, `stable`, `deprecated`
-- `changelogLabels` — human-readable labels for changelog categories
-- `SEMVER_REGEX` — validates semantic versioning strings including pre-release and build metadata
+| Export | Purpose |
+|--------|---------|
+| `releaseTypeOptions` | Dropdown options for `major`, `minor`, `patch`, `beta`, `alpha` with colors |
+| `releaseStatusOptions` | Dropdown options for `alpha`, `beta`, `stable`, `deprecated` with colors |
+| `changelogLabels` | Human-readable labels for changelog JSONB categories |
+| `SEMVER_REGEX` | Validates semantic versioning strings (e.g., `2.1.0-beta+build.1`) |
 
 ## Usage Example
 
 ```typescript
-import type {
-  ProductRelease,
-  CreateProductReleaseData,
-  ProductReleaseFilters,
-  ChangelogEntry,
-} from './product-release'
+import type { ProductRelease, ChangelogEntry, ProductReleaseFilters } from './product-release'
 import { releaseTypeOptions, SEMVER_REGEX } from './product-release'
 
-// Validate version before submission
-const version = '2.1.0-beta.1'
-if (!SEMVER_REGEX.test(version)) {
-  throw new Error(`Invalid semver: ${version}`)
-}
+// Validate a version string
+const isValid = SEMVER_REGEX.test('2.1.0-beta') // true
 
-// Build a new release payload
-const newRelease: CreateProductReleaseData = {
-  title: 'OpenFrame 2.1 Beta',
-  slug: 'openframe-2-1-beta',
-  version,
-  release_type: 'beta',
-  release_status: 'beta',
-  release_date: '2025-07-01',
-  status: 'draft',
-  author_id: 'user-uuid',
-  platforms: ['platform-uuid-1'],
-  tags: [1, 4],
-  features_added: [
-    { title: 'Mingo AI ticket routing', visibility: 'public' },
-    { title: 'Internal billing dashboard', visibility: 'internal' },
-  ] satisfies ChangelogEntry[],
+// Type a changelog entry with visibility control
+const entry: ChangelogEntry = {
+  title: 'Added OAuth2 SSO support',
+  description: 'Supports Google and Microsoft providers',
+  visibility: 'public'
 }
 
-// Filter releases for a public changelog page
+// Build a filter query
 const filters: ProductReleaseFilters = {
-  release_status: ['stable', 'beta'],
+  platform: 'openframe',
+  release_type: ['major', 'minor'],
+  release_status: ['stable'],
   has_breaking_changes: false,
-  status: 'published',
   limit: 20,
-  offset: 0,
+  offset: 0
 }
 
-// Access dropdown labels for a form
-const typeLabel = releaseTypeOptions.find(o => o.value === 'beta')?.label
-// → 'Beta Release'
+// Access type metadata for UI
+const typeLabel = releaseTypeOptions.find(o => o.value === 'major')?.label
+// → "Major Release"
 ```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.cn.md b/openframe-frontend-core/src/utils/.cn.md
index 79f144e3a..cef8baa06 100644
--- a/openframe-frontend-core/src/utils/.cn.md
+++ b/openframe-frontend-core/src/utils/.cn.md
@@ -1,44 +1,41 @@
-<!-- source-hash: c1693a304ddf9b29bde0ca02b6f6b8ea -->
-Utility module providing class name merging with extended Tailwind support, and platform URL resolution helpers for multi-tenant Flamingo/OpenFrame deployments.
+<!-- source-hash: 6a6f6a3f4f7ef709fefb0984ff1f4a1d -->
+Utility module providing class name merging with custom Tailwind typography extensions, and environment-aware URL resolution for Flamingo platform deployments.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `cn` | Function | Merges class names using `clsx` + `tailwind-merge`, extended with custom ODS typography classes (`text-h1`–`text-h6`) |
-| `getPlatformProductionUrl` | Function | Returns the production URL for a named platform, with `NEXT_PUBLIC_*` env var override support |
-| `getAllPlatformBaseDomains` | Function | Extracts all unique base domains across platforms; handles localhost, Vercel preview, and production cases (useful for cross-domain cookie scope) |
-| `getBaseUrl` | Function | Resolves the current app's base URL using a priority chain: env override → platform URL → Vercel domain → production fallback → `localhost:3000` |
+- **`cn(...inputs)`** — Merges class names using `clsx` + a custom `tailwind-merge` instance extended with ODS typography classes (`text-h1` through `text-h6`).
+- **`getPlatformProductionUrl(platform)`** — Returns the production URL for a named platform, with support for `NEXT_PUBLIC_*` environment variable overrides.
+- **`getAllPlatformBaseDomains()`** — Extracts all unique base domains from known platforms; handles localhost, Vercel preview, and production cases (useful for cross-domain cookie scoping).
+- **`getBaseUrl(platform?)`** — Resolves the application base URL for the current environment, respecting dev/preview/production context and optional platform targeting.
 
 ## Usage Example
 
 ```typescript
-import { cn, getBaseUrl, getPlatformProductionUrl, getAllPlatformBaseDomains } from '@/lib/cn'
+import { cn, getBaseUrl, getPlatformProductionUrl } from '@/lib/cn'
 
-// Merge Tailwind classes (including custom ODS typography)
-const className = cn('text-h1 font-bold', isActive && 'text-yellow-400')
+// Merge Tailwind classes (deduplicates conflicting utilities)
+const classes = cn('text-h1 font-bold', isActive && 'text-amber-400')
 
-// Resolve current app base URL
-const apiBase = getBaseUrl()                      // http://localhost:3000 (dev)
-                                                  // https://www.openmsp.ai (prod fallback)
+// Resolve URL for current environment
+const appUrl = getBaseUrl()                    // http://localhost:3000 (dev)
+const flamingoUrl = getBaseUrl('flamingo')     // https://www.flamingo.run (prod)
+const openframeUrl = getBaseUrl('openframe')   // https://openframe.ai (prod)
 
-// Resolve a specific platform URL (respects NEXT_PUBLIC_* overrides)
-const flamingoUrl = getBaseUrl('flamingo')        // https://www.flamingo.run
-const openframeUrl = getPlatformProductionUrl('openframe') // https://openframe.ai
+// Get a platform URL directly (always production, with env override)
+const dashboardUrl = getPlatformProductionUrl('openframe-dashboard')
+// → process.env.NEXT_PUBLIC_OPENFRAME_DASHBOARD_URL || 'https://openframe.ai'
 
-// Get all cookie-scoped base domains (e.g. for document.cookie domain=)
+// Get all cookie-scoped domains (e.g. for cross-platform auth)
 const domains = getAllPlatformBaseDomains()
-// Production: ['.flamingo.run', 'flamingo.run', '.openmsp.ai', 'openmsp.ai', ...]
-// Vercel preview: ['.vercel.app', 'vercel.app']
-// Localhost: []
+// → ['.flamingo.run', 'flamingo.run', '.openmsp.ai', 'openmsp.ai', ...]
 ```
 
-## Environment Variables
+## Platform Identifiers
 
-| Variable | Platform | Default |
-|----------|----------|---------|
-| `NEXT_PUBLIC_FLAMINGO_URL` | `flamingo`, `universal` | `https://www.flamingo.run` |
-| `NEXT_PUBLIC_OPENMSP_URL` | `openmsp` | `https://www.openmsp.ai` |
-| `NEXT_PUBLIC_OPENFRAME_URL` | `openframe` | `https://openframe.ai` |
-| `NEXT_PUBLIC_MARKETING_HUB_URL` | `marketing-hub` | `https://marketing-hub.flamingo.so` |
-| `NEXT_PUBLIC_DEV_URL` | all (dev only) | `http://localhost:3000` |
\ No newline at end of file
+| Identifier | Default URL |
+|---|---|
+| `flamingo` | `https://www.flamingo.run` |
+| `openframe` | `https://openframe.ai` |
+| `openmsp` | `https://www.openmsp.ai` |
+| `marketing-hub` | `https://marketing-hub.flamingo.so` |
+| `openframe-dashboard` | `https://openframe.ai` |
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.content-href.md b/openframe-frontend-core/src/utils/.content-href.md
new file mode 100644
index 000000000..f8bd2feb7
--- /dev/null
+++ b/openframe-frontend-core/src/utils/.content-href.md
@@ -0,0 +1,56 @@
+<!-- source-hash: 451492ba0893d221a9e5a3a1ae9138cb -->
+Unified content-href authority for all embeddable surfaces — resolves content links consistently across page views and chat surfaces using a single configurable seam.
+
+## Key Components
+
+**`DEFAULT_CONTENT_SUFFIXES`** — Maps content `documentType` keys (e.g. `product_release`) to URL path segments (e.g. `releases`). Embedder default; kept manually in sync with the hub's `PUBLIC_URL_PATHS`.
+
+**`ComposeContentUrlInput`** — Shared input shape for both callers: page views (pass `type` + slug as `identifier`) and chat rows (pass `type` + primary-key `identifier` + `externalUrl` for slug recovery).
+
+**`ContentHrefOptions`** — Config for `makeComposeContentUrl`: `hostedTypes` (in-app soft-nav set), `contentOrigin` (fallback hub origin), optional `suffixes` override, and per-type `overrides`.
+
+**`makeComposeContentUrl(opts)`** — Builds the embedder's `composeContentUrl` function. Resolution order:
+1. `overrides[type]` — explicit per-type href
+2. `hostedTypes` member → relative `/<suffix>/<slug>` (soft-nav)
+3. `externalUrl` present → use verbatim (RAG-authoritative)
+4. Fallback → `${contentOrigin}/<suffix>/<identifier>`
+
+**`buildDefaultHref(basePath, slug)`** — Single-platform fallback when no composer is wired.
+
+**`resolveContentHref(composeContentUrl, args)`** — Centralizes the composer-vs-fallback ternary used by every catalog/detail view.
+
+## Usage Example
+
+```typescript
+// Wire the embedder's composer (e.g. in ChatRuntime setup)
+const composeContentUrl = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: 'https://openframe.app',
+  overrides: {
+    webinar: (id) => ({ href: `/live/${id}`, targetPlatform: null }),
+  },
+})
+
+// Page view — slug passed directly
+composeContentUrl({ type: 'product_release', identifier: 'my-release' })
+// → { href: '/releases/my-release', targetPlatform: null }
+
+// Chat row — slug recovered from hub URL
+composeContentUrl({
+  type: 'product_release',
+  identifier: '42',
+  externalUrl: 'https://openframe.app/releases/my-release',
+})
+// → { href: '/releases/my-release', targetPlatform: null }
+
+// Non-hosted type — opens out to hub
+composeContentUrl({ type: 'blog_post', identifier: 'some-post' })
+// → { href: 'https://openframe.app/blog/some-post', targetPlatform: null }
+
+// In a catalog/detail view — handles missing composer gracefully
+resolveContentHref(composeContentUrl, {
+  type: 'onboarding_guide',
+  slug: 'getting-started',
+  basePath: '/onboarding-guides',
+})
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.embed-authed-fetch.md b/openframe-frontend-core/src/utils/.embed-authed-fetch.md
index 692f7f4e9..586e06960 100644
--- a/openframe-frontend-core/src/utils/.embed-authed-fetch.md
+++ b/openframe-frontend-core/src/utils/.embed-authed-fetch.md
@@ -1,46 +1,50 @@
-<!-- source-hash: 585108e1683f75548fc4f177781fa0c8 -->
-A client-side `fetch` wrapper for embedded surfaces (chat, ticket center, widgets) that automatically attaches bearer-act-as proxy authentication headers from `sessionStorage` while enforcing same-origin security.
+<!-- source-hash: 3eed3430713683512d97b9b4d8553fba -->
+Shared `fetch` wrapper for embedded surfaces (chat, ticket center, widgets) that automatically attaches bearer-act-as proxy authentication headers and supports optional host-supplied auth adapters with 401 self-healing.
 
 ## Key Components
 
-### `embedAuthedFetch(url, init?)`
-Drop-in replacement for `fetch()` that:
-- Normalizes `RequestInit.headers` (handles `Headers` instance, tuple arrays, or plain objects) into `Record<string, string>`
-- Delegates to `applyProxyAuth` to merge `Authorization` and `X-Chat-Act-As` headers — **proxy credentials always win** over caller-supplied headers
-- Defaults `Content-Type: application/json` when no headers are provided
-- Forces `credentials: 'same-origin'` to ensure Supabase auth cookies are included alongside bearer tokens
-- **Self-heals on `401`** when a host registered an `EmbedAuthAdapter` with a `refresh` callback: calls `refresh()` once, and on success retries the same request a single time with freshly-recomputed headers (so a rotated bearer is picked up). Concurrent 401s share ONE refresh. With no adapter / no `refresh`, the 401 passes through unchanged.
-
-### `setEmbedAuthAdapter(adapter | null)` + `EmbedAuthAdapter`
-Optional host-owned auth override registered at module level (one chat panel per app). The adapter can supply:
-- `getHeaders()` — headers merged onto every call AFTER proxy-auth (adapter wins), re-read per request so token rotation is seen
-- `credentials` — overrides the default `'same-origin'` (e.g. `'include'` for cross-origin cookie auth)
-- `refresh()` — `Promise<boolean>` 401 self-heal hook (see above). This lifts the openframe `apiClient`'s refresh-then-retry behaviour into the lib so embedded surfaces no longer need a host-side `window.fetch` monkey-patch to survive an expired token mid-session.
-
-### `assertSameOrigin(url)` *(internal)*
-Defense-in-depth guard that:
-- Resolves all URL forms (relative, absolute, protocol-relative, whitespace-prefixed) against `window.location.href` via the WHATWG `URL` constructor — bypasses regex shortcuts vulnerable to `\t`/`\n` prefix tricks
-- Blocks non-`http(s):` schemes explicitly (`javascript:`, `data:`, `blob:`, etc.)
-- Throws on cross-origin destinations before any bearer token leaves the page
-- Skips silently during SSR (`typeof window === 'undefined'`)
+### `EmbedAuthAdapter` (interface)
+Opt-in auth adapter interface for hosts with custom auth models (e.g., OpenFrame JWT, OAuth tokens). Exposes:
+- `getHeaders()` — returns per-request headers merged over proxy defaults
+- `credentials` — overrides the default `'same-origin'` credentials mode
+- `refresh()` — optional 401 self-heal callback; resolves `true` to trigger a single retry with refreshed headers
+
+### `setEmbedAuthAdapter(adapter)`
+Registers (or clears) a host-owned auth adapter at module level. Stored on `globalThis` to survive bundler chunk duplication. Warns in dev if overwriting an existing registration.
+
+### `embedAuthedFetch(url, init)`
+Drop-in `fetch` replacement that:
+- Enforces same-origin URLs synchronously (throws on cross-origin to prevent bearer leakage)
+- Merges proxy-auth headers via `applyProxyAuth` (proxy values win over caller headers)
+- Defaults to `Content-Type: application/json` when no headers are provided
+- Triggers `dedupedRefresh()` + single retry on `401` when an adapter with `refresh` is registered
+
+### `dedupedRefresh()`
+Deduplicates concurrent 401 refresh attempts via a `globalThis`-scoped in-flight promise — ensures at most one refresh call fires per expiry cycle regardless of how many requests 401 simultaneously.
 
 ## Usage Example
 
 ```typescript
-// JSON POST to chat API — proxy headers attached automatically
+// Basic usage — proxy auth applied automatically
 const res = await embedAuthedFetch('/api/chat/messages', {
   method: 'POST',
   body: JSON.stringify({ message: 'Hello' }),
 })
 
-// GET with explicit empty headers — skips Content-Type default
-const upload = await embedAuthedFetch('/api/storage/generate-upload-url', {
-  method: 'GET',
-  headers: {},
+// Register a host adapter (e.g., OpenFrame JWT + cross-origin cookies)
+setEmbedAuthAdapter({
+  getHeaders: () => ({
+    Authorization: token ? `Bearer ${token}` : undefined,
+  }),
+  credentials: 'include',
+  refresh: async () => {
+    const ok = await refreshAccessToken()
+    return ok
+  },
 })
 
-// Vanilla fetch — use for routes that don't need bearer-act-as
-const profile = await fetch('/api/profile/me', { credentials: 'same-origin' })
+// Clear on provider unmount
+setEmbedAuthAdapter(null)
 ```
 
-> Routes outside the `/api/chat/*`, `/api/docs/chat/*`, or `/api/storage/generate-upload-url` surfaces should use vanilla `fetch` — this wrapper is scoped to embedded auth contexts only.
\ No newline at end of file
+> **Note:** Use `embedAuthedFetch` only for routes requiring bearer-act-as identity (`/api/chat/*`, `/api/docs/chat/*`, `/api/storage/generate-upload-url`). Routes like `/api/profile/me` should use vanilla `fetch`.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.index.md b/openframe-frontend-core/src/utils/.index.md
index a2b6cf498..a286ce1e3 100644
--- a/openframe-frontend-core/src/utils/.index.md
+++ b/openframe-frontend-core/src/utils/.index.md
@@ -1,49 +1,67 @@
-<!-- source-hash: a199bfb2e9675c73161c9b56f81904f7 -->
-Barrel export index for the `utils` package, re-exporting all utility functions, types, and constants from their canonical source files to provide a single stable import path for consumers across the frontend library and hub.
+<!-- source-hash: fb239d150a07bb69832e5ee5fe61948e -->
+Barrel (index) file that re-exports the full public utility API for `@flamingo-stack/openframe-frontend-core/utils`, aggregating client-side helpers, formatters, platform config, chat utilities, and server-safe pure functions into a single import surface.
 
 ## Key Components
 
-| Export Group | Source | Description |
+| Export Group | Source Module | Description |
 |---|---|---|
-| `cn`, `getAllPlatformBaseDomains`, `getBaseUrl`, `getPlatformProductionUrl` | `./cn` | CSS class merging and platform URL helpers |
-| `formatDate`, `formatNumber`, `formatPrice`, `formatBytes`, `formatCurrency`, `formatPercent`, etc. | `./format` | Number, currency, byte, date, and metric formatters |
-| `getPlatformAccentColor`, `getCurrentPlatform` | `./ods-color-utils` | Platform theming and color utilities |
-| `getDynamicIcon`, `ICON_REGISTRY`, `getIconComponent` | `chat/utils/icon-registry` | Dynamic icon registry |
-| `embedAuthedFetch`, `getEmbedProxyAuth`, `setEmbedProxyAuth` | `./embed-*` | Embed-surface authentication helpers |
-| `formatRelativeTime`, `formatAbsoluteDate`, `isToday`, `createUTCTimestamp` | `./date-utils` | Date/time formatting and comparison |
-| `escapeMarkdownInline`, `buildChatAttachmentViewUrl` | `chat/utils/chat-attachment-markdown` | Chat attachment markdown helpers |
+| `cn`, `getAllPlatformBaseDomains` | `./cn` | Class name merging + domain helpers |
+| `formatDate`, `formatNumber`, `formatPrice`, `formatBytes` | `./format` | Core number/currency/byte/date formatters |
+| `getPlatformAccentColor`, `getCurrentPlatform` | `./ods-color-utils` | ODS design token color utilities |
+| `delay`, `generateRandomString`, `truncateString`, `deepClone` | `./common` | General-purpose helpers |
+| `getBaseUrl`, `getPlatformProductionUrl` | `../utils/cn` | Environment URL resolvers |
+| `getDynamicIcon`, `ICON_REGISTRY`, `getIconComponent` | `../components/chat/utils/icon-registry` | Dynamic icon registry |
+| `embedAuthedFetch`, `setEmbedAuthAdapter` | `./embed-authed-fetch` | Embed-surface auth fetch wrapper |
+| `getEmbedProxyAuth`, `setEmbedProxyAuth` | `./embed-proxy-auth-storage` | Proxy auth storage (cross-surface) |
+| `readLeadingDecisionFrame` | `./sse-decision-frame` | SSE leading-frame reader for confirm-tool route |
+| `escapeMarkdownInline`, `buildChatAttachmentViewUrl` | `../components/chat/utils/chat-attachment-markdown` | Chat attachment markdown helpers |
 | `scrollElementIntoView` | `./scroll-into-view` | Smooth scroll with sticky-chrome offset |
-| `readLeadingDecisionFrame` | `./sse-decision-frame` | SSE frame reader for confirm-tool route |
-| `isCrossOriginUrl` | `chat/utils/is-cross-origin-url` | Cross-origin URL detection (server-safe) |
+| `buildListUrl` | `./list-url` | Shared list-API URL builder for RAG mappers |
+| `makeComposeContentUrl`, `buildDefaultHref` | `./content-href` | Embedder-configurable content-URL composer |
+| `formatLargeNumber`, `formatCurrency`, `formatPercent`, `getTrendColors` | `./format` | Extended metric/trend/text formatters |
+| `formatRelativeTime`, `formatAbsoluteDate`, `isToday` | `./date-utils` | Relative/absolute date helpers |
+| `SOURCE_ICON_NAMES`, `getSourceLabel` | `./source-icons` | Chat source icons and labels (server-safe) |
+| `CUSTOM_ITEM_ID`, `getTaskTypeLabel` | `../components/chat/utils/clickup-task-type-utils` | ClickUp taxonomy constants (server-safe) |
+| `fetchPriorityProp` | `./fetch-priority` | React 18/19 `fetchpriority` prop builder |
+| `DEV_SECTION_PARAM_KEYS` | `./dev-sections/dev-section-param-keys` | Dev-center URL param key constants |
+
+Also re-exports full namespaces: `platform-config`, `os-platforms`, `access-code-client`, `validation-utils`, `confidence-helpers`, `date-formatters`, `release-badge`, `release-cover`, `tool-utils`, `shell-utils`, `os-utils`, `country-phone-utils`, `generic-domain-utils`, `color-analysis`, `dev-sections`.
 
 ## Usage Example
 
 ```typescript
-// Import any utility directly from the utils barrel
+// Pull any util from the single barrel — no need to chase individual modules
 import {
   cn,
   formatCurrency,
   formatRelativeTime,
   getDynamicIcon,
-  getEmbedProxyAuth,
+  embedAuthedFetch,
   scrollElementIntoView,
-  getCurrentPlatform,
+  buildListUrl,
+  DEV_SECTION_PARAM_KEYS,
 } from '@flamingo-stack/openframe-frontend-core/utils'
 
-// CSS class merging
-const className = cn('base-class', isActive && 'active')
+// Class merging
+const cls = cn('base-class', isActive && 'active')
 
-// Format a currency value
-const price = formatCurrency(4999, 'USD') // "$49.99"
+// Currency formatter
+const price = formatCurrency(1999.99) // "$1,999.99"
 
-// Relative time display
+// Relative date
 const label = formatRelativeTime(new Date('2024-01-01')) // "6 months ago"
 
-// Retrieve embed proxy auth for non-chat surfaces
-const auth = getEmbedProxyAuth()
+// Dynamic icon lookup
+const Icon = getDynamicIcon('slack', 'md')
+
+// Embed-surface authenticated fetch
+const data = await embedAuthedFetch('/api/tickets')
+
+// Smooth scroll with sticky-header offset
+scrollElementIntoView(document.getElementById('section-3'), { offsetPx: 64 })
 
-// Scroll an element into view respecting sticky chrome
-scrollElementIntoView(targetElement, { offsetPx: 64 })
+// Build a typed deep-link for the dev center
+const url = `/dev?${DEV_SECTION_PARAM_KEYS.search}=flamingo`
 ```
 
-> **Note:** Several exports are intentionally re-routed through this barrel to keep server-safe utilities (e.g. `CUSTOM_ITEM_ID`, `getSourceLabel`, `isCrossOriginUrl`) accessible from SSR/server code without crossing `"use client"` boundaries.
\ No newline at end of file
+> **Note:** Server-safe exports (source icons, ClickUp taxonomy, content-href, list-url) are explicitly isolated so Next.js server components can import from this barrel without crossing a `"use client"` boundary.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.list-url.md b/openframe-frontend-core/src/utils/.list-url.md
new file mode 100644
index 000000000..2d617c168
--- /dev/null
+++ b/openframe-frontend-core/src/utils/.list-url.md
@@ -0,0 +1,35 @@
+<!-- source-hash: 9635a461e965f0ae24cadbd85973188a -->
+Builds a type-safe list-API URL for fetching full entity rows by ID in OpenFrame's chat entity-card pipeline, serving as the single source of truth for per-content-type endpoint shapes across hub RAG mappers and embedders.
+
+## Key Components
+
+- **`ALIASES`** — Maps legacy `contentRefType` strings (e.g. `blog_post_existing`) to their canonical `documentType` equivalents before URL lookup.
+- **`BUILDERS`** — A keyed registry of URL constructor functions for each fetch-mode content type. Covers 12 entity types across roadmap/delivery tasks, blog, programs, guides, case studies, releases, interviews, and investor updates.
+- **`buildListUrl(contentRefType, ids, base?)`** — The exported entry point. Resolves aliases, handles the `marketing_campaign` admin endpoint as a static literal branch (CodeQL-safe), performs a `hasOwnProperty` guard to prevent prototype-chain dispatch, and returns `null` for unknown/no-list types.
+
+## Usage Example
+
+```typescript
+import { buildListUrl } from '@flamingo-stack/openframe-frontend-core/utils'
+
+// Hub-relative (default base)
+buildListUrl('roadmap_item', ['abc', 'def'])
+// → '/api/roadmap?task_ids=abc,def'
+
+// Legacy alias resolution
+buildListUrl('blog_post_existing', ['abc', 'def'])
+// → '/api/blog/posts?ids=abc,def&pageSize=2'
+
+// With reverse-proxy prefix (embedder usage)
+buildListUrl('webinar', ['abc'], '/content')
+// → '/content/api/programs/webinars?ids=abc&limit=1&filter=all'
+
+// Type with no list endpoint → null (fetch skipped)
+buildListUrl('github_pr', ['abc'])
+// → null
+
+// Embedder wiring
+endpoints.buildListUrl = (type, ids) => buildListUrl(type, ids, '/content')
+```
+
+> **Note:** Returns `null` for empty `ids` arrays or unregistered types. Non-RAG types (`github_*`, `slack_message`, financials) are intentionally absent from `BUILDERS` — their `null` return disables fetching rather than fabricating a URL.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.ods-color-utils.md b/openframe-frontend-core/src/utils/.ods-color-utils.md
index e3386d3e9..bb5e318ed 100644
--- a/openframe-frontend-core/src/utils/.ods-color-utils.md
+++ b/openframe-frontend-core/src/utils/.ods-color-utils.md
@@ -1,27 +1,36 @@
-<!-- source-hash: 8d0a4e249109b10a270ca0755176abc6 -->
-Runtime utility library for working with ODS (OpenFrame Design System) color tokens, providing platform-aware theming, token lookup, CSS generation, and React integration helpers.
+<!-- source-hash: 07ff9cab51e7c135d79021e303c42878 -->
+Runtime utility library for working with ODS (OpenFrame Design System) color tokens across Flamingo's multi-platform stack (`openmsp`, `openframe`, `flamingo`).
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `Platform` | Type | Union of `'openmsp' \| 'openframe' \| 'flamingo'` |
-| `ColorCategory` | Type | Union of `'open' \| 'flamingo' \| 'system' \| 'attention'` |
-| `ColorVariant` | Type | Union of `'base' \| 'hover' \| 'active' \| 'focus' \| 'disabled'` |
-| `getODSToken` | Function | Looks up a raw token value by category, color name, and variant |
-| `getPlatformAccentColor` | Function | Returns the CSS variable for the current or specified platform's accent color |
-| `getCurrentPlatform` | Function | Resolves platform from DOM attribute or `NEXT_PUBLIC_APP_TYPE` env var |
-| `switchPlatformTheme` | Function | Updates `data-app-type` on `<html>` and dispatches `platformThemeChanged` event |
-| `getSemanticColor` | Function | Reads a computed `--color-*` CSS property for a given platform |
-| `tokenToTailwindClass` | Function | Maps a semantic token key to its corresponding Tailwind utility class |
-| `getTokensByCategory` | Function | Returns all tokens matching a given `ColorCategory` prefix |
-| `isValidODSToken` | Function | Checks whether a token key exists in the ODS token map |
-| `getPlatformConfig` | Function | Returns a config object with accent color, theme type, and brand name |
-| `generatePlatformCSS` | Function | Builds a CSS block of custom property overrides for a platform |
-| `applyColorToken` | Function | Directly sets a CSS custom property on an `HTMLElement` |
-| `interpolateColors` | Function | Linearly interpolates between two hex ODS tokens by progress (0–1) |
-| `usePlatformColors` | Function | React-friendly helper returning platform config and token accessors |
-| `getReadableTextColor` | Function | Returns `#212121` or `#fafafa` based on Rec. 601 luminance of a hex color |
+### Types
+- `Platform` — `'openmsp' | 'openframe' | 'flamingo'`
+- `ColorCategory` — `'open' | 'flamingo' | 'system' | 'attention'`
+- `ColorVariant` — `'base' | 'hover' | 'active' | 'focus' | 'disabled'`
+
+### Token Utilities
+- `getODSToken(category, color, variant?)` — Looks up a raw token value by composite key
+- `getTokensByCategory(category)` — Returns all tokens matching a category prefix
+- `isValidODSToken(tokenKey)` — Validates token existence in the ODS registry
+- `tokenToTailwindClass(tokenKey, type?)` — Maps a semantic token to a Tailwind utility class (e.g. `bg-ods-accent`)
+
+### Platform / Theme
+- `getCurrentPlatform()` — Resolves active platform from DOM attribute or `NEXT_PUBLIC_APP_TYPE` env
+- `getPlatformAccentColor(platform?)` — Returns the CSS variable for the platform's accent color
+- `getPlatformConfig(platform?)` — Returns a config object including accent color, brand name, and dark/light flags
+- `switchPlatformTheme(platform)` — Updates `data-app-type` on `<html>` and dispatches `platformThemeChanged`
+- `generatePlatformCSS(platform)` — Emits a CSS block with platform-scoped custom property overrides
+- `getSemanticColor(semanticName, platform?)` — Reads a computed `--color-*` property from a live DOM probe
+
+### Color Math
+- `hexToRgb(hex)` / `rgbToHex(r, g, b)` — Hex ↔ RGB conversion with clamping
+- `rgbToHsl(r, g, b)` / `hslToRgb(h, s, l)` — RGB ↔ HSL conversion
+- `getReadableTextColor(hex)` — Returns `#212121` or `#fafafa` based on Rec. 601 luminance
+- `deriveHoverColor(hex)` / `deriveActiveColor(hex)` — Darkens by 10/20 steps to match design-system presets
+- `interpolateColors(startToken, endToken, progress)` — Linearly blends two hex token values
+
+### React Integration
+- `usePlatformColors(platform?)` — Returns platform config + helper callbacks for use in React components
 
 ## Usage Example
 
@@ -30,42 +39,23 @@ import {
   getCurrentPlatform,
   getPlatformConfig,
   getODSToken,
-  tokenToTailwindClass,
-  interpolateColors,
-  getReadableTextColor,
-  usePlatformColors,
-  switchPlatformTheme
+  deriveHoverColor,
+  usePlatformColors
 } from './ods-color-utils';
 
-// Resolve the active platform (SSR + CSR safe)
+// Resolve active platform at runtime
 const platform = getCurrentPlatform(); // 'openframe'
 
-// Get full platform configuration
-const config = getPlatformConfig(platform);
-// { platform: 'openframe', accentColor: 'var(--ods-open-yellow-base)',
-//   isDarkTheme: true, isLightTheme: false, brandName: 'OpenFrame' }
+// Get full platform config
+const config = getPlatformConfig();
+// { platform: 'openframe', accentColor: 'var(--ods-open-yellow-base)', isDarkTheme: true, brandName: 'OpenFrame' }
 
-// Look up a raw design token
+// Look up a raw ODS token
 const tokenValue = getODSToken('system', 'greys-background', 'base');
 
-// Map a semantic token to a Tailwind class
-const twClass = tokenToTailwindClass('text-primary', 'text');
-// → 'text-ods-text-primary'
+// Derive interaction states for a custom hex color
+const hoverColor = deriveHoverColor('#3a86ff'); // '#2e7af5' (darkened by 10)
 
-// Interpolate between two hex tokens (e.g. for animations)
-const midColor = interpolateColors('open-yellow-base', 'flamingo-pink-base', 0.5);
-
-// Ensure readable text on a dynamic background
-const textColor = getReadableTextColor('#FFC008'); // → '#212121'
-
-// Switch platform at runtime (updates <html data-app-type> + fires event)
-switchPlatformTheme('flamingo');
-
-// React component usage
-function MyComponent() {
-  const { accentColor, isDarkTheme, getToken, switchTheme } = usePlatformColors();
-  return <div style={{ color: accentColor }}>{isDarkTheme ? 'Dark' : 'Light'}</div>;
-}
-```
-
-> **Note:** `getSemanticColor` and `applyColorToken` are browser-only — they return `undefined` or no-op on the server. `switchPlatformTheme` cannot persist `process.env` changes in production; use it for UI-layer toggling only.
\ No newline at end of file
+// In a React component
+const { accentColor, isDarkTheme, getToken } = usePlatformColors();
+```
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.release-badge.md b/openframe-frontend-core/src/utils/.release-badge.md
new file mode 100644
index 000000000..4b3baa9dc
--- /dev/null
+++ b/openframe-frontend-core/src/utils/.release-badge.md
@@ -0,0 +1,42 @@
+<!-- source-hash: 47a64824b89a260db77220062bb3aaf7 -->
+Maps product release types to their corresponding `StatusBadge` color schemes for the `ProductReleaseCard` large variant's metadata grid.
+
+## Key Components
+
+**Types**
+- `ReleaseType` — Union of valid release type strings: `'major' | 'minor' | 'patch' | 'beta' | 'alpha'`
+- `ReleaseTypeBadgeColor` — Union of badge color tokens: `'error' | 'cyan' | 'success' | 'warning'`
+
+**Function**
+- `releaseTypeToBadgeColor(t)` — Converts a release type string to its badge color token. Accepts `ReleaseType | string | null | undefined` to handle legacy API values gracefully; returns `undefined` for unknown inputs (triggers the card's em-dash fallback rather than crashing).
+
+**Color mapping**
+
+| Release Type | Color | Semantic |
+|---|---|---|
+| `major` | `error` (red) | Breaking change |
+| `minor` | `cyan` | New feature |
+| `patch` | `success` (green) | Safe bump |
+| `beta` / `alpha` | `warning` (yellow) | Preview |
+
+## Usage Example
+
+```typescript
+import { releaseTypeToBadgeColor } from './release-badge'
+
+// Known release type
+const color = releaseTypeToBadgeColor('major') // → 'error'
+
+// In a ProductReleaseCard render
+const releaseTypeBadgeColor = releaseTypeToBadgeColor(release.release_type)
+
+// Card renders colored badge only when BOTH values are present
+// If release_type is unknown/null, color is undefined → card shows '—'
+<ProductReleaseCard
+  size="lg"
+  releaseType={release.release_type}
+  releaseTypeBadgeColor={releaseTypeToBadgeColor(release.release_type)}
+/>
+```
+
+> **Note:** The admin form's `releaseTypeOptions.color` array uses a separate color vocabulary — this utility is intentionally scoped to `ProductReleaseCard` display logic only.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.release-cover.md b/openframe-frontend-core/src/utils/.release-cover.md
new file mode 100644
index 000000000..dfbe99847
--- /dev/null
+++ b/openframe-frontend-core/src/utils/.release-cover.md
@@ -0,0 +1,43 @@
+<!-- source-hash: 90922d1a0fba270fdb0d92bc58406d0e -->
+Resolves the cover image for `ProductReleaseCard` using a deterministic priority chain, ensuring consistent rendering across all surfaces (catalog, chat inline, chat wrapper).
+
+## Key Components
+
+### `ReleaseCoverSource`
+Input interface describing the optional image fields sourced from a release entity.
+
+| Field | Description |
+|---|---|
+| `featured_image` | Editor-curated cover — highest priority |
+| `highlight_video_thumbnail` | AI-generated highlight reel thumbnail |
+| `main_video_thumbnail` | Full-release video thumbnail |
+| `og_image_url` | SEO/OG fallback image |
+
+### `ReleaseCoverResult`
+Return shape from `resolveReleaseCover`.
+
+| Field | Description |
+|---|---|
+| `cover` | Resolved image URL, or `null` if none available |
+| `hasVideoCover` | `true` only when the active cover is a video thumbnail (priority 2 or 3) — used to conditionally render a Play overlay |
+
+### `resolveReleaseCover(r: ReleaseCoverSource): ReleaseCoverResult`
+Applies the priority chain using `||` (not `??`) so empty strings fall through rather than rendering a broken `<Image src="">`. Sets `hasVideoCover` to `false` when a `featured_image` is present, suppressing misleading Play overlays on still images.
+
+## Usage Example
+
+```typescript
+import { resolveReleaseCover } from './release-cover'
+
+const { cover, hasVideoCover } = resolveReleaseCover({
+  featured_image: null,
+  highlight_video_thumbnail: 'https://cdn.example.com/highlight.jpg',
+  main_video_thumbnail: 'https://cdn.example.com/main.jpg',
+  og_image_url: 'https://cdn.example.com/og.jpg',
+})
+
+// cover         → 'https://cdn.example.com/highlight.jpg'
+// hasVideoCover → true  (no featured_image, video thumb is active)
+```
+
+> To add a new fallback source or reorder priority, edit **only this file** — all surfaces update automatically.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/.scroll-into-view.md b/openframe-frontend-core/src/utils/.scroll-into-view.md
index 5bc110b31..972dffe59 100644
--- a/openframe-frontend-core/src/utils/.scroll-into-view.md
+++ b/openframe-frontend-core/src/utils/.scroll-into-view.md
@@ -1,40 +1,38 @@
-<!-- source-hash: ec93c3a6544d7f572c8219bc65ceaf67 -->
-Smooth-scroll utility that positions an element at the top of the viewport with support for sticky header offsets and pre-computed layout-shift adjustments.
+<!-- source-hash: 81fd222f9418c327ea827cd249169c58 -->
+A cancellation-proof scroll utility that animates a target element to the top of the viewport using a self-driven `requestAnimationFrame` tween, bypassing native smooth scroll's vulnerability to browser scroll anchoring and competing programmatic scrolls.
 
 ## Key Components
 
-### `ScrollElementIntoViewOptions`
+**`scrollElementIntoView(target, options)`** — Main export. Scrolls the page so `target` lands at the top of the viewport. SSR-safe; accepts `null`/`undefined` targets without defensive branching.
 
+**`ScrollElementIntoViewOptions`** — Configuration interface:
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `headerOffset` | `number` | `0` | Pixels to subtract for sticky chrome (e.g., `96` for `scroll-mt-24`) |
-| `behavior` | `ScrollBehavior` | `'smooth'` | `'smooth'` for animated scrolls, `'instant'` for deep-link jumps |
-| `adjustTargetY` | `(raw: number) => number` | — | Callback to correct the pixel target before animation starts |
+| `headerOffset` | `number` | `0` | Pixels subtracted from target `top` to clear sticky chrome |
+| `behavior` | `ScrollBehavior` | `'smooth'` | `'instant'`/`'auto'` for synchronous jump; `'smooth'` for tween |
+| `adjustTargetY` | `(raw: number) => number` | — | Per-frame target override for known layout shifts |
+| `durationMs` | `number` | `320` | Tween duration in ms |
 
-### `scrollElementIntoView(target, options?)`
+**`cancelActiveScroll()`** — Internal. Cancels any in-flight tween and removes gesture listeners. Only one page-scroll animation runs at a time.
 
-Computes a fixed pixel target via `getBoundingClientRect().top + scrollY - headerOffset`, then calls `window.scrollTo()` directly. This avoids the jitter caused by `element.scrollIntoView()`, which re-targets continuously during layout shifts. Handles `null`/`undefined` refs as a no-op and short-circuits in SSR environments.
+**`easeOutCubic`** — `1 - (1-t)³` easing curve applied to the tween.
 
 ## Usage Example
 
 ```typescript
-import { scrollElementIntoView } from './scroll-into-view'
+import { scrollElementIntoView } from '@/lib/scroll-into-view'
 
-// Basic — scroll a ref to top, accounting for a 96px sticky header
-scrollElementIntoView(cardRef.current, { headerOffset: 96 })
+// Basic scroll with hub header offset
+scrollElementIntoView(ref.current, { headerOffset: 96 })
 
-// Instant jump on deep-link land
-scrollElementIntoView(anchorRef.current, {
-  headerOffset: 96,
-  behavior: 'instant',
-})
+// Instant jump (deep-link land / programmatic focus)
+scrollElementIntoView(anchorEl, { behavior: 'instant', headerOffset: 96 })
 
-// Pre-computed layout-shift adjustment (e.g. HelpCenterCard accordion)
-// Row A (above target) collapses simultaneously — shift target up by A's height
-scrollElementIntoView(rowBRef.current, {
+// Compensate for a sibling drawer still collapsing
+scrollElementIntoView(rowEl, {
   headerOffset: 96,
-  adjustTargetY: (raw) => raw - getAboveDrawerHeight(),
+  adjustTargetY: (raw) => raw - DRAWER_HEIGHT,
 })
 ```
 
-> **Why not `element.scrollIntoView()`?** That API re-targets continuously as the page reflows during the animation, causing visible jitter when sibling content is also moving. Pre-computing a fixed pixel value lets the browser commit to a clean, uninterrupted animation.
\ No newline at end of file
+> **Why not `behavior: 'smooth'`?** Browser scroll anchoring synchronously corrects `scrollTop` when content shifts, which aborts any in-flight native smooth scroll per the CSSOM-View spec. This tween writes instant positions every frame — nothing to abort — and re-computes the target each frame to track elements still settling.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/dev-sections/.dev-section-param-keys.md b/openframe-frontend-core/src/utils/dev-sections/.dev-section-param-keys.md
new file mode 100644
index 000000000..eeaaecbc5
--- /dev/null
+++ b/openframe-frontend-core/src/utils/dev-sections/.dev-section-param-keys.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 7cdef55a92a1bc9821fa545e33ee79f7 -->
+Defines canonical URL parameter keys for dev-center sections, serving as the single source of truth shared between the chrome registry (which **writes** query params) and list views (which **read** them) to prevent silent filtering mismatches.
+
+## Key Components
+
+**`DEV_SECTION_PARAM_KEYS`** — a `const` object of URL parameter key strings used across dev-center sections:
+
+| Key | URL Param | Used By |
+|-----|-----------|---------|
+| `search` | `?search=` | All dev-center sections (free-text search) |
+| `status` | `?status=` | Roadmap & Help Center ticket filters |
+| `releaseStatus` | `?release_status=` | Product releases stability-tier filter |
+| `deliveryTaskType` | `?task_type=` | Delivery (bug-fix / enhancement) task-type filter |
+
+## Usage Example
+
+```typescript
+import { DEV_SECTION_PARAM_KEYS } from '@/utils/dev-section-param-keys'
+
+// In the chrome registry — WRITING params to the URL
+const params = new URLSearchParams()
+params.set(DEV_SECTION_PARAM_KEYS.status, 'in-progress')
+params.set(DEV_SECTION_PARAM_KEYS.search, query)
+
+// In a list view — READING params from the URL
+const status = searchParams.get(DEV_SECTION_PARAM_KEYS.status)
+const search = searchParams.get(DEV_SECTION_PARAM_KEYS.search)
+```
+
+> **Why this matters:** Both the chrome registry (`OPENFRAME_DEV_SECTIONS`) and the list views (`RoadmapView`, `ProductReleasesView`, `DeliveryLists`) import from this file rather than re-declaring string literals. This makes key mismatches structurally impossible — if the written key and the read key ever diverge, filtering breaks silently with no runtime error.
\ No newline at end of file
diff --git a/openframe-frontend-core/src/utils/dev-sections/.openframe-dev-sections.md b/openframe-frontend-core/src/utils/dev-sections/.openframe-dev-sections.md
index 307aec4e4..d7106e2f3 100644
--- a/openframe-frontend-core/src/utils/dev-sections/.openframe-dev-sections.md
+++ b/openframe-frontend-core/src/utils/dev-sections/.openframe-dev-sections.md
@@ -1,38 +1,31 @@
-<!-- source-hash: 54e69314db343a8160db105f0636d9c5 -->
-Canonical metadata registry for all OpenFrame dev-center surface sections (Roadmap, Bug-fixes & Enhancements, Releases, Onboarding Guides, Help Center). Centralizes per-section icon, navigator card copy, hero copy, search config, and filter config into a single source of truth consumed by both the homepage navigator grid and destination page heroes.
+<!-- source-hash: 5b2aafd9e6be550c74161d5e68607913 -->
+Canonical metadata registry for all OpenFrame dev-center surfaces, co-locating icon, copy, search config, and filter config for each section in a single source of truth consumed by both the homepage navigator grid and destination page heroes.
 
 ## Key Components
 
-### Exported Constants
+**Exported Constants**
 
-| Export | Purpose |
-|--------|---------|
-| `ROADMAP_STATUS_OPTIONS` | Filter options for roadmap status (`all`, `completed`, `in_progress`) |
-| `DELIVERY_TASK_TYPE_OPTIONS` | Filter options for delivery task type (`all`, `Bug`, `Request`) |
-| `TICKET_STATUS_OPTIONS` | Filter options for help center ticket status (`all`, `open`, `closed`) |
-| `OPENFRAME_DEV_SECTIONS` | Primary registry — keyed object of all 5 dev-center sections |
+| Constant | Purpose |
+|---|---|
+| `ROADMAP_STATUS_OPTIONS` | Filter options for the Roadmap section (`all` / `completed` / `in_progress`) |
+| `DELIVERY_TASK_TYPE_OPTIONS` | Filter options for Bug-fixes & Enhancements (`all` / `Bug` / `Request`) |
+| `TICKET_STATUS_OPTIONS` | Filter options for Help Center tickets (`all` / `open` / `closed`) |
+| `OPENFRAME_DEV_SECTIONS` | Master registry of all five sections: `roadmap`, `delivery`, `releases`, `onboarding`, `tickets` |
 
-### Types
+**Exported Types**
 
-- **`OpenframeDevSection`** — Shape contract for each registry entry, including `href`, `icon`, `navigator`, `hero`, `search`, and `filter` fields
-- **`OpenframeDevSectionKey`** — Union type of valid section keys: `"roadmap" | "delivery" | "releases" | "onboarding" | "tickets"`
-
-### Sections in the Registry
-
-| Key | Route | Notes |
-|-----|-------|-------|
-| `roadmap` | `/roadmap` | Status filter |
-| `delivery` | `/bug-fixes-and-enhancements` | Task type filter |
-| `releases` | `/releases` | Release status filter |
-| `onboarding` | `/onboarding-guides` | Navigator card only — `hero`/`search`/`filter` are inert |
-| `tickets` | `/tickets` | Ticket status filter |
+- `OpenframeDevSection` — interface describing the shape of each section entry (`href`, `icon`, `navigator`, `hero`, `search`, `filter`)
+- `OpenframeDevSectionKey` — union type of valid section keys (`"roadmap" | "delivery" | "releases" | "onboarding" | "tickets"`)
 
 ## Usage Example
 
 ```typescript
-import { OPENFRAME_DEV_SECTIONS, type OpenframeDevSectionKey } from './openframe-dev-sections'
+import {
+  OPENFRAME_DEV_SECTIONS,
+  type OpenframeDevSectionKey,
+} from './openframe-dev-sections'
 
-// Render all navigator cards (skip onboarding if route is not hosted)
+// Render all homepage navigator cards (skip onboarding if route not hosted)
 const navSections = Object.values(OPENFRAME_DEV_SECTIONS).filter(
   (s) => s.href !== '/onboarding-guides'
 )
@@ -40,10 +33,18 @@ const navSections = Object.values(OPENFRAME_DEV_SECTIONS).filter(
 // Access a specific section's hero copy
 const { title, description } = OPENFRAME_DEV_SECTIONS.roadmap.hero
 
-// Type-safe section key lookup
+// Type-safe section lookup
 function getSectionConfig(key: OpenframeDevSectionKey) {
   return OPENFRAME_DEV_SECTIONS[key]
 }
+
+// Build filter pills for a section (guard for null)
+const roadmapFilter = OPENFRAME_DEV_SECTIONS.roadmap.filter
+if (roadmapFilter) {
+  roadmapFilter.options.forEach(({ value, label }) => {
+    console.log(`${label} → ?${roadmapFilter.paramKey}=${value}`)
+  })
+}
 ```
 
-> **⚠️ Embedder Note — `onboarding` entry:** The `onboarding` section drives the homepage navigator card only. Its `hero`, `search`, and `filter` fields are intentionally empty/null. Embedders that don't host `/onboarding-guides` should filter it out before iterating the registry.
\ No newline at end of file
+> **Note:** The `onboarding` section has `search: null` and `filter: null` by design — its search and filter controls are injected by the host via `DevSectionPage`'s `preControls` slot. Embedders iterating the registry for sections that use `DevSectionView` chrome should filter it out explicitly.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ProxySessionCleanupWebSocketClient.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ProxySessionCleanupWebSocketClient.md
index c28289cb9..5bebc07ea 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ProxySessionCleanupWebSocketClient.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ProxySessionCleanupWebSocketClient.md
@@ -1,38 +1,42 @@
-<!-- source-hash: 69ec826fd0776ad7643408129d07530b -->
-A decorator for Spring's `WebSocketClient` that ensures downstream proxy WebSocket sessions are properly closed after relay completion, with optional debug logging per path.
+<!-- source-hash: c0ed52105696c668a1c8bd2b9566da5d -->
+A decorator/wrapper around a reactive `WebSocketClient` that ensures downstream proxy WebSocket sessions are properly closed after relay completion, preventing connection leaks in the OpenFrame API gateway.
 
 ## Key Components
 
-| Element | Description |
-|---|---|
-| `ProxySessionCleanupWebSocketClient` | Implements `WebSocketClient`; wraps a delegate client to add cleanup logic |
-| `delegate` | The underlying `WebSocketClient` that performs the actual connection |
+| Component | Description |
+|-----------|-------------|
+| `ProxySessionCleanupWebSocketClient` | Implements `WebSocketClient`; delegates execution while adding cleanup logic |
+| `delegate` | The underlying `WebSocketClient` to which actual connection handling is forwarded |
 | `loggingProperties` | `WebSocketLoggingProperties` used to enable per-path debug logging |
-| `wrapHandler(URI, WebSocketHandler)` | Decorates the original handler with `doFinally` cleanup logic |
-| `CLOSE_TIMEOUT` | 5-second timeout applied when force-closing a lingering session |
+| `wrapHandler()` | Wraps the original `WebSocketHandler` to inject a `doFinally` cleanup hook |
+| `CLOSE_TIMEOUT` | 5-second timeout applied when forcefully closing a lingering session |
 
 ## Behavior
 
-After the relay `Mono<Void>` completes (any terminal signal), the wrapper checks whether the proxy session is still open. If so, it issues a `CloseStatus.GOING_AWAY` close with a 5-second timeout, logs the outcome, and silently swallows errors to avoid propagating close failures upstream.
+After the relay `Mono<Void>` completes (normally or via error/cancel), the `doFinally` hook checks whether the proxy session is still open:
+
+- **Still open** → logs a warning, then calls `session.close(GOING_AWAY)` with a 5-second timeout; errors during close are swallowed silently.
+- **Already closed** → logs a debug message (if the path is in the debug list) and does nothing.
 
 ## Usage Example
 
 ```java
+// Bean definition in Spring configuration
 @Bean
 public WebSocketClient webSocketClient(
         ReactorNettyWebSocketClient nettyClient,
-        WebSocketLoggingProperties loggingProperties) {
+        WebSocketLoggingProperties loggingProps) {
 
-    return new ProxySessionCleanupWebSocketClient(nettyClient, loggingProperties);
+    return new ProxySessionCleanupWebSocketClient(nettyClient, loggingProps);
 }
 
-// The client is then used transparently like any other WebSocketClient:
+// The wrapper is transparent — use it exactly like a standard WebSocketClient
 webSocketClient.execute(
-    URI.create("ws://backend-service/ws/chat"),
-    headers,
+    URI.create("ws://backend-service/ws/events"),
+    httpHeaders,
     session -> session.receive()
+        .doOnNext(msg -> process(msg))
         .then()
-).subscribe();
-```
-
-> **Note:** This client is typically registered as a Spring bean and injected into the gateway's WebSocket proxy routing configuration. It adds no behavioral changes to the happy path — cleanup only triggers when a session remains open after relay termination.
\ No newline at end of file
+);
+// Cleanup fires automatically via doFinally when the relay ends
+```
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ToolWebSocketProxyUrlFilter.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ToolWebSocketProxyUrlFilter.md
index 0818e70e9..024a6fcb8 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ToolWebSocketProxyUrlFilter.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.ToolWebSocketProxyUrlFilter.md
@@ -1,26 +1,25 @@
-<!-- source-hash: 5fa52a8e046e90ebacfbc588429ac816 -->
-Abstract Spring Cloud Gateway filter that resolves and proxies WebSocket connections to integrated tools by dynamically determining the upstream WebSocket URI based on the tool configuration and request path.
+<!-- source-hash: 1588558beaccea69ba991845e39982a6 -->
+Reactive Spring Cloud Gateway filter that intercepts WebSocket proxy requests for integrated tools, resolves the upstream WebSocket URI, and forwards the mutated exchange through the filter chain.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `ToolWebSocketProxyUrlFilter` | Abstract `GatewayFilter` base class for WebSocket proxy URL resolution |
-| `ORIGINAL_AUTHORIZATION_ATTR` | Exchange attribute key for preserving the original `Authorization` header downstream |
-| `filter()` | Core filter logic: extracts tool ID from path, validates the tool, resolves the upstream WebSocket URI, and stores it as `GATEWAY_REQUEST_URL_ATTR` |
-| `getTool()` | Looks up the `IntegratedTool` by ID, throwing if not found or disabled |
-| `mutateExchange()` | Overridable hook for subclasses to further mutate the exchange before forwarding |
-| `getRequestToolId()` | Abstract — subclasses extract the tool ID from the request path |
-| `getEndpointPrefix()` | Abstract — subclasses provide the endpoint prefix used during upstream WebSocket URI resolution |
-| `getOrder()` | Runs one step after `RouteToRequestUrlFilter` to override the resolved URL |
+| Member | Type | Description |
+|--------|------|-------------|
+| `ORIGINAL_AUTHORIZATION_ATTR` | `String` constant | Exchange attribute key used to preserve the original `Authorization` header before upstream mutation |
+| `getOrder()` | Method | Sets filter precedence to `ROUTE_TO_URL_FILTER_ORDER + 1`, ensuring it runs immediately after route URL resolution |
+| `filter()` | Method | Core reactive pipeline — extracts tool ID from path, validates the tool, resolves the WebSocket upstream URI, stores it in `GATEWAY_REQUEST_URL_ATTR`, and delegates to the chain |
+| `getTool()` | Method (private) | Looks up the `IntegratedTool` by key and enforces enabled-state validation, emitting errors on missing or disabled tools |
+| `mutateExchange()` | Method (protected) | Hook for subclasses to modify the `ServerWebExchange` (e.g. rewrite headers) before forwarding; returns the original exchange by default |
+| `getRequestToolId()` | Abstract method | Subclass-defined path parsing to extract the tool identifier |
+| `getEndpointPrefix()` | Abstract method | Subclass-defined prefix passed to the upstream resolver for WebSocket endpoint construction |
 
 ## Usage Example
 
 ```java
 @Component
-public class MyToolWebSocketFilter extends ToolWebSocketProxyUrlFilter {
+public class ZabbixWebSocketFilter extends ToolWebSocketProxyUrlFilter {
 
-    public MyToolWebSocketFilter(
+    public ZabbixWebSocketFilter(
             ReactiveIntegratedToolRepository toolRepository,
             ToolUpstreamResolverRegistry upstreamRegistry) {
         super(toolRepository, upstreamRegistry);
@@ -28,21 +27,24 @@ public class MyToolWebSocketFilter extends ToolWebSocketProxyUrlFilter {
 
     @Override
     protected String getRequestToolId(String path) {
-        // e.g. /ws/tools/{toolId}/...
-        return path.split("/")[3];
+        // e.g. /ws/zabbix/... -> "zabbix"
+        return path.split("/")[2];
     }
 
     @Override
     protected String getEndpointPrefix() {
-        return "/ws";
+        return "/zabbix";
     }
 
     @Override
     protected ServerWebExchange mutateExchange(ServerWebExchange exchange, IntegratedTool tool) {
-        // Optionally strip or replace auth headers before forwarding
-        return exchange.mutate()
-                .request(r -> r.headers(h -> h.remove(HttpHeaders.AUTHORIZATION)))
+        // Strip or replace auth headers before forwarding upstream
+        ServerHttpRequest mutated = exchange.getRequest().mutate()
+                .header(HttpHeaders.AUTHORIZATION, "Bearer " + tool.getApiKey())
                 .build();
+        return exchange.mutate().request(mutated).build();
     }
 }
-```
\ No newline at end of file
+```
+
+> **Note:** The original `Authorization` header is preserved under `ORIGINAL_AUTHORIZATION_ATTR` on the exchange attributes, allowing downstream filters or logging to inspect the caller's credentials independently of whatever header is sent upstream.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.WebSocketServiceSecurityDecorator.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.WebSocketServiceSecurityDecorator.md
index fbd7c532c..d14081708 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.WebSocketServiceSecurityDecorator.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/config/ws/.WebSocketServiceSecurityDecorator.md
@@ -1,45 +1,55 @@
-<!-- source-hash: 58fc06a2b3a2fab4eccd370f98e6c25c -->
-A decorator for Spring's `WebSocketService` that enforces JWT-based session lifecycle management on secured WebSocket endpoints in the OpenFrame gateway.
+<!-- source-hash: fef90abf3194352d4d9d049e01051e92 -->
+A decorator for Spring's `WebSocketService` that enforces JWT-based session lifecycle management on secured WebSocket endpoints in the OpenFrame API gateway.
 
 ## Key Components
 
-| Member | Description |
-|--------|-------------|
-| `CLOCK_SKEW_SECONDS` | 60-second buffer added to JWT expiry to align with Spring Security's default clock skew tolerance |
-| `sessionRegistry` | Thread-safe `ConcurrentHashMap` tracking active sessions with creation time, path, and subject |
-| `SessionInfo` | Record holding per-session metadata (`createdAt`, `path`, `sub`) |
-| `handleRequest()` | Intercepts WebSocket upgrade requests; applies JWT enforcement only on secured endpoints |
-| `isSecuredEndpoint()` | Checks if the request path matches any known secured endpoint prefixes (tools API/agent, NATS WS paths) |
-| `scheduleSessionRemoveJob()` | Schedules a reactive `Mono.delay` to force-close the session when the JWT expires |
-| `processSessionClosedEvent()` | Subscribes to the session close status to clean up the registry, dispose the expiry job, and emit traffic metrics |
-| `formatLifetime()` | Formats session duration in human-readable `min`/`sec` form for logging |
+| Component | Description |
+|-----------|-------------|
+| `WebSocketServiceSecurityDecorator` | Core decorator implementing `WebSocketService`; intercepts WebSocket handshakes on secured paths |
+| `sessionRegistry` | `ConcurrentHashMap` tracking active sessions with creation time, path, and subject (`sub`) |
+| `SessionInfo` | Record holding session metadata: `createdAt`, `path`, `sub` |
+| `CLOCK_SKEW_SECONDS` | 60-second buffer added to JWT expiry to align with Spring Security's default clock skew |
+| `isSecuredEndpoint()` | Checks if the request path matches known secured WS prefixes (tools API/agent, NATS) |
+| `scheduleSessionRemoveJob()` | Schedules a reactive delayed close when the JWT expires (expiry + skew seconds) |
+| `processSessionClosedEvent()` | Subscribes to the session's close status to clean up registry, cancel the scheduled job, and emit metrics |
 
 ## Usage Example
 
-The decorator wraps the default `WebSocketService` bean and is wired via `WebSocketGatewayConfig`:
-
 ```java
+// Registered as a Spring Bean — typically in WebSocketGatewayConfig
 @Bean
 public WebSocketService webSocketService(
-    WebSocketService defaultWebSocketService,
-    RequestJwtClaimsReader jwtReader,
-    GatewayTrafficMetrics metrics,
-    WebSocketLoggingProperties loggingProps
-) {
+        WebSocketService defaultWebSocketService,
+        RequestJwtClaimsReader jwtClaimsReader,
+        GatewayTrafficMetrics metrics,
+        WebSocketLoggingProperties loggingProps) {
+
     return new WebSocketServiceSecurityDecorator(
-        defaultWebSocketService,
-        jwtReader,
-        metrics,
-        loggingProps
+            defaultWebSocketService,
+            jwtClaimsReader,
+            metrics,
+            loggingProps
     );
 }
 ```
 
-At runtime, on a secured path (e.g. `/tools/api/ws`), the decorator:
-
-1. Opens the session and registers it in `sessionRegistry`
-2. Reads the JWT expiration and schedules an auto-close after `expiresAt + 60s`
-3. Observes `session.closeStatus()` — if the client disconnects first, the scheduled job is disposed
-4. Emits `webSocketOpened` / `webSocketClosed` metrics for traffic observability
+**Session lifecycle flow:**
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Decorator
+    participant JWTReader
+    participant Scheduler
+
+    Client->>Decorator: WS Handshake (secured path)
+    Decorator->>JWTReader: getExpiration()
+    JWTReader-->>Decorator: expiresAt
+    Decorator->>Scheduler: delay(expiry + 60s) → session.close()
+    Decorator->>Decorator: subscribe to closeStatus()
+    Client->>Decorator: Client closes first
+    Decorator->>Scheduler: disposable.dispose()
+    Decorator->>Decorator: webSocketClosed() metrics + registry cleanup
+```
 
-> **Note:** Secured endpoint paths are currently hardcoded. A TODO exists to rely on Spring Security configuration instead of explicit path matching.
\ No newline at end of file
+> **Note:** Hardcoded secured path matching is a known limitation — a TODO exists to delegate authorization to Spring Security instead of matching prefixes manually.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.GatewaySecurityConfig.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.GatewaySecurityConfig.md
index 144d1f2a1..74064baad 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.GatewaySecurityConfig.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.GatewaySecurityConfig.md
@@ -1,43 +1,50 @@
-<!-- source-hash: 692860e0c8942c89cb847b18849abf40 -->
-Configures Spring Security for the OpenFrame API Gateway in a reactive (WebFlux) environment, defining JWT authentication, role-based access control, and the security filter chain.
+<!-- source-hash: 98e270b032718abb5312ecd00341d0be -->
+Configures Spring WebFlux security for the OpenFrame API gateway, defining JWT-based OAuth2 resource server authentication, role-based access control, and filter chain setup for reactive web applications.
 
 ## Key Components
 
-| Component | Description |
-|-----------|-------------|
-| `reactiveJwtAuthenticationConverter()` | Builds a JWT converter that extracts both `roles` (prefixed `ROLE_`) and `scope` (prefixed `SCOPE_`) claims, using `sub` as the principal |
-| `springSecurityFilterChain()` | Defines the main security filter chain: disables CSRF/CORS/form login, enables OAuth2 resource server with a multi-issuer resolver, and enforces path-based RBAC |
-| `passwordEncoder()` | Exposes a `BCryptPasswordEncoder` bean for password hashing |
-| `AddAuthorizationHeaderFilter` | Custom pre-authentication filter injected before the authentication stage |
+| Bean | Description |
+|------|-------------|
+| `reactiveJwtAuthenticationConverter()` | Extracts `roles` (prefixed `ROLE_`) and `scope` (prefixed `SCOPE_`) claims from JWT tokens, merging both into a single authority stream |
+| `springSecurityFilterChain()` | Builds the reactive security filter chain: disables CSRF/CORS/BasicAuth/FormLogin, wires the multi-issuer JWT resolver, injects `AddAuthorizationHeaderFilter`, and enforces path-level RBAC |
+| `passwordEncoder()` | Provides a BCrypt password encoder bean |
 
 ## Access Control Rules
 
-| Path Pattern | Required Role |
-|-------------|--------------|
-| `OPTIONS /**` | Public |
-| `/clients/metrics/**`, `/oauth/token`, `/api/agents/register` | Public |
-| `/api/**` | `ADMIN` |
-| `/tools/agent/**`, `/ws-tools/agent/**` | `AGENT` |
-| NATS WebSocket endpoints | `ADMIN` or `AGENT` |
-| `/chat/**` | `ADMIN` or `AGENT` |
-| `/guide/**` | `ADMIN` |
-| `/clients/**` | `AGENT` |
-| `/tools/**`, `/ws-tools/**` | `ADMIN` |
+```text
+OPTIONS /**                              → permitAll (preflight)
+/clients/metrics/**                      → permitAll
+/clients/api/agents/register|reinstall   → permitAll
+/clients/oauth/token                     → permitAll
+/api/**                                  → ROLE_ADMIN
+/tools/agent/**                          → ROLE_AGENT
+/ws-tools/agent/**                       → ROLE_AGENT
+NATS WebSocket endpoints                 → ROLE_AGENT or ROLE_ADMIN
+/chat/**                                 → ROLE_AGENT or ROLE_ADMIN
+/content/**                              → ROLE_ADMIN
+/clients/**                              → ROLE_AGENT
+/tools/**                                → ROLE_ADMIN
+/ws-tools/**                             → ROLE_ADMIN
+/**                                      → permitAll (catch-all)
+```
 
 ## Usage Example
 
 ```java
-// JWT token must carry claims in this shape for correct role resolution:
-// {
-//   "sub": "user-id-123",
-//   "roles": ["ADMIN"],
-//   "scope": "read write"
-// }
-
-// Spring auto-wires the filter chain — no manual wiring needed.
-// To protect a new route, add a pathMatchers() rule in springSecurityFilterChain():
-
-.pathMatchers(NEW_PREFIX + "/**").hasRole(ADMIN)
+// JWT must carry a "roles" claim for RBAC to work
+// Example decoded JWT payload:
+{
+  "sub": "agent-service-01",
+  "roles": ["AGENT"],
+  "scope": "read write"
+}
+
+// Spring will resolve this to:
+// GrantedAuthority: ROLE_AGENT, SCOPE_read, SCOPE_write
+
+// Bean is auto-wired by Spring Boot — no manual instantiation needed.
+// Customize path rules via PathConstants:
+// API_PREFIX, CLIENTS_PREFIX, TOOLS_PREFIX, etc.
 ```
 
-> **Note:** The `ReactiveAuthenticationManagerResolver` bean (not shown here) must support multi-issuer JWT validation. The filter chain is only active for reactive (`REACTIVE`) web applications via `@ConditionalOnWebApplication`.
\ No newline at end of file
+> **Note:** The class activates only for reactive (`REACTIVE`) web applications via `@ConditionalOnWebApplication`. A multi-issuer `ReactiveAuthenticationManagerResolver` bean must be provided separately to support multiple JWT issuers.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.PathConstants.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.PathConstants.md
index b26d4e1f8..8430a89e3 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.PathConstants.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/.PathConstants.md
@@ -1,32 +1,36 @@
-<!-- source-hash: e33033a91063db2553d133390b0b1cfa -->
-Defines path prefix constants used across the OpenFrame Gateway security and routing layer to standardize endpoint URL segments.
+<!-- source-hash: 9b9f685d6fa7ea176ee02a5389ab3a82 -->
+Defines centralized path prefix constants used across the OpenFrame Gateway for routing and security configuration.
 
 ## Key Components
 
-| Constant | Value | Description |
+| Constant | Value | Purpose |
 |---|---|---|
-| `CLIENTS_PREFIX` | `/clients` | Client-facing endpoint prefix |
-| `API_PREFIX` | `/api` | General API endpoint prefix |
-| `TOOLS_PREFIX` | `/tools` | Tools endpoint prefix |
-| `WS_TOOLS_PREFIX` | `/ws/tools` | WebSocket tools endpoint prefix |
-| `CHAT_PREFIX` | `/chat` | Chat endpoint prefix |
-| `GUIDE_PREFIX` | `/guide` | Guide endpoint prefix |
+| `CLIENTS_PREFIX` | `/clients` | Client-facing endpoint routes |
+| `API_PREFIX` | `/api` | REST API endpoint routes |
+| `TOOLS_PREFIX` | `/tools` | Tool/integration endpoint routes |
+| `WS_TOOLS_PREFIX` | `/ws/tools` | WebSocket tool endpoint routes |
+| `CHAT_PREFIX` | `/chat` | Chat/messaging endpoint routes |
+| `CONTENT_PREFIX` | `/content` | Content delivery endpoint routes |
 
 ## Usage Example
 
 ```java
 import com.openframe.gateway.security.PathConstants;
 
-// Use in security configuration to permit or restrict routes
-http.authorizeRequests()
-    .antMatchers(PathConstants.API_PREFIX + "/**").authenticated()
-    .antMatchers(PathConstants.CLIENTS_PREFIX + "/**").hasRole("CLIENT")
-    .antMatchers(PathConstants.WS_TOOLS_PREFIX + "/**").authenticated()
-    .anyRequest().permitAll();
+@Configuration
+public class SecurityConfig {
 
-// Use in route matching
-String toolsRoute = PathConstants.TOOLS_PREFIX + "/execute";
-String chatRoute  = PathConstants.CHAT_PREFIX + "/session";
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        http.authorizeHttpRequests(auth -> auth
+            .requestMatchers(PathConstants.CLIENTS_PREFIX + "/**").hasRole("CLIENT")
+            .requestMatchers(PathConstants.API_PREFIX + "/**").authenticated()
+            .requestMatchers(PathConstants.WS_TOOLS_PREFIX + "/**").authenticated()
+            .anyRequest().permitAll()
+        );
+        return http.build();
+    }
+}
 ```
 
-> **Note:** `PathConstants` is a non-instantiable utility class (private constructor). Always reference constants statically via `PathConstants.CONSTANT_NAME`.
\ No newline at end of file
+> `PathConstants` is a non-instantiable utility class — all fields are `static final`. Reference constants directly via the class name rather than instantiating it.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/filter/.AddAuthorizationHeaderFilter.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/filter/.AddAuthorizationHeaderFilter.md
index 8096fb4e8..6a3cfff20 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/filter/.AddAuthorizationHeaderFilter.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/filter/.AddAuthorizationHeaderFilter.md
@@ -1,50 +1,39 @@
-<!-- source-hash: ac6c4fb8a33be0ab20db2589d15c1af1 -->
-A reactive `WebFilter` that normalizes authentication by injecting a standard `Authorization: Bearer` header when one is absent, resolving the token from multiple fallback sources before passing the request downstream.
+<!-- source-hash: 1308ce43bbccbfb89e9742a3f1ee1a80 -->
+A reactive Spring `WebFilter` that normalizes incoming requests by injecting a standard `Authorization: Bearer` header when absent, resolving the token from cookies, a custom header, or a query parameter.
 
 ## Key Components
 
 | Member | Description |
-|---|---|
-| `filter()` | Main filter logic — skips public paths, short-circuits if `Authorization` already exists, otherwise resolves and injects the token |
-| `isPrivatePath()` | Determines if a request path requires authentication (API, tools, WebSocket, chat, internal probe, and scoped client routes) |
-| `resolveBearerToken()` | Token resolution chain: HTTP cookie → `Access-Token` header → `authorization` query param |
-| `CookieService` | Injected dependency responsible for extracting the access token from cookies |
+|--------|-------------|
+| `filter()` | Core filter method — skips public paths, short-circuits if `Authorization` already exists, otherwise resolves and injects the token |
+| `isPrivatePath()` | Determines whether a request path requires authentication, covering API, tools, WebSocket, chat, content, internal probe, and client routes (with explicit public exclusions) |
+| `resolveBearerToken()` | Cascading token resolver: checks cookie → `Access-Token` header → `authorization` query param, returns first non-blank value |
+| `CookieService` | Injected dependency responsible for extracting the access token from the request cookie store |
 
-## Token Resolution Priority
+## Usage Example
+
+```java
+// Registered automatically as a Spring @Component — no manual wiring needed.
+// The filter intercepts all reactive requests and mutates protected ones:
+
+// Example: request arrives with token in cookie, no Authorization header
+// Before filter:  GET /api/tickets  (no Authorization header)
+// After filter:   GET /api/tickets  Authorization: Bearer eyJhbGci...
 
-```mermaid
-graph TD
-    A["Incoming Request"] --> B{"Is private path?"}
-    B -- No --> C["Pass through"]
-    B -- Yes --> D{"Authorization header present?"}
-    D -- Yes --> C
-    D -- No --> E{"Cookie token?"}
-    E -- Yes --> F["Inject Bearer header"]
-    E -- No --> G{"Access-Token header?"}
-    G -- Yes --> F
-    G -- No --> H{"authorization query param?"}
-    H -- Yes --> F
-    H -- No --> C
-    F --> C
+// Example: public path — filter is bypassed entirely
+// GET /clients/oauth/token  →  passed through unchanged
+
+// To extend protected paths, update isPrivatePath() or PathConstants:
+public static final String API_PREFIX = "/api";
+public static final String CONTENT_PREFIX = "/content";
 ```
 
-## Usage Example
+## Token Resolution Priority
 
-```java
-// Automatically registered as a Spring bean — no manual wiring needed.
-// The filter activates for any request matching a private path pattern, e.g.:
-
-// Request arrives with token in cookie instead of Authorization header:
-// Cookie: access_token=eyJhbGciOiJSUzI1NiJ9...
-//
-// Filter mutates the request before it reaches the resource server:
-// Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
-
-// Paths excluded from token injection (public):
-// /clients/metrics/**
-// /clients/api/agents/register
-// /clients/oauth/token
-// /clients/tool-agent/**
+```text
+1. HTTP Cookie     → access_token cookie   (cookieService)
+2. Custom Header   → Access-Token header   (ACCESS_TOKEN_HEADER)
+3. Query Parameter → ?authorization=...    (AUTHORIZATION_QUERY_PARAM)
 ```
 
-> **Note:** This filter is a pre-auth normalizer only — it does not validate tokens. Actual authentication is delegated to the Spring Security resource server configured downstream.
\ No newline at end of file
+> Paths explicitly excluded from client-private routing (e.g. `/clients/oauth/token`, `/clients/api/agents/register`) are treated as public and will never have a token injected.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.DefaultIssuerUrlProvider.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.DefaultIssuerUrlProvider.md
new file mode 100644
index 000000000..7c6336860
--- /dev/null
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.DefaultIssuerUrlProvider.md
@@ -0,0 +1,40 @@
+<!-- source-hash: 76cfd69c97224a0731ac47645b81c99e -->
+Fallback `IssuerUrlProvider` implementation for self-hosted (OSS/single-tenant) OpenFrame deployments, resolving JWT issuer URLs from static configuration rather than a database lookup.
+
+## Key Components
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `allowedIssuerBase` | `@Value` field | Base URL for the issuer, from `openframe.security.jwt.allowed-issuer-base` |
+| `superTenantId` | `@Value` field | Fixed tenant ID, from `openframe.security.jwt.super-tenant-id` |
+| `resolveIssuerUrls()` | `Mono<List<String>>` | Wraps the cached URL list in a reactive `Mono` |
+| `getCachedIssuerUrl()` | `List<String>` | Returns a singleton list of the fully-composed issuer URL |
+
+**Activation condition:** Registered only when no other `IssuerUrlProvider` bean exists (e.g. `SaasIssuerUrlProvider` in managed/cloud deployments), controlled via `@ConditionalOnMissingBean`.
+
+## Usage Example
+
+```java
+// application.yml (self-hosted deployment)
+// openframe:
+//   security:
+//     jwt:
+//       allowed-issuer-base: https://auth.example.com
+//       super-tenant-id: my-org
+
+// Resolved issuer URL produced:
+// → https://auth.example.com/my-org
+
+@Autowired
+IssuerUrlProvider issuerUrlProvider;
+
+// Reactive usage
+issuerUrlProvider.resolveIssuerUrls()
+    .subscribe(urls -> System.out.println(urls));
+// Output: [https://auth.example.com/my-org]
+
+// Synchronous usage (e.g. during filter initialization)
+List<String> urls = issuerUrlProvider.getCachedIssuerUrl();
+```
+
+> **Note:** In SaaS/multi-tenant deployments, this bean is skipped in favour of a database-backed provider. For single-tenant OSS installs, no DB lookup is required — the issuer URL is fully resolved from static config at startup.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.IssuerUrlProvider.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.IssuerUrlProvider.md
index 7953dc5ec..b6de4ff0b 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.IssuerUrlProvider.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/security/tenant/.IssuerUrlProvider.md
@@ -1,41 +1,48 @@
-<!-- source-hash: 3175b3652dda78c3f7ef4dffd28a683d -->
-This service provides dynamic JWT issuer URL resolution for multi-tenant security configurations. It manages a cached list of allowed issuer URLs based on tenant data from the database, with support for a super tenant configuration.
+<!-- source-hash: 4f85a3190b768380f7e64d14c662a546 -->
+Defines the contract for resolving JWT issuer URLs accepted by the gateway, supporting both single-tenant (OSS) and multi-tenant (SaaS) deployments.
 
 ## Key Components
 
-- **`resolveIssuerUrls()`** - Reactively resolves and caches issuer URLs from tenant repository
-- **`getCachedIssuerUrl()`** - Provides synchronous access to cached issuer URLs
-- **`allowedIssuerBase`** - Configurable base URL for issuer generation
-- **`superTenantId`** - Optional configuration for super tenant support
-- **`AtomicReference<Mono<List<String>>>`** - Thread-safe caching mechanism for reactive operations
+| Member | Type | Description |
+|--------|------|-------------|
+| `resolveIssuerUrls()` | `Mono<List<String>>` | Reactively fetches the current list of accepted JWT issuer URLs |
+| `getCachedIssuerUrl()` | `List<String>` | Returns the last cached issuer URLs synchronously, avoiding a blocking call on the hot path |
+
+## Implementation Strategy
+
+```mermaid
+graph TD
+    A["IssuerUrlProvider Interface"] --> B["OSS Default Impl"]
+    A --> C["SaaS Override (@Primary)"]
+    B --> D["Single Tenant - Local DB"]
+    C --> E["Multi-Tenant - tenant_cluster_registrations"]
+```
+
+- **OSS default** — reads a single `Tenant` record from the local database
+- **SaaS override** — annotated `@Primary`, reads from `tenant_cluster_registrations` to support multiple tenants per pod
 
 ## Usage Example
 
 ```java
 @Component
-public class JwtValidator {
-    
+public class JwtSecurityConfig {
+
     private final IssuerUrlProvider issuerUrlProvider;
-    
-    public JwtValidator(IssuerUrlProvider issuerUrlProvider) {
+
+    public JwtSecurityConfig(IssuerUrlProvider issuerUrlProvider) {
         this.issuerUrlProvider = issuerUrlProvider;
     }
-    
-    public Mono<Boolean> validateToken(String token) {
-        return issuerUrlProvider.resolveIssuerUrls()
-            .map(allowedIssuers -> {
-                // Extract issuer from JWT token
-                String tokenIssuer = extractIssuer(token);
-                return allowedIssuers.contains(tokenIssuer);
-            });
+
+    public Mono<List<String>> getAcceptedIssuers() {
+        // Reactive fetch - use on startup or cache refresh
+        return issuerUrlProvider.resolveIssuerUrls();
     }
-    
-    // For synchronous contexts
-    public boolean isValidIssuer(String issuer) {
-        List<String> cachedIssuers = issuerUrlProvider.getCachedIssuerUrl();
-        return cachedIssuers.contains(issuer);
+
+    public List<String> getAcceptedIssuersCached() {
+        // Synchronous cache read - use on hot path (e.g., per-request JWT validation)
+        return issuerUrlProvider.getCachedIssuerUrl();
     }
 }
 ```
 
-The component implements thread-safe lazy loading with error recovery, ensuring issuer URLs are efficiently cached while maintaining data consistency across reactive operations.
\ No newline at end of file
+> Implementations should populate the cache on startup and refresh it periodically so `getCachedIssuerUrl()` is always non-blocking and up to date.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.IntegrationService.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.IntegrationService.md
index 23c013ac0..51806f5fa 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.IntegrationService.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.IntegrationService.md
@@ -1,29 +1,34 @@
-<!-- source-hash: b9216f73900b544e29a418061d6251ae -->
-A reactive service that manages external tool integration testing and connection validation for the OpenFrame gateway system.
+<!-- source-hash: d7bee66e93d8b070896bd004595bf300 -->
+Provides integration connectivity testing for tools registered in the OpenFrame gateway, resolving tool API URLs and verifying reachability via HTTP health checks.
 
 ## Key Components
 
-- **testIntegrationConnection()** - Tests connectivity to integrated tools by validating tool status and making health check requests
-- **adjustUrl()** - Modifies URLs for local development by redirecting to localhost while preserving path and query parameters
-- **isLocalProfile()** - Detects if the application is running in local development mode based on Spring profiles
+| Member | Type | Description |
+|--------|------|-------------|
+| `testIntegrationConnection(String toolId)` | `Mono<String>` | Looks up a tool by ID, validates it is enabled, resolves its API URL, and performs a `GET /health` request |
+| `adjustUrl(String originalUrl)` | `private String` | Rewrites the host to `localhost` when the active Spring profile is `local` (or no profile is set), preserving scheme, port, path, query, and fragment |
+| `isLocalProfile()` | `private boolean` | Returns `true` if the `local` profile is active or no profiles are configured |
+
+**Dependencies injected:**
+
+- `ToolUrlService` — resolves the `API` URL from a tool document
+- `ReactiveIntegratedToolRepository` — reactive lookup of integrated tool records
+- `WebClient.Builder` — issues the health-check HTTP request
+- `Environment` — reads active Spring profiles for local-mode detection
 
 ## Usage Example
 
 ```java
-@RestController
-public class IntegrationController {
-    
-    private final IntegrationService integrationService;
-    
-    @GetMapping("/integrations/{toolId}/test")
-    public Mono<ResponseEntity<String>> testConnection(@PathVariable String toolId) {
-        return integrationService.testIntegrationConnection(toolId)
-            .map(response -> ResponseEntity.ok(response))
-            .onErrorResume(ResponseStatusException.class, 
-                ex -> Mono.just(ResponseEntity.status(ex.getStatusCode())
-                    .body(ex.getReason())));
-    }
-}
+// Inject the service and test connectivity for a registered tool
+integrationService.testIntegrationConnection("zabbix-prod")
+    .subscribe(
+        response -> System.out.println("Health response: " + response),
+        error   -> System.err.println("Connection failed: " + error.getMessage())
+    );
 ```
 
-The service validates that tools exist and are enabled before attempting connections. In local development, it automatically redirects API calls to localhost for easier testing. Health check responses are logged for monitoring integration status.
\ No newline at end of file
+**Error conditions:**
+
+- `404 NOT_FOUND` — no tool exists for the given `toolId`
+- `403 FORBIDDEN` — tool exists but `isEnabled()` returns `false`
+- `500 INTERNAL_SERVER_ERROR` — tool has no `API`-type URL configured
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.RestProxyService.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.RestProxyService.md
index e4b0a15dc..6a841969d 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.RestProxyService.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/service/.RestProxyService.md
@@ -1,44 +1,37 @@
-<!-- source-hash: cafe4b626be4c80f5f3d1cd80b110bf8 -->
-Reactive proxy service that forwards HTTP requests from the OpenFrame gateway to integrated tools (RMM agents, APIs), handling SSL, authentication headers, and error responses.
+<!-- source-hash: cf4d6a3bfe40aef597bff906a1d13e82 -->
+Reactive Spring service that proxies HTTP requests to integrated tools (e.g., RMM agents, APIs) by resolving the tool's upstream URL, injecting appropriate authentication headers, and forwarding the request via a configured `WebClient` with SSL and timeout settings.
 
 ## Key Components
 
 | Method | Description |
 |---|---|
-| `proxyApiRequest` | Proxies generic API calls to a tool's REST endpoint, injecting API key headers |
-| `proxyAgentRequest` | Proxies agent/device-scoped requests, forwarding `Tool-Authorization` headers |
-| `buildHttpClient` | Constructs a Reactor Netty `HttpClient` with SSL bypass, timeouts, and curl logging |
-| `buildApiRequestHeaders` | Builds standard JSON headers + resolved API key credentials for tool API calls |
-| `buildAgentRequestHeaders` | Extracts and forwards `Tool-Authorization` from the incoming request |
-| `proxy` | Core dispatch method — creates a `WebClient`, applies headers/body, handles errors reactively |
-| `buildErrorResponse` | Maps `WebClientResponseException` or generic errors to `ResponseEntity<String>` |
+| `proxyApiRequest()` | Proxies REST API calls to a tool's upstream endpoint under `/tools`, injecting API key headers |
+| `proxyAgentRequest()` | Proxies agent-level requests under `/tools/agent`, forwarding `Tool-Authorization` headers from the incoming request |
+| `buildApiRequestHeaders()` | Builds standard JSON headers plus resolved API key headers for tool API calls |
+| `buildAgentRequestHeaders()` | Builds headers for agent requests, passing through `Tool-Authorization` as `Authorization` |
+| `proxy()` | Core proxy method — constructs a `WebClient`, sends the request with a 60s timeout, and maps the response to `ResponseEntity<String>` |
+| `buildHttpClient()` | Configures a Reactor Netty `HttpClient` with SSL bypass (insecure trust manager), 30s connect timeout, 16KB decoder limits, and curl-style request logging |
+| `processErrorResponse()` | Converts 4xx/5xx upstream responses into `WebClientResponseException` for consistent error handling |
+| `buildErrorResponse()` | Maps exceptions to structured `ResponseEntity` error responses |
 
 ## Usage Example
 
 ```java
-// Inject the service
+// Injected via Spring context
 @Autowired
-private RestProxyService restProxyService;
+RestProxyService restProxyService;
 
-// Proxy an API request to a registered tool
+// Proxy an API request to an integrated tool
 Mono<ResponseEntity<String>> response = restProxyService.proxyApiRequest(
-    "tool-abc123",
-    serverHttpRequest,
-    "{\"query\": \"status\"}"
+    "tactical-rmm",       // toolId
+    serverHttpRequest,    // incoming reactive request
+    "{\"agentId\": \"*\"}" // request body
 );
 
-// Proxy an agent-scoped request (e.g., Tactical RMM)
-Mono<ResponseEntity<String>> agentResponse = restProxyService.proxyAgentRequest(
-    "tool-rmm456",
-    serverHttpRequest,
-    "{\"agentId\": \"device-001\"}"
-);
+response.subscribe(entity -> {
+    System.out.println("Status: " + entity.getStatusCode());
+    System.out.println("Body:   " + entity.getBody());
+});
 ```
 
-## Notes
-
-- SSL verification is **disabled** via `InsecureTrustManagerFactory` — intended for internal/self-signed tool endpoints
-- Response and connection timeouts are set to **60s** and **30s** respectively
-- In-memory codec buffer is capped at **16 MB** to support large upstream responses
-- `CurlLoggingHandler` is attached per connection for debug logging
-- ⚠️ Device-level access validation for agent requests is **not yet implemented** (see TODO in source)
\ No newline at end of file
+> **Note:** SSL verification is intentionally bypassed via `InsecureTrustManagerFactory` to support self-signed certificates common in on-premise MSP tool deployments. The in-memory buffer is capped at **16 MB** to handle large upstream responses. Device-level access validation for agent requests is a known TODO pending tool connection feature implementation.
\ No newline at end of file
diff --git a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/upstream/.DefaultToolUpstreamResolver.md b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/upstream/.DefaultToolUpstreamResolver.md
index 626384816..7bb346fb6 100644
--- a/openframe-gateway-service-core/src/main/java/com/openframe/gateway/upstream/.DefaultToolUpstreamResolver.md
+++ b/openframe-gateway-service-core/src/main/java/com/openframe/gateway/upstream/.DefaultToolUpstreamResolver.md
@@ -1,33 +1,42 @@
-<!-- source-hash: 8c283d4de985815c2a0dc1a45a6dc78e -->
-Serves as the default fallback implementation of `ToolUpstreamResolver`, resolving upstream REST and WebSocket URLs for integrated tools by reading configuration from MongoDB via `ToolUrlService`. Used when no dedicated resolver is registered for a given tool.
+<!-- source-hash: 8198f0b10a43612822325e14baec1882 -->
+Fallback implementation of `ToolUpstreamResolver` that resolves upstream URLs for integrated tools by reading configuration from MongoDB via `ToolUrlService`, used when no dedicated resolver is registered for a given tool.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `toolUrlService` | Dependency | Fetches `ToolUrl` entries from the `IntegratedTool` document by URL type |
-| `proxyUrlResolver` | Dependency | Builds the final proxy `URI` from tool ID, base URL, port, and incoming request URI |
-| `supportsToolId()` | Method | Returns `Optional.empty()` — signals this resolver applies to all tools without a dedicated resolver |
-| `resolveRest()` | Method | Resolves the upstream REST (`API`) URI for a given tool and request |
-| `resolveWs()` | Method | Resolves the upstream WebSocket (`WS`) URI for a given tool and request |
-| `resolveByType()` | Private | Shared logic — looks up the `ToolUrl` by type and delegates to `ProxyUrlResolver` |
+| `toolUrlService` | Dependency | Retrieves `ToolUrl` documents (REST/WS) from MongoDB for a given `IntegratedTool` |
+| `proxyUrlResolver` | Dependency | Builds the final proxy `URI` from the tool key, base URL, port, and incoming request URI |
+| `supportsToolId()` | Method | Returns `Optional.empty()` — marks this as the catch-all fallback (no specific tool ID claimed) |
+| `resolveRest()` | Method | Resolves the upstream REST URI using `ToolUrlType.API` |
+| `resolveWs()` | Method | Resolves the upstream WebSocket URI using `ToolUrlType.WS` |
+| `resolveByType()` | Private Method | Shared logic — fetches the configured `ToolUrl` by type and delegates to `ProxyUrlResolver` |
 
 ## Usage Example
 
 ```java
-// Injected automatically by Spring; called by the gateway routing pipeline
+// Injected automatically when no dedicated ToolUpstreamResolver matches the tool ID.
+// The gateway picks this resolver as the default fallback.
+
+// REST upstream resolution example:
 URI upstreamUri = defaultToolUpstreamResolver.resolveRest(
-    integratedTool,
-    serverHttpRequest,
-    "/api/v1/tools/my-tool"
+    integratedTool,   // MongoDB document for the tool (e.g., Zabbix, Grafana)
+    serverHttpRequest, // incoming reactive HTTP request
+    "/api/zabbix"      // prefix to strip before forwarding
 );
 
-// For WebSocket upgrades
+// WebSocket upstream resolution example:
 URI wsUri = defaultToolUpstreamResolver.resolveWs(
     integratedTool,
     serverHttpRequest,
-    "/ws/my-tool"
+    "/ws/zabbix"
 );
+
+// Throws IllegalStateException if no URL of the requested type
+// is configured on the IntegratedTool document.
 ```
 
-> **Note:** Throws `IllegalStateException` if the target tool has no URL configured for the requested `ToolUrlType` (`API` or `WS`). Ensure all integrated tools have both URL types populated in MongoDB before routing traffic through this resolver.
\ No newline at end of file
+## Notes
+
+- `supportsToolId()` returning `Optional.empty()` is the convention used by the resolver registry to identify this as the **default/fallback** resolver.
+- Throws `IllegalStateException` if the tool has no URL configured for the requested `ToolUrlType`, preventing silent misrouting.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/controller/.IntegratedToolController.md b/openframe-management-service-core/src/main/java/com/openframe/management/controller/.IntegratedToolController.md
index 1f47163a7..9e6e6ef53 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/controller/.IntegratedToolController.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/controller/.IntegratedToolController.md
@@ -1,62 +1,45 @@
-<!-- source-hash: 1fbd206995c35cc266ce92120466da8f -->
-REST controller managing CRUD operations for integrated tools in the OpenFrame platform, exposing endpoints under `/v1/tools` to retrieve and persist tool configurations with Debezium connector lifecycle management and post-save hook execution.
+<!-- source-hash: 987f134b86986b4575c2afb52eaaf9cf -->
+REST controller managing CRUD operations for integrated tools within the OpenFrame platform, handling tool configuration persistence, Debezium connector lifecycle, and post-save hook execution.
 
 ## Key Components
 
-| Component | Description |
-|---|---|
-| `getTools()` | Returns all registered integrated tools for the current tenant |
-| `getTool(id)` | Fetches a single tool by ID, returning a 404-style error map if not found |
-| `saveTool(id, request)` | Persists tool configuration, conditionally applies Debezium connectors, and runs post-save hooks |
-| `SaveToolRequest` | Inner DTO wrapping an `IntegratedTool` payload for the POST body |
-| `IntegratedToolPostSaveHook` | Plugin hooks executed after a successful tool save (failures are warned, not propagated) |
-| `TenantIdProvider` | Guards Debezium connector creation — connectors are only pushed to Kafka Connect after tenant registration |
+- **`getTools()`** — `GET /v1/tools` — Returns all tools for the current tenant
+- **`getTool(id)`** — `GET /v1/tools/{id}` — Fetches a single tool by ID
+- **`saveTool(id, request)`** — `POST /v1/tools/{id}` — Persists tool configuration, conditionally applies Debezium connectors based on tenant registration state, and triggers post-save hooks
+- **`SaveToolRequest`** — Inner DTO wrapping the `IntegratedTool` payload
+- **`IntegratedToolPostSaveHook`** — Extension point; all registered hooks are invoked after a successful save (failures are logged but non-fatal)
+
+### Debezium Connector Handling
+
+If no tenant is registered yet, connector definitions are stored to MongoDB only. Once a tenant is active, connectors are applied to Kafka Connect immediately via `DebeziumService`.
 
 ## Usage Example
 
 ```java
 // GET all tools
 GET /v1/tools
+// Response: { "status": "success", "tools": [...] }
 
-// GET a specific tool
-GET /v1/tools/servicenow
-
-// POST to create/update a tool configuration
-POST /v1/tools/servicenow
+// Save/update a tool configuration
+POST /v1/tools/zabbix
 Content-Type: application/json
 
 {
   "tool": {
-    "name": "ServiceNow",
-    "debeziumConnectors": [...],
-    "enabled": true
+    "name": "Zabbix",
+    "debeziumConnectors": [...]
   }
 }
-
-// Success response
-{
-  "status": "success",
-  "tool": { "id": "servicenow", "name": "ServiceNow", ... }
-}
-
-// Error response (500)
-{
-  "status": "error",
-  "message": "Connection refused"
-}
-```
-
-## Debezium Lifecycle Behavior
-
-```mermaid
-graph TD
-    A["POST /v1/tools/{id}"] --> B["Save tool to MongoDB"]
-    B --> C{"Tenant Registered?"}
-    C -->|No| D["Skip Kafka Connect — connectors stored in MongoDB only"]
-    C -->|Yes| E["Apply Debezium connectors to Kafka Connect"]
-    D --> F["Run post-save hooks"]
-    E --> F
-    F --> G["Return 200 OK"]
+// Response: { "status": "success", "tool": { ... } }
 ```
 
-> **Note:** Debezium connector templates are always persisted to MongoDB. They are only applied to Kafka Connect after a tenant is registered, enabling safe pre-registration tool configuration.
\ No newline at end of file
+```java
+// Implementing a post-save hook
+@Component
+public class MyHook implements IntegratedToolPostSaveHook {
+    @Override
+    public void onToolSaved(String toolId, IntegratedTool savedTool) {
+        // custom logic after tool is saved
+    }
+}
+```
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.OpenFrameClientConfigurationInitializer.md b/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.OpenFrameClientConfigurationInitializer.md
index 70963b745..74d9085b8 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.OpenFrameClientConfigurationInitializer.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.OpenFrameClientConfigurationInitializer.md
@@ -1,28 +1,41 @@
-<!-- source-hash: d0473e83217a8fdd18d35ad8f2fb92a0 -->
-Initializes the OpenFrame client configuration at application startup by loading a default configuration from a bundled JSON file and persisting it via the configuration service.
+<!-- source-hash: a13d98c442c54b9a145b775d16c8b3b4 -->
+Loads and applies the OpenFrame client configuration from a bundled JSON file at application startup, ensuring the client configuration is initialized before the application begins serving requests.
 
 ## Key Components
 
 | Element | Description |
-|---|---|
-| `OpenFrameClientConfigurationInitializer` | Spring `ApplicationRunner` component that runs at startup with `@Order(30)` |
-| `CONFIG_FILE` | Classpath resource path: `agent-configurations/client-configuration.json` |
-| `run()` | Reads the JSON config, assigns the default ID, and calls `updateConfigurationFields()` |
+|---------|-------------|
+| `OpenFrameClientConfigurationInitializer` | Spring `ApplicationRunner` component that executes during startup |
+| `CONFIG_FILE` | Classpath resource path `agent-configurations/client-configuration.json` |
+| `ObjectMapper` | Deserializes the JSON config file into an `OpenFrameClientConfiguration` document |
+| `OpenFrameClientConfigurationService` | Applies the deserialized configuration via `updateConfigurationFields()` |
+| `@Order(30)` | Controls execution order relative to other `ApplicationRunner` initializers |
 
 ## Usage Example
 
-This initializer runs automatically on startup. No manual invocation is required. The underlying JSON file must exist on the classpath:
+This component runs automatically on startup — no manual invocation required. To customize the client configuration, update the bundled JSON file:
 
 ```java
-// Triggered automatically by Spring Boot at startup (Order = 30)
-// Reads from: src/main/resources/agent-configurations/client-configuration.json
-
-// Internally performs:
-ClassPathResource resource = new ClassPathResource(CONFIG_FILE);
-OpenFrameClientConfiguration fromConfig =
-    objectMapper.readValue(resource.getInputStream(), OpenFrameClientConfiguration.class);
-fromConfig.setId(DEFAULT_ID);
-clientConfigurationService.updateConfigurationFields(fromConfig);
+// Classpath resource resolved at startup:
+// src/main/resources/agent-configurations/client-configuration.json
+
+// Internally, the initializer performs:
+ClassPathResource resource = new ClassPathResource("agent-configurations/client-configuration.json");
+OpenFrameClientConfiguration config = objectMapper.readValue(
+    resource.getInputStream(),
+    OpenFrameClientConfiguration.class
+);
+clientConfigurationService.updateConfigurationFields(config);
+```
+
+To register a new initializer at a specific order relative to this one, use `@Order` with a value other than `30`:
+
+```java
+@Component
+@Order(31) // Runs after OpenFrameClientConfigurationInitializer
+public class MyPostConfigInitializer implements ApplicationRunner {
+    // depends on client configuration being already applied
+}
 ```
 
-> **Note:** The `@Order(30)` annotation ensures this initializer runs after earlier-ordered startup components, maintaining a predictable initialization sequence across the OpenFrame platform.
\ No newline at end of file
+> **Note:** If the JSON file is missing or malformed, an `IOException` is thrown and will halt application startup. Ensure `client-configuration.json` is present and valid on every deployment.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.TacticalRmmScriptsInitializer.md b/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.TacticalRmmScriptsInitializer.md
index d97067f53..a5bb2f092 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.TacticalRmmScriptsInitializer.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/initializer/.TacticalRmmScriptsInitializer.md
@@ -1,20 +1,22 @@
-<!-- source-hash: a203c518ed5e9202538ba656f4c325e6 -->
-A Spring Boot application initializer that automatically synchronizes PowerShell scripts from the classpath to a Tactical RMM server during application startup.
+<!-- source-hash: 6eaccbf14030d58acd71ae10e66b1bbe -->
+Bootstraps Tactical RMM script synchronization at application startup, ensuring all configured scripts are present and up-to-date in the connected Tactical RMM instance by creating or updating them as needed.
 
 ## Key Components
 
-- **ApplicationRunner Implementation**: Executes automatically after Spring Boot application starts
-- **Script Configuration**: Manages predefined script metadata including name, resource path, description, and execution parameters
-- **Tactical RMM Integration**: Uses `TacticalRmmClient` to create and update scripts on the remote management server
-- **Resource Loading**: Loads PowerShell script content from classpath resources using Spring's `ResourceLoader`
-- **Error Handling**: Comprehensive logging and exception handling for script synchronization operations
+- **`TOOL_ID`** — Constant identifier (`"tactical-rmm"`) used to look up the integration in `IntegratedToolService`
+- **`SCRIPT_CONFIGS`** — Static list of `ScriptConfig` entries defining scripts to sync (currently: `OpenFrame Client Latest Update`, a PowerShell script for updating the OpenFrame client)
+- **`run(ApplicationArguments)`** — Entry point (`ApplicationRunner`); resolves API credentials, fetches existing remote scripts, then delegates per-script processing with success/failure tracking
+- **`processScript(...)`** — Loads script content from classpath resources and routes to create or update based on name matching
+- **`loadScriptFromResources(String)`** — Reads a classpath resource into a UTF-8 string, throwing if not found
+- **`findScriptByName(...)`** — Streams existing remote scripts to find a name match
+- **`createScript(...)`** / **`updateScript(...)`** — Builds a `CreateScriptRequest` and calls the appropriate `TacticalRmmClient` method
 
 ## Usage Example
 
-The initializer runs automatically on application startup, but here's how it processes scripts:
-
 ```java
-// Script configuration is defined as a static list
+// Automatically invoked by Spring Boot on startup via ApplicationRunner.
+// To add a new managed script, append a ScriptConfig entry:
+
 private static final List<ScriptConfig> SCRIPT_CONFIGS = List.of(
     ScriptConfig.builder()
         .name("OpenFrame Client Latest Update")
@@ -23,14 +25,17 @@ private static final List<ScriptConfig> SCRIPT_CONFIGS = List.of(
         .shell("powershell")
         .category("OpenFrame")
         .defaultTimeout(30)
+        .build(),
+
+    ScriptConfig.builder()
+        .name("My Custom Remediation Script")
+        .resourcePath("classpath:scripts/my-remediation.ps1")
+        .description("Runs custom remediation tasks")
+        .shell("powershell")
+        .category("OpenFrame")
+        .defaultTimeout(60)
         .build()
 );
-
-// The initializer automatically:
-// 1. Loads Tactical RMM connection details from IntegratedToolService
-// 2. Fetches existing scripts from the server
-// 3. Creates new scripts or updates existing ones based on configuration
-// 4. Reports success/failure statistics
 ```
 
-To add new scripts, simply add them to the `SCRIPT_CONFIGS` list and place the corresponding PowerShell files in the `src/main/resources/scripts/` directory. The initializer will handle the synchronization automatically on the next application restart.
\ No newline at end of file
+> **Note:** The corresponding `.ps1` file must exist under `src/main/resources/scripts/`. If the Tactical RMM tool is not configured in `IntegratedToolService`, startup initialization will log an error and exit gracefully without crashing the application.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillDocumentVersionChangeUnit.md b/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillDocumentVersionChangeUnit.md
index 07141b524..cab614657 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillDocumentVersionChangeUnit.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillDocumentVersionChangeUnit.md
@@ -1,37 +1,34 @@
-<!-- source-hash: 1ea71187b50e88387cd98769c35aeebe -->
-Mongock migration change unit that backfills a `documentVersion` field (set to `0L`) on all existing documents that lack it, across three MongoDB collections.
+<!-- source-hash: 188b3c7080c30240a1f5ab5618629b88 -->
+A Mongock migration change unit that backfills a `documentVersion` field (set to `0L`) on existing documents that lack it, across three MongoDB collections for a given tenant.
 
 ## Key Components
 
 | Element | Description |
 |---|---|
-| `@ChangeUnit(id = "backfill-document-version", order = "001")` | Mongock annotation registering this as the first migration to run |
-| `execution(MongoTemplate)` | Iterates the three target collections and sets `documentVersion = 0` on any document missing the field |
-| `rollback()` | No-op rollback — backfilling a version field is considered safe to leave in place |
-| `backfill(MongoTemplate, String)` | Shared helper issuing an `updateMulti` query targeting documents where `documentVersion` does not exist |
+| `@ChangeUnit(id = "backfill-document-version", order = "001")` | Mongock annotation registering this as migration step #1 |
+| `execution()` | Main migration entry point; resolves the current tenant and runs the backfill across all three collections |
+| `rollback()` | No-op rollback — adding a version field is considered safe and non-destructive |
+| `backfill()` | Core helper that queries documents missing `documentVersion` for the given tenant and sets it to `0L` via `updateMulti` |
+
+**Collections targeted:**
 
-**Targeted collections:**
 - `integrated_tool_agents`
 - `openframe_client_configuration`
 - `release_versions`
 
 ## Usage Example
 
-This class is auto-discovered and executed by Mongock at application startup. No manual invocation is needed. The underlying query it runs is equivalent to:
-
 ```java
-Query query = new Query(Criteria.where("documentVersion").exists(false));
+// Mongock discovers and executes this automatically on application startup.
+// The change unit is idempotent — only documents without documentVersion are updated.
+
+// Equivalent runtime query per collection:
+Query query = new Query(
+    Criteria.where("tenantId").is(tenantId)
+            .and("documentVersion").exists(false)
+);
 Update update = new Update().set("documentVersion", 0L);
 mongoTemplate.updateMulti(query, update, "integrated_tool_agents");
 ```
 
-Which translates to the following MongoDB operation:
-
-```javascript
-db.integrated_tool_agents.updateMany(
-  { documentVersion: { $exists: false } },
-  { $set: { documentVersion: NumberLong(0) } }
-)
-```
-
-Each run logs the number of modified documents per collection. Subsequent runs are idempotent — documents already carrying a `documentVersion` field are unaffected.
\ No newline at end of file
+> **Note:** The rollback is intentionally empty. Since this migration only *adds* a previously absent field, reverting it would risk data loss and is not required for safe recovery.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillTicketOrdersChangeUnit.md b/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillTicketOrdersChangeUnit.md
index a68d82074..81acefc81 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillTicketOrdersChangeUnit.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/migration/.BackfillTicketOrdersChangeUnit.md
@@ -1,36 +1,34 @@
-<!-- source-hash: 8c503ef7099cc80c3e65793f5bf87bb2 -->
-A Mongock database migration change unit that backfills LexoRank ordering values for existing tickets that lack an `order` field, processing each ticket status group independently.
+<!-- source-hash: 756a620ee388f243ed44abf0234c8977 -->
+A Mongock database migration change unit that backfills LexoRank-based ordering values for existing tickets that lack an `order` field, grouped by ticket status.
 
 ## Key Components
 
 | Component | Description |
 |-----------|-------------|
-| `@ChangeUnit(id = "backfill-ticket-orders", order = "002")` | Mongock annotation registering this as the second migration in the sequence |
-| `execution()` | Entry point iterating over all `TicketStatus` enum values and triggering backfill per status |
-| `backfillColumn()` | Queries tickets with a null `order` field for a given status, sorted by `createdAt` descending, then assigns sequential LexoRank values |
-| `assignOrder()` | Performs the individual MongoDB `updateFirst` to persist the generated rank string on a ticket document |
-| `rollback()` | No-op rollback — order field additions are considered non-destructive |
+| `@ChangeUnit(id = "backfill-ticket-orders", order = "002")` | Registers this as the second migration in the Mongock changelog |
+| `execution()` | Entry point — iterates all `TicketStatus` values and triggers backfill per status column |
+| `backfillColumn()` | Queries tickets with a null `order` field for a given status/tenant, assigns sequential LexoRank values sorted by `createdAt DESC` |
+| `assignOrder()` | Applies the computed LexoRank string to a single ticket document via `mongoTemplate.updateFirst()` |
+| `rollback()` | No-op rollback — intentionally left empty as rank assignment is non-destructive |
 
 ## Usage Example
 
-This class is auto-discovered and executed by Mongock at application startup. No manual invocation is needed.
+This migration runs automatically via Mongock on application startup. No manual invocation is needed. The logic it encodes:
 
 ```java
-// Mongock scans the migration package and runs registered @ChangeUnit classes
-// Execution order is determined by the `order` attribute
-
-@ChangeUnit(id = "backfill-ticket-orders", order = "002", author = "openframe")
-public class BackfillTicketOrdersChangeUnit {
-
-    @Execution
-    public void execution(MongoTemplate mongoTemplate) {
-        // Iterates TicketStatus.values() → calls backfillColumn() for each
-        // LexoRank.middle() seeds the ranking, then genNext() increments it
-        for (TicketStatus status : TicketStatus.values()) {
-            backfillColumn(mongoTemplate, status);
-        }
-    }
+// For each TicketStatus (e.g., OPEN, IN_PROGRESS, DONE)
+// Find tickets missing an order field, sorted newest-first
+Query query = new Query(Criteria.where("tenantId").is(tenantId)
+        .and("status").is(status)
+        .and("order").is(null));
+query.with(Sort.by(Sort.Direction.DESC, "createdAt"));
+
+// Assign LexoRank values starting from the middle bucket
+LexoRank rank = LexoRank.middle();
+for (Ticket ticket : tickets) {
+    assignOrder(mongoTemplate, ticket.getId(), rank.format());
+    rank = rank.genNext(); // e.g., "0|hzzzzz:" → "0|i00007:"
 }
 ```
 
-> **Note:** Only tickets where `order` is `null` are affected. Tickets already carrying an order value are skipped, making this migration safe to reason about in partial-migration scenarios.
\ No newline at end of file
+> **Note:** LexoRank ordering enables drag-and-drop ticket reordering within Kanban columns without requiring full list re-indexing. This migration ensures all pre-existing tickets receive an initial rank before that feature is used.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/migration/.MigrateTicketStatusesChangeUnit.md b/openframe-management-service-core/src/main/java/com/openframe/management/migration/.MigrateTicketStatusesChangeUnit.md
new file mode 100644
index 000000000..219df0334
--- /dev/null
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/migration/.MigrateTicketStatusesChangeUnit.md
@@ -0,0 +1,43 @@
+<!-- source-hash: c64f5d8f1e1211415b7815fcc38d2988 -->
+A Mongock `@ChangeUnit` (order `003`) that seeds system ticket status definitions and migrates legacy `status` string fields on existing ticket documents to the new structured `statusId`/`statusKind` model. Guarded by the `openframe.features.tickets.lifecycle.enabled` feature flag and marked `runAlways=true` pending full rollout.
+
+## Key Components
+
+| Member | Description |
+|---|---|
+| `LEGACY_TO_KIND` | Static mapping from legacy status strings (`ACTIVE`, `TECH_REQUIRED`, `RESOLVED`, `ARCHIVED`) to `TicketStatusKind` enum values |
+| `execution()` | Entry point — checks feature flag, seeds statuses, then migrates legacy ticket documents |
+| `seedStatuses()` | Upserts system-level `TicketStatusDefinition` records; conditionally seeds the custom `ON_HOLD` status if absent |
+| `migrateTickets()` | Finds all tenant tickets missing `statusId`, then delegates per-document migration with error isolation |
+| `migrateOne()` | Resolves the correct `TicketStatusDefinition` for a ticket's legacy status and writes `statusId`, `statusKind`, `updatedAt`; removes the old `status` field |
+| `resolveTarget()` | Handles `ON_HOLD` as a special case (name-based lookup with `TECH_REQUIRED` fallback); all other values go through kind-based lookup |
+| `rollback()` | No-op — migration is forward-only |
+
+## Usage Example
+
+```java
+// Mongock picks this up automatically via component scan.
+// Triggered on application startup when the lifecycle flag is enabled:
+
+// application.yml
+// openframe:
+//   features:
+//     tickets:
+//       lifecycle:
+//         enabled: true
+
+// Per-ticket before migration:
+// { "_id": "abc", "tenantId": "t1", "status": "ACTIVE", ... }
+
+// Per-ticket after migration:
+// {
+//   "_id": "abc",
+//   "tenantId": "t1",
+//   "statusId": "<TicketStatusDefinition._id>",
+//   "statusKind": "AI_ASSISTANCE",
+//   "updatedAt": "2025-01-15T10:30:00Z"
+//   // "status" field removed
+// }
+```
+
+> **Note:** `runAlways=true` is temporary. Once the lifecycle feature flag is permanently enabled, this should be converted to a standard one-shot migration and the flag guard removed — see the `TODO(lifecycle-rollout)` comments in the source.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/scheduler/.FleetMdmSetupScheduler.md b/openframe-management-service-core/src/main/java/com/openframe/management/scheduler/.FleetMdmSetupScheduler.md
index f30b6141a..0c165e1b4 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/scheduler/.FleetMdmSetupScheduler.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/scheduler/.FleetMdmSetupScheduler.md
@@ -1,36 +1,35 @@
-<!-- source-hash: e84196c0a607b24d3af38744629dd2db -->
-Scheduled component that periodically checks whether the Fleet MDM server integration requires setup, triggering token provisioning when the tool is present.
+<!-- source-hash: a111169c95af9f607f34ae2f6b6dff46 -->
+Scheduled Spring component that periodically checks whether the FleetMDM server integration requires setup, triggering API token generation and persistence when the tool is present.
 
 ## Key Components
 
 | Element | Description |
-|---|---|
-| `@ConditionalOnProperty` | Activates only when `openframe.fleet-mdm.setup.enabled=true` |
-| `FLEETMDM_SERVER` | Constant ID (`"fleetmdm-server"`) used to look up the tool in the repository |
-| `runSetupIfNeeded()` | Scheduled task that queries `IntegratedToolRepository` and delegates to `FleetMdmSetupService` if the tool record exists |
-| `scheduler-interval-ms` | Configurable polling interval (default: `30000` ms) |
+|---------|-------------|
+| `@ConditionalOnProperty` | Activates the scheduler only when `openframe.fleet-mdm.setup.enabled=true` |
+| `FLEETMDM_SERVER` | Repository lookup key (`"fleetmdm-server"`) used to find the integrated tool record |
+| `runSetupIfNeeded()` | Scheduled method that queries the tool repository and delegates to `FleetMdmSetupService` if the tool is found |
+| `fixedDelayString` | Polling interval controlled by `openframe.fleet-mdm.setup.scheduler-interval-ms` (default: 30 seconds) |
 
 ## Usage Example
 
 ```java
-// application.yml
+// application.yml configuration to enable and tune the scheduler
 openframe:
   fleet-mdm:
     setup:
       enabled: true
-      scheduler-interval-ms: 60000  # override default 30s interval
+      scheduler-interval-ms: 60000  # Poll every 60 seconds
 ```
 
 ```java
-// The scheduler fires automatically at the configured interval.
-// If the "fleetmdm-server" tool entry exists in the DB, setup is triggered:
-toolRepository.findById("fleetmdm-server")
+// The scheduler automatically fires on the configured interval.
+// If fleetmdm-server is registered in IntegratedToolRepository,
+// FleetMdmSetupService handles token setup:
+toolRepository.findByKey("fleetmdm-server")
     .ifPresent(fleetMdmSetupService::setupAndSaveApiToken);
-// Errors are caught and logged; the next tick will retry automatically.
-```
 
-## Behavior Notes
+// Errors are caught and logged; the scheduler retries on the next tick
+// without crashing the application context.
+```
 
-- **Conditional activation** — the bean is only registered when the feature flag is `true`; no-op in environments where Fleet MDM setup is disabled.
-- **Non-fatal errors** — exceptions are caught, logged, and silently retried on the next scheduled tick to avoid crashing the scheduler thread.
-- **Idempotent design** — `setupAndSaveApiToken` is expected to be safe to call repeatedly; the scheduler does not track state between ticks.
\ No newline at end of file
+> **Note:** Setting `openframe.fleet-mdm.setup.enabled=false` (or omitting it) disables the bean entirely — no polling occurs, and no Fleet MDM setup is attempted.
\ No newline at end of file
diff --git a/openframe-management-service-core/src/main/java/com/openframe/management/service/.ReleaseVersionService.md b/openframe-management-service-core/src/main/java/com/openframe/management/service/.ReleaseVersionService.md
index d988e19be..ff3b75ef9 100644
--- a/openframe-management-service-core/src/main/java/com/openframe/management/service/.ReleaseVersionService.md
+++ b/openframe-management-service-core/src/main/java/com/openframe/management/service/.ReleaseVersionService.md
@@ -1,30 +1,47 @@
-<!-- source-hash: 7f62405f7fc896122eeb6237a08d5ea2 -->
-Manages the lifecycle of release versions within the OpenFrame platform, handling creation, updates, and propagation of version changes across client configurations and integrated tool agents.
+<!-- source-hash: 35a044fb29d6bb36ec575d3a190a4bb1 -->
+Manages the lifecycle of OpenFrame platform release versions, handling creation, update, and propagation of version information across client configurations and integrated tool agents.
 
 ## Key Components
 
 | Member | Type | Description |
 |--------|------|-------------|
-| `process(String releaseVersion)` | Public Method | Entry point for version processing; creates or updates the persisted release version record with optimistic locking retry support |
-| `updateExistingReleaseVersion(...)` | Private Method | Updates an existing version record if outdated, then triggers propagation (idempotent — propagates even if already up to date) |
-| `createNewReleaseVersion(...)` | Private Method | Persists a new `ReleaseVersion` document using `ReleaseVersion.DEFAULT_ID` and triggers propagation |
-| `propagate(String version)` | Private Method | Coordinates downstream updates: refreshes `OpenFrameClientConfiguration` and all release-flagged tool agents |
-| `updateReleaseAgents(String version)` | Private Method | Fetches all `IntegratedToolAgent` records with `releaseVersion=true` and updates each to the new version |
+| `process(String releaseVersion)` | `@RetryOnOptimisticLockingFailure` method | Entry point — upserts the release version record and triggers propagation |
+| `updateExistingReleaseVersion(...)` | Private method | Updates an existing `ReleaseVersion` document if the version has changed; propagates regardless for idempotency |
+| `createNewReleaseVersion(...)` | Private method | Creates the initial `ReleaseVersion` document when none exists |
+| `propagate(String version)` | Private method | Fans out the new version to client configurations and all release-flagged tool agents |
+| `updateReleaseAgents(String version)` | Private method | Fetches all `IntegratedToolAgent` records where `releaseVersion=true` and updates each to the new version |
 
 ## Usage Example
 
 ```java
-// Typically invoked during a deployment or version sync event
+// Injected via Spring context
 @Autowired
 private ReleaseVersionService releaseVersionService;
 
-// Process (create or update) the platform release version
-// Automatically propagates to client configs and release agents
-releaseVersionService.process("2.4.1");
+// Called during a deployment pipeline or version sync event
+releaseVersionService.process("2.14.0");
+
+// Internally, the service will:
+// 1. Upsert the ReleaseVersion document in the repository
+// 2. Push the new version to OpenFrameClientConfigurationService
+// 3. Update all IntegratedToolAgents flagged as release agents
 ```
 
-## Notes
+## Flow
+
+```mermaid
+graph TD
+    A["process(releaseVersion)"] --> B{"ReleaseVersion exists?"}
+    B -->|"Yes"| C{"Version changed?"}
+    B -->|"No"| D["createNewReleaseVersion()"]
+    C -->|"No"| E["Log idempotent re-run"]
+    C -->|"Yes"| F["Update & save document"]
+    E --> G["propagate(version)"]
+    F --> G
+    D --> G
+    G --> H["updateVersion() on ClientConfig"]
+    G --> I["updateReleaseAgents()"]
+    I --> J["Update each flagged IntegratedToolAgent"]
+```
 
-- Annotated with `@RetryOnOptimisticLockingFailure` to handle concurrent version update conflicts gracefully.
-- Propagation is always triggered after processing — even when the version is unchanged — ensuring idempotent behaviour across restarts or replays.
-- Agents are filtered via `integratedToolAgentService.findByReleaseVersionTrue()`, meaning only agents explicitly marked as release agents receive the version update.
\ No newline at end of file
+> **Note:** `process()` is annotated with `@RetryOnOptimisticLockingFailure` to safely handle concurrent version update conflicts at the database layer.
\ No newline at end of file
diff --git a/openframe-stream-service-core/src/main/java/com/openframe/stream/service/.IntegratedToolDataEnrichmentService.md b/openframe-stream-service-core/src/main/java/com/openframe/stream/service/.IntegratedToolDataEnrichmentService.md
index ec9440ced..849af1d39 100644
--- a/openframe-stream-service-core/src/main/java/com/openframe/stream/service/.IntegratedToolDataEnrichmentService.md
+++ b/openframe-stream-service-core/src/main/java/com/openframe/stream/service/.IntegratedToolDataEnrichmentService.md
@@ -1,47 +1,38 @@
-<!-- source-hash: 8e06947ef80122a0a9b1bfee3330c5d4 -->
-Enriches deserialized Debezium messages from integrated tools with machine, organization, and tenant context by resolving cached data before downstream processing.
+<!-- source-hash: 031f80dd245a28e2a5e0d72f57f6be2d -->
+Enriches deserialized Debezium CDC messages from integrated tools with machine and tenant metadata by resolving agent IDs and cluster identifiers against cached data sources.
 
 ## Key Components
 
-| Member | Type | Description |
-|--------|------|-------------|
-| `getExtraParams()` | Method | Entry point that orchestrates enrichment, returning an `IntegratedToolEnrichedData` object |
-| `enrichFromMachine()` | Method | Resolves `machineId`, `hostname`, `organizationId`, and `organizationName` from Redis cache via `MachineIdCacheService` using the message's `agentId` |
-| `enrichFromTenant()` | Method | Resolves `tenantId` — uses `TenantIdProvider` for single-tenant clusters, or `ClusterTenantIdResolver` for shared/multi-tenant clusters |
-| `getType()` | Method | Identifies this service as `INTEGRATED_TOOLS_EVENTS` for the `DataEnrichmentService` registry |
-| `clusterTenantIdResolver` | Dependency | Optional bean (`required = false`) — absent on dedicated tenant clusters, present on shared clusters (e.g., MeshCentral domain mapping) |
+| Component | Description |
+|-----------|-------------|
+| `getExtraParams(DeserializedDebeziumMessage)` | Entry point that returns an `IntegratedToolEnrichedData` object populated with machine and tenant context |
+| `enrichFromMachine(...)` | Resolves `agentId` → `CachedMachineInfo` (machineId, hostname) and `organizationId`/`organizationName` via Redis cache |
+| `enrichFromTenant(...)` | Resolves tenantId using either `TenantIdProvider` (dedicated tenant clusters) or `ClusterTenantIdResolver` (shared clusters mapping domain → canonical tenantId) |
+| `getType()` | Returns `DataEnrichmentServiceType.INTEGRATED_TOOLS_EVENTS`, identifying this service in the enrichment pipeline |
+| `ClusterTenantIdResolver` | Optional bean (`required = false`); when absent, the cluster is treated as single-tenant |
 
 ## Usage Example
 
 ```java
-// Typically invoked by a stream processor after Debezium deserialization
-DeserializedDebeziumMessage message = debeziumDeserializer.deserialize(record);
+// Injected automatically by Spring in the enrichment pipeline
+@Autowired
+IntegratedToolDataEnrichmentService enrichmentService;
 
+DeserializedDebeziumMessage message = kafkaConsumer.poll();
+
+// Returns enriched metadata; also mutates message.tenantId in-place
 IntegratedToolEnrichedData enriched = enrichmentService.getExtraParams(message);
 
-// enriched now carries resolved context
-log.info("Processing event for tenant={} machine={} org={}",
-    enriched.getTenantId(),
+log.info("machineId={}, hostname={}, org={}, tenant={}",
     enriched.getMachineId(),
-    enriched.getOrganizationName()
+    enriched.getHostname(),
+    enriched.getOrganizationName(),
+    enriched.getTenantId()
 );
 ```
 
-## Enrichment Flow
-
-```mermaid
-graph TD
-    A["DeserializedDebeziumMessage"] --> B["getExtraParams()"]
-    B --> C["enrichFromMachine()"]
-    B --> D["enrichFromTenant()"]
-    C --> E["MachineIdCacheService.getMachine(agentId)"]
-    E -->|"found"| F["Set machineId + hostname"]
-    F --> G["MachineIdCacheService.getOrganization()"]
-    G -->|"found"| H["Set organizationId + organizationName"]
-    D --> I{"ClusterTenantIdResolver\npresent?"}
-    I -->|"No (dedicated cluster)"| J["TenantIdProvider.getTenantId()"]
-    I -->|"Yes (shared cluster)"| K["ClusterTenantIdResolver.resolveTenantId()"]
-    J --> L["IntegratedToolEnrichedData"]
-    K --> L
-    H --> L
-```
\ No newline at end of file
+## Notes
+
+- `MachineIdCacheService` is backed by Redis; a cache miss logs a `WARN` and skips machine-level fields.
+- `ClusterTenantIdResolver` is **optional** — omit the bean for dedicated single-tenant cluster deployments (e.g., MeshCentral `domain`-based multi-tenant setups require it).
+- Both `enriched.tenantId` and `message.tenantId` are updated in `enrichFromTenant`, keeping the source message consistent for downstream processors.
\ No newline at end of file
diff --git a/openframe-test-service-core/src/main/java/com/openframe/test/helpers/.RequestSpecHelper.md b/openframe-test-service-core/src/main/java/com/openframe/test/helpers/.RequestSpecHelper.md
index 311610d10..68f040df4 100644
--- a/openframe-test-service-core/src/main/java/com/openframe/test/helpers/.RequestSpecHelper.md
+++ b/openframe-test-service-core/src/main/java/com/openframe/test/helpers/.RequestSpecHelper.md
@@ -1,25 +1,33 @@
-<!-- source-hash: 93748ef101ded8d5cf8c44eefaa7438b -->
-Utility class for building and managing REST Assured `RequestSpecification` objects in the OpenFrame test framework, providing thread-safe session management, SSL configuration, and SLF4J-integrated request logging.
+<!-- source-hash: c82437cfcdba9b1362a43fe951716e39 -->
+Builds and configures RestAssured `RequestSpecification` objects for OpenFrame API tests, providing authorized, unauthorized, and auth-flow request specs with retry logic, SSL relaxation, and SLF4J-routed logging.
 
 ## Key Components
 
-| Method/Field | Description |
-|---|---|
-| `getAuthorizedSpec()` | Builds a request spec with session cookies attached for authenticated API calls |
-| `getUnAuthorizedSpec()` | Builds a base request spec without authentication cookies |
-| `getAuthFlowRequestSpec()` | Builds a request spec targeting the auth URL (for login/token flows) |
-| `graphqlSuccess()` | Returns a `ResponseSpecification` asserting HTTP 200 with no GraphQL `errors` field |
-| `setCookies()` / `getCookies()` | Thread-local cookie store; lazily fetches from `AuthHelper` if unset |
-| `setBaseUrl()` / `getBaseUrl()` | Thread-local base URL override; falls back to `EnvironmentConfig.getBaseUrl()` |
-| `setEnableLogging()` | Toggles request logging via the SLF4J stream |
-| `Slf4jOutputStream` | Inner class that bridges REST Assured's `PrintStream` output to SLF4J `Logger` |
-
-All specs are pre-configured with a **32-second timeout**, relaxed HTTPS validation, and JSON content type.
+| Member | Description |
+|--------|-------------|
+| `getAuthorizedSpec()` | Returns a `RequestSpecification` with session cookies attached (auto-fetches via `AuthHelper` if not set) |
+| `getUnAuthorizedSpec()` | Returns a bare `RequestSpecification` with no credentials |
+| `getAuthFlowRequestSpec()` | Returns a spec targeting the auth URL (used during login/token flows) |
+| `graphqlSuccess()` | `ResponseSpecification` asserting HTTP 200 and no `errors` field in the GraphQL response body |
+| `setBaseUrl(String)` / `setCookies(Map)` | Thread-local overrides for base URL and cookies, safe for parallel test execution |
+| `clearCookies()` | Removes the thread-local cookie store (forces re-authentication on next use) |
+| `setEnableLogging(boolean)` | Toggles `RequestLoggingFilter` globally |
+| `retryingHttpClientConfig()` | Configures 10 s connect / 32 s socket timeouts with up to 2 connect-failure retries |
+| `Slf4jOutputStream` (inner) | Bridges RestAssured's `PrintStream` logging to SLF4J line-by-line |
 
 ## Usage Example
 
 ```java
-// Authenticated request
+// Authorized JSON request
+given()
+    .spec(RequestSpecHelper.getAuthorizedSpec())
+    .body(payload)
+.when()
+    .post("/api/devices")
+.then()
+    .statusCode(201);
+
+// GraphQL request with success assertion
 given()
     .spec(RequestSpecHelper.getAuthorizedSpec())
     .body(graphqlQuery)
@@ -28,20 +36,16 @@ given()
 .then()
     .spec(RequestSpecHelper.graphqlSuccess());
 
-// Override base URL per thread (e.g., in parallel tests)
+// Override base URL per thread (e.g. in parallel test suites)
 RequestSpecHelper.setBaseUrl("https://staging.openframe.ai");
 
-// Unauthenticated request
+// Unauthenticated call (e.g. testing 401 responses)
 given()
     .spec(RequestSpecHelper.getUnAuthorizedSpec())
 .when()
-    .get("/public/health");
+    .get("/api/protected")
+.then()
+    .statusCode(401);
+```
 
-// Auth flow (login endpoint)
-given()
-    .spec(RequestSpecHelper.getAuthFlowRequestSpec())
-    .formParam("username", user)
-    .formParam("password", pass)
-.when()
-    .post("/auth/login");
-```
\ No newline at end of file
+> **Retry behaviour:** Only connect-establishment failures (`ConnectException`, `ConnectTimeoutException`) are retried — never socket/read timeouts — ensuring mutations are not replayed after the server has already received the request.
\ No newline at end of file
diff --git a/openframe-test-service-core/src/main/java/com/openframe/test/tests/.KnowledgeBaseTest.md b/openframe-test-service-core/src/main/java/com/openframe/test/tests/.KnowledgeBaseTest.md
index 8aec5016e..d985fe26c 100644
--- a/openframe-test-service-core/src/main/java/com/openframe/test/tests/.KnowledgeBaseTest.md
+++ b/openframe-test-service-core/src/main/java/com/openframe/test/tests/.KnowledgeBaseTest.md
@@ -1,46 +1,29 @@
-<!-- source-hash: 2abeccff34e1f27481a9ed41bf817a4a -->
-JUnit 5 integration test suite for the OpenFrame Knowledge Base API, covering CRUD operations and folder/article management via `KnowledgeBaseApi`.
+<!-- source-hash: e093f2171cf5c0d80de87b630d692cc8 -->
+JUnit 5 integration test suite validating the OpenFrame Knowledge Base API, covering CRUD operations for folders and articles, tag retrieval, and item lifecycle management (draft → publish).
 
 ## Key Components
 
-| Test Method | Tag(s) | Description |
+| Test Method | Tags | Description |
 |---|---|---|
-| `testGetRootFolders` | `saas`, `read` | Validates root folder listing — checks id, name, type, parentId, timestamps |
-| `testGetArticlesInFolder` | `saas`, `read` | Finds a folder containing articles and validates article fields + filtered count |
-| `testGetAllTags` | `saas`, `read` | Asserts at least one tag exists with non-blank id and key |
-| `testCreateDraftArticle` | `saas` | Creates a folder, attaches a tag, creates a draft article, validates all fields |
-| `testPublishArticle` | `saas` | Creates a draft then publishes it, verifies status transitions to `PUBLISHED` |
-| `testUpdateArticle` | `saas` | Creates an article, updates name/content/summary, verifies field changes and `updatedAt` mutation |
-| `testCreateAndDeleteFolder` | `saas` | Creates a root folder and immediately deletes it |
-| `testRenameFolder` | `saas` | Creates and renames a folder, verifies new name |
-| `testMoveToFolder` | `saas` | Creates parent/child folders, moves child under parent, validates `parentId` |
-| `testGetKnowledgeBaseItemById` | `saas` | Creates a folder + article, fetches by id (truncated in source) |
+| `testGetRootFolders` | `saas`, `read` | Verifies root folder listing returns valid items with required fields |
+| `testGetArticlesInFolder` | `saas`, `read` | Fetches articles within a folder and validates filtered count consistency |
+| `testGetAllTags` | `saas`, `read` | Asserts at least one tag exists with non-blank `id` and `key` |
+| `testCreateDraftArticle` | `saas` | Creates a folder + draft article with tags, validates all returned fields |
+| `testPublishArticle` | `saas` | Creates a draft then publishes it, asserting status transitions to `PUBLISHED` |
+| `testUpdateArticle` | `saas` | Updates name, content, and summary; asserts `updatedAt` changes |
+| `testCreateAndDeleteFolder` | `saas` | Creates a root folder and hard-deletes it, asserting `true` on delete |
+| `testRenameFolder` | `saas` | Renames a folder and verifies the new name is persisted |
+| `testMoveToFolder` | `saas` | Moves a child folder under a parent and checks `parentId` update |
+| `testGetKnowledgeBaseItemById` | `saas` | Fetches both a folder and article by ID and validates their fields |
 
 ## Usage Example
 
 ```java
-// Run only read-only tests against SaaS environment
-@Tag("saas")
-@Tag("read")
-@Test
-@DisplayName("Get root folders")
-public void testGetRootFolders() {
-    List<KnowledgeBaseItem> folders = KnowledgeBaseApi.getKnowledgeBaseItems(
-        rootFoldersFilter(), null, 100
-    );
+// Run only read-scoped SaaS tests via Maven Surefire tag filter
+mvn test -Dgroups="saas & read" -Dtest=KnowledgeBaseTest
 
-    assertThat(folders).isNotEmpty();
-    assertThat(folders).allSatisfy(folder -> {
-        assertThat(folder.getType()).isEqualTo(KnowledgeBaseItemType.FOLDER);
-        assertThat(folder.getParentId()).isNull(); // root = no parent
-    });
-}
-
-// Create and publish an article
-KnowledgeBaseItem folder = KnowledgeBaseApi.createFolder(randomFolderName(), null);
-KnowledgeBaseItem draft = KnowledgeBaseApi.createArticle(draftArticle(folder.getId(), List.of()));
-KnowledgeBaseItem published = KnowledgeBaseApi.publishArticle(draft.getId());
-assertThat(published.getStatus()).isEqualTo(KnowledgeBaseArticleStatus.PUBLISHED);
+// Run the full suite (remove @Disabled to enable)
+mvn test -Dtest=KnowledgeBaseTest
 ```
 
-> **Note:** All tests extend `BaseTest` and are tagged `saas`. Read-only tests additionally carry the `read` tag, enabling selective CI execution. Test data is generated via `KnowledgeBaseGenerator` static factory methods such as `randomFolderName()` and `draftArticle()`.
\ No newline at end of file
+> **Note:** The class is annotated with `@Disabled` — remove this annotation to include these tests in CI runs. All write tests (`testCreate*`, `testPublish*`, etc.) generate isolated resources using `randomFolderName()` and `draftArticle()` from `KnowledgeBaseGenerator`.
\ No newline at end of file
diff --git a/openframe-test-service-core/src/main/java/com/openframe/test/tests/.TicketsTest.md b/openframe-test-service-core/src/main/java/com/openframe/test/tests/.TicketsTest.md
index 55cd9e038..9a0a73435 100644
--- a/openframe-test-service-core/src/main/java/com/openframe/test/tests/.TicketsTest.md
+++ b/openframe-test-service-core/src/main/java/com/openframe/test/tests/.TicketsTest.md
@@ -1,19 +1,19 @@
-<!-- source-hash: 05d3c9e989476e1dc291b1d06f3e8487 -->
-Integration test suite for the OpenFrame ticket management API, covering the full lifecycle of ticket operations including creation, status transitions, ordering, and retrieval.
+<!-- source-hash: 891d5f272c5ca3af509e9dfa28321fb0 -->
+Integration test suite for the OpenFrame ticket management API, covering the full ticket lifecycle from creation through status transitions (active → on hold → resolved → archived) and supporting operations like listing, label retrieval, reordering, and validation of invalid state transitions.
 
 ## Key Components
 
-| Method | Tags | Description |
-|--------|------|-------------|
-| `testListTickets()` | `saas`, `read` | Verifies paginated ticket listing returns valid edges with mandatory fields |
-| `testListTicketLabels()` | `saas`, `read` | Validates that ticket labels exist and contain required `id` and `key` fields |
-| `testCreateTicket()` | — | Creates a fully-populated ticket with assignee, organization, device, and label; asserts all returned fields |
-| `testPutTicketOnHold()` | Order 2 | Transitions an `ACTIVE` ticket to `ON_HOLD` status |
-| `testResolveTicket()` | Order 3 | Transitions an `ACTIVE` ticket to `RESOLVED` and verifies `resolvedAt` is set |
-| `testArchiveActiveTicketRejected()` | — | Confirms that archiving an `ACTIVE` ticket is rejected with a user error describing the invalid status transition |
-| `testArchiveTicket()` | Order 4 | Resolves then archives a ticket; verifies `ARCHIVED` status |
-| `testReorderTicket()` | Order 5 | Reorders a ticket among its neighbors and asserts the `order` key changes |
-| `testGetTicket()` | `saas`, `read` | Fetches a single ticket by ID and verifies mandatory fields including `owner` |
+| Method | Tags/Order | Description |
+|---|---|---|
+| `testListTickets()` | `saas`, `read` | Fetches paginated active tickets and validates mandatory fields (`id`, `ticketNumber`, `title`, `status`) |
+| `testListTicketLabels()` | `saas`, `read` | Retrieves all ticket labels and asserts `id` and `key` are present |
+| `testCreateTicket()` | Order 1 | Creates a ticket with assignee, organization, device, and label; validates all returned fields |
+| `testPutTicketOnHold()` | Order 2 | Transitions an `ACTIVE` ticket to `ON_HOLD` |
+| `testResolveTicket()` | Order 3 | Transitions an `ACTIVE` ticket to `RESOLVED` and checks `resolvedAt` is set |
+| `testArchiveActiveTicketRejected()` | — | Asserts that archiving an `ACTIVE` ticket returns user errors with an invalid transition message |
+| `testArchiveTicket()` | Order 4 | Resolves then archives a ticket; validates `ARCHIVED` status |
+| `testReorderTicket()` | Order 5 | Reorders tickets using before/after anchors and verifies the order key changes |
+| `testGetTicket()` | `saas`, `read` | Fetches a single ticket by ID and validates fields including `owner` |
 
 ## Usage Example
 
@@ -21,17 +21,20 @@ Integration test suite for the OpenFrame ticket management API, covering the ful
 // Run only read-safe SaaS tests (no mutations)
 // mvn test -Dgroups="saas & read"
 
-// Full lifecycle: create → hold → resolve → archive
+// Full lifecycle test run (requires at least 3 active tickets and a valid assignee)
+TicketConnection connection = TicketApi.getTickets(
+    TicketGenerator.activeTickets(),
+    CursorPaginationInput.builder().limit(20).build(),
+    null);
+
 CreateTicketInput input = TicketGenerator.createTicketRequest(
-        organization.getOrganizationId(),
-        device.getMachineId(),
-        assigneeId,
-        List.of(labelId));
-
-Ticket ticket  = TicketApi.createTicket(input);           // ACTIVE
-Ticket onHold  = TicketApi.putTicketOnHold(ticket.getId()); // ON_HOLD
-Ticket resolved = TicketApi.resolveTicket(ticket.getId());  // RESOLVED
-Ticket archived = TicketApi.archiveTicket(ticket.getId());  // ARCHIVED
+    organization.getOrganizationId(),
+    device.getMachineId(),
+    assigneeId,
+    List.of(labelId));
+
+Ticket ticket = TicketApi.createTicket(input);
+// Lifecycle: createTicket → putTicketOnHold → resolveTicket → archiveTicket
 ```
 
-> **Status transition rules enforced:** Direct `ACTIVE → ARCHIVED` is rejected by the API and validated in `testArchiveActiveTicketRejected()`. Tickets must be `RESOLVED` before they can be archived.
\ No newline at end of file
+> **Note:** The class is annotated `@Disabled` at the class level. Remove or override this annotation to enable execution. Tests tagged `saas`+`read` are safe for read-only environments; ordered tests (1–5) require a writable environment with pre-existing users, organizations, and devices.
\ No newline at end of file
diff --git a/react-embedding-example/.tailwind.config.md b/react-embedding-example/.tailwind.config.md
new file mode 100644
index 000000000..f77c2ff06
--- /dev/null
+++ b/react-embedding-example/.tailwind.config.md
@@ -0,0 +1,35 @@
+<!-- source-hash: 6d6ae1558185f95a961b9e4a50b4775f -->
+Tailwind CSS configuration for the application, composing design tokens, fonts, and animations from the OpenFrame Frontend Core preset while extending content scanning to include both local source files and the core library's compiled output.
+
+## Key Components
+
+- **`openframeCorePreset`** — Imported preset from `@flamingo-stack/openframe-frontend-core` providing ODS tokens, custom fonts, and animations
+- **`presets`** — Merges the core preset using Tailwind's native preset composition (not object-spread)
+- **`content`** — Glob patterns covering local HTML/TS/TSX sources and pre-compiled library dist files to prevent class purging
+
+## Usage Example
+
+```typescript
+// Extend the config locally without overriding core preset tokens
+import type { Config } from 'tailwindcss'
+import openframeCorePreset from '@flamingo-stack/openframe-frontend-core/tailwind.config.ts'
+
+export default {
+  presets: [openframeCorePreset as Config],
+  content: [
+    './index.html',
+    './src/**/*.{ts,tsx}',
+    './node_modules/@flamingo-stack/openframe-frontend-core/dist/**/*.{js,mjs,cjs}',
+  ],
+  // Add app-level extensions here — core tokens remain intact
+  theme: {
+    extend: {
+      colors: {
+        'app-accent': '#FF6B35',
+      },
+    },
+  },
+} satisfies Config
+```
+
+> **Note:** Always use `presets: [corePreset]` instead of spreading the core config object. Tailwind's preset system handles deep merging of `theme`, `plugins`, and `variants` — object-spread will silently drop inherited rules.
\ No newline at end of file
diff --git a/react-embedding-example/.vite.config.md b/react-embedding-example/.vite.config.md
new file mode 100644
index 000000000..ef0b70562
--- /dev/null
+++ b/react-embedding-example/.vite.config.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 32054aa9fee20f33c9989b2032fbd9fa -->
+Vite configuration for the OpenFrame frontend dev server and preview server, wiring up React, proxy rules, module deduplication, and pre-bundling for the linked `@flamingo-stack/openframe-frontend-core` library.
+
+## Key Components
+
+- **`hubTarget` / `injectHeaders`** — proxy helpers that resolve the hub origin and inject chat secrets + identity headers server-side (secrets stay in Node config, never in the bundle)
+- **`CONTENT_PREFIX`** proxy rule — forwards `/content/api/*` → `${HUB_ORIGIN}/api/*` with path rewriting
+- **Bare `/api` fallbacks** — temporary dev-only routes (`/api/docs/search`, `/api/chat/agent`) for lib hooks that still hardcode bare paths
+- **`resolve.dedupe`** — enforces a single copy of React, React DOM, React Router, and TanStack Query across the app and the linked lib (prevents "invalid hook call" and split context provider issues)
+- **`next/font/google` stub** — aliases the Next.js font macro to a local stub so accidental imports don't break the Vite build
+- **`optimizeDeps.include`** — pre-bundles all `openframe-frontend-core` entry points via esbuild, preventing mid-rebuild 404s and Babel 500 KB deoptimisation warnings during dev
+
+## Usage Example
+
+```bash
+# Dev server — force re-bundle on every start (picks up lib edits)
+npm run dev -- --force
+
+# Preview server (uses the same proxy config)
+npm run preview
+```
+
+```typescript
+// proxy/inject.mjs contract expected by this config
+export function hubTarget(env: Record<string, string>): string
+export function injectHeaders(proxyReq: { setHeader: ... }, env: Record<string, string>): void
+export function rewrite(path: string): string
+```
+
+> **Note:** All environment variables are loaded with an empty prefix (`''`) via `loadEnv`, so secrets like `HUB_ORIGIN` and the chat secret are available to the Node config layer only — they are never injected into the client bundle.
\ No newline at end of file
diff --git a/react-embedding-example/src/.app-routes.md b/react-embedding-example/src/.app-routes.md
new file mode 100644
index 000000000..c51fe0fec
--- /dev/null
+++ b/react-embedding-example/src/.app-routes.md
@@ -0,0 +1,42 @@
+<!-- source-hash: 93de562d5ef74a8bc928aedcb352d13a -->
+Defines the application's client-side route tree using React Router v6, mapping URL paths to page components within a shared `AppShell` layout.
+
+## Key Components
+
+- **`AppRoutes`** — Root routing component that wraps all routes inside `AppShell` and exports a single registry of all application surfaces
+- **`AppShell`** — Persistent layout wrapper (nav, shell chrome) rendered as the parent `Route` element
+- **`PageError`** — Catch-all `*` route rendering a "Page not found" error for unmatched paths
+
+## Route Map
+
+| Path | Component |
+|------|-----------|
+| `/` | `HomePage` |
+| `/onboarding-guides` | `OnboardingCatalogPage` |
+| `/onboarding-guides/:slug` | `OnboardingDetailPage` |
+| `/roadmap` | `RoadmapPage` |
+| `/delivery` | `DeliveryPage` |
+| `/releases` | `ReleasesPage` |
+| `/releases/:slug` | `ReleaseDetailRoute` |
+| `/legal/:docType` | `LegalPage` |
+| `/contact` | `ContactPage` |
+| `/tickets` | `TicketsPage` |
+| `*` | `PageError` |
+
+## Usage Example
+
+```typescript
+// Mount at the application entry point
+import { BrowserRouter } from 'react-router-dom'
+import { AppRoutes } from './app-routes'
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  )
+}
+```
+
+> **Adding a new surface:** declare a single `<Route>` inside `AppRoutes` — the shared shell and error boundary are inherited automatically.
\ No newline at end of file
diff --git a/react-embedding-example/src/.main.md b/react-embedding-example/src/.main.md
new file mode 100644
index 000000000..218ee8505
--- /dev/null
+++ b/react-embedding-example/src/.main.md
@@ -0,0 +1,31 @@
+<!-- source-hash: cf6fe1ed57cc6005d9bc6072697a6631 -->
+Application entry point that bootstraps the React app by mounting the component tree into the DOM, registering the embed router bridge, and importing global styles.
+
+## Key Components
+
+- **`registerEmbedRouterBridge()`** — Called before first render to wire `react-router` navigation into the embed shims layer, replacing the fallback `popstate`-only mechanism
+- **`AppProviders`** — Wraps the app with all required context providers
+- **`AppRoutes`** — Defines the top-level route configuration
+- **`BrowserRouter`** — Provides client-side routing context
+- **`@flamingo-stack/openframe-frontend-core/styles`** — Imports ODS design tokens, chat keyframes, and fonts exactly once before any lib surface renders
+
+## Usage Example
+
+```typescript
+// This file is the Vite/bundler entrypoint — referenced in index.html:
+// <script type="module" src="/src/main.tsx"></script>
+
+// Execution order:
+// 1. Global styles imported (ODS tokens, fonts, keyframes)
+// 2. registerEmbedRouterBridge() called synchronously
+// 3. ReactDOM.createRoot mounts the tree:
+//    <BrowserRouter>
+//      <AppProviders>   ← all context/providers
+//        <AppRoutes />  ← route definitions
+//      </AppProviders>
+//    </BrowserRouter>
+```
+
+## Notes
+
+- **No `<React.StrictMode>`** by design — this reference app mirrors production network behavior exactly. StrictMode's dev-only double-invocation produces duplicate cancelled fetch requests in the network panel, which is misleading for demos. The underlying library remains StrictMode-safe (covered by its Vitest suite).
\ No newline at end of file
diff --git a/react-embedding-example/src/.vite-env.d.md b/react-embedding-example/src/.vite-env.d.md
new file mode 100644
index 000000000..371cedee6
--- /dev/null
+++ b/react-embedding-example/src/.vite-env.d.md
@@ -0,0 +1,25 @@
+<!-- source-hash: 08e4a6d28d6d13801ae7493cf3934e49 -->
+Vite environment type declarations that extend the default `ImportMeta` interface with application-specific environment variables.
+
+## Key Components
+
+- **`ImportMetaEnv`** — Augments Vite's built-in env interface with a custom variable:
+  - `VITE_HUB_ORIGIN` *(optional string)* — Public hub origin URL used for new-tab content links in embed mode
+- **`ImportMeta`** — Re-declares `env` as the extended `ImportMetaEnv` type to enable full IntelliSense on `import.meta.env`
+
+## Usage Example
+
+```typescript
+// Access the hub origin at runtime with full type safety
+const hubOrigin = import.meta.env.VITE_HUB_ORIGIN ?? 'https://default.hub.example.com'
+
+const contentUrl = `${hubOrigin}/path/to/resource`
+window.open(contentUrl, '_blank')
+```
+
+```bash
+# .env or .env.local
+VITE_HUB_ORIGIN=https://hub.flamingo.run
+```
+
+> **Note:** Variables prefixed with `VITE_` are exposed to client-side code by Vite's build pipeline. Any variable without this prefix remains server-side only and will be `undefined` in the browser bundle.
\ No newline at end of file
diff --git a/react-embedding-example/src/components/.app-shell.md b/react-embedding-example/src/components/.app-shell.md
new file mode 100644
index 000000000..07ea4f2a0
--- /dev/null
+++ b/react-embedding-example/src/components/.app-shell.md
@@ -0,0 +1,33 @@
+<!-- source-hash: b2af0fa9a3598f5868ea2db4a8717f24 -->
+Provides the top-level layout shell for the OpenFrame embed demo app, composing a sticky navigation header, announcement bar, route outlet, and floating AI assistant into a single persistent wrapper rendered on every route.
+
+## Key Components
+
+- **`AppShell`** — Root layout component rendered by the router; wraps all child routes via `<Outlet />`
+- **`NAV`** — Static navigation config array defining all top-level routes with their labels and `end` matching flags
+- **`AnnouncementBar`** — Imported from `@flamingo-stack/openframe-frontend-core`; reads its endpoint autonomously from `EndpointsRuntime.announcementsUrl` — no props required
+- **`AskAi`** — Floating AI assistant trigger rendered persistently across all routes
+
+## Routing Notes
+
+The shell deliberately avoids any manual router bridging. React Router is registered once into the library's embed shims via `providers/embed-router-bridge`, allowing all embedded surfaces (chat chips, markdown anchors, entity cards, onboarding cards, release lists) to soft-navigate through the registered router directly — no `runtime.navigation` callback or document-click interceptor needed.
+
+## Usage Example
+
+```typescript
+// Typically registered as the root layout route
+import { createBrowserRouter } from 'react-router-dom'
+import { AppShell } from './app-shell'
+
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <AppShell />,
+    children: [
+      { index: true, element: <Home /> },
+      { path: 'roadmap', element: <Roadmap /> },
+      { path: 'tickets', element: <Tickets /> },
+    ],
+  },
+])
+```
\ No newline at end of file
diff --git a/react-embedding-example/src/components/.ask-ai.md b/react-embedding-example/src/components/.ask-ai.md
new file mode 100644
index 000000000..5883f4cfe
--- /dev/null
+++ b/react-embedding-example/src/components/.ask-ai.md
@@ -0,0 +1,35 @@
+<!-- source-hash: ccfcee9e3f2287e780ee7cf4302fc079 -->
+Thin wrapper component that renders an embedded AI chat interface for the embedder side, delegating all configuration, identity resolution, and routing logic to the shared `EmbeddableChat` library component.
+
+## Key Components
+
+**`AskAi`** *(exported function component)*
+Renders `EmbeddableChat` with `guide` mode active and an empty guide config, which signals the SSE adapter to fall back to the lib's built-in `defaultTableIdForDocumentType` lookup — no hand-written source map required.
+
+## Design Notes
+
+| Concern | Resolution |
+|---|---|
+| Identity | Resolved server-side via proxy `act-as` headers |
+| Source wiring | Resolved server-side; no static per-embed override |
+| Chat-history namespace | Falls back to lib defaults |
+| Doc-card routing | Config-driven via `content-runtime.ts` `docPlatformTargets` |
+| Mixed-source routing | Each doc type routes to its own platform (knowledge hub vs. company hub) |
+| Entity content | Routes through `composeContentUrl` |
+
+## Usage Example
+
+```typescript
+// Drop into any embedder page — no props required
+import { AskAi } from './ask-ai'
+
+export default function SupportPage() {
+  return (
+    <main>
+      <AskAi />
+    </main>
+  )
+}
+```
+
+> This is the embedder-side equivalent of the hub's `global-ask-ai-client.tsx`. Both wrap the same `EmbeddableChat` component — the embedder version carries no auth gate, as identity is handled transparently by the proxy layer.
\ No newline at end of file
diff --git a/react-embedding-example/src/components/.page-state.md b/react-embedding-example/src/components/.page-state.md
new file mode 100644
index 000000000..2bc425299
--- /dev/null
+++ b/react-embedding-example/src/components/.page-state.md
@@ -0,0 +1,28 @@
+<!-- source-hash: 71754bad2d7ee17c5daf3a7876f2bde2 -->
+Shared UI component for displaying route-level error states using ODS design tokens (no hardcoded colors).
+
+## Key Components
+
+- **`PageError`** — A presentational component that renders a styled error heading and optional detail message using ODS semantic color tokens (`ods-text-primary`, `ods-text-secondary`).
+
+## Usage Example
+
+```typescript
+import { PageError } from './page-state'
+
+// Minimal usage
+<PageError title="Not Found" />
+
+// With detail message
+<PageError
+  title="Failed to load data"
+  detail="The requested resource could not be retrieved. Please try again."
+/>
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `title` | `string` | ✅ | Primary error heading |
+| `detail` | `string` | ❌ | Optional secondary descriptive message |
\ No newline at end of file
diff --git a/react-embedding-example/src/config/.content.md b/react-embedding-example/src/config/.content.md
new file mode 100644
index 000000000..4b0e4b7e2
--- /dev/null
+++ b/react-embedding-example/src/config/.content.md
@@ -0,0 +1,18 @@
+<!-- source-hash: 1ce5c4fdc816f308b830d1bc63fac2e9 -->
+Centralized base URL constant for all content hub API endpoint calls, derived from the shared proxy prefix to ensure namespace consistency.
+
+## Key Components
+
+- **`CONTENT`** — Exported string constant combining `CONTENT_PREFIX` with `/api`, used as the base path for every hub endpoint request.
+- **`CONTENT_PREFIX`** — Imported from `proxy/content-prefix.mjs`, the single source of truth for the proxy namespace prefix.
+
+## Usage Example
+
+```typescript
+import { CONTENT } from './content'
+
+const response = await fetch(`${CONTENT}/articles`)
+const data = await response.json()
+```
+
+> Changing the proxy namespace requires only a single edit in `proxy/content-prefix.mjs` — all hub calls update automatically.
\ No newline at end of file
diff --git a/react-embedding-example/src/config/.endpoints.md b/react-embedding-example/src/config/.endpoints.md
new file mode 100644
index 000000000..7b0fcc4e2
--- /dev/null
+++ b/react-embedding-example/src/config/.endpoints.md
@@ -0,0 +1,38 @@
+<!-- source-hash: c14e6a98c1b3123a2ddf68cdea6f652c -->
+Centralized API endpoint registry for the Flamingo content hub. All route strings are derived once from the `CONTENT` base URL — no path is duplicated across the runtime factory, data layer, or pages.
+
+## Key Components
+
+**`EP` (const object)**
+The single source of truth for all hub API paths, organized by domain:
+
+| Group | Endpoints |
+|-------|-----------|
+| Chat | `chatStream`, `commands`, `docsSearch`, `agentBase`, `approval`, `attachmentUpload`, `attachmentViewPrefix`, `identity`, `imageProxy` |
+| Roadmap | `roadmap`, `roadmapVote`, `roadmapById(id)` |
+| Delivery | `delivery`, `deliveryCompleted`, `deliveryInProgress` |
+| Onboarding | `onboarding`, `onboardingBySlug(slug)`, `onboardingSections` |
+| Releases | `productReleases`, `productReleaseBySlug(slug)` |
+| Misc | `legal(docType)`, `contact`, `announcements`, `accessValidate`, `accessConsume`, `ogPlaceholder(title)` |
+
+Static paths are plain strings; dynamic paths are typed factory functions returning a string.
+
+**`HUB_PUBLIC_ORIGIN`**
+The public hub origin URL, read from `VITE_HUB_ORIGIN` at build time, falling back to `http://localhost:3000`. Used for embed-mode "open in full" links.
+
+## Usage Example
+
+```typescript
+import { EP, HUB_PUBLIC_ORIGIN } from './endpoints'
+
+// Static endpoint
+const res = await fetch(EP.chatStream, { method: 'POST', body: payload })
+
+// Dynamic endpoint — slug/id factories
+const release = await fetch(EP.productReleaseBySlug('v2.1.0'))
+const guide   = await fetch(EP.onboardingBySlug('getting-started'))
+const legal   = await fetch(EP.legal('privacy-policy'))
+
+// Embed-mode origin
+const fullUrl = `${HUB_PUBLIC_ORIGIN}/releases/v2.1.0`
+```
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.contact.md b/react-embedding-example/src/pages/.contact.md
new file mode 100644
index 000000000..712fa5654
--- /dev/null
+++ b/react-embedding-example/src/pages/.contact.md
@@ -0,0 +1,28 @@
+<!-- source-hash: 44d299d16911be32c43addaa05b2c9ba -->
+Renders the public **Contact Us** page by mounting the self-contained `ContactForm` component from the OpenFrame frontend core library.
+
+## Key Components
+
+- **`ContactPage`** — Page-level wrapper that provides layout padding and renders `ContactForm` with pre-configured title and subtitle props.
+- **`ContactForm`** *(from `@flamingo-stack/openframe-frontend-core`)* — Fully self-contained form component; internally calls `useContactSubmission`, which resolves the submission endpoint via the mounted `EndpointsRuntime` provider. No host-side hooks or schema imports are required.
+
+## Usage Example
+
+```typescript
+// Route this component from your page router (e.g. Next.js / React Router)
+import { ContactPage } from './contact'
+
+// In your router config:
+{ path: '/contact', element: <ContactPage /> }
+```
+
+To customise the heading copy, edit the `title` and `subtitle` props directly:
+
+```typescript
+<ContactForm
+  title="Get in touch"
+  subtitle="Questions about OpenFrame? Send us a note."
+/>
+```
+
+> **Note:** `ContactPage` relies on an `EndpointsRuntime` provider being present higher in the React tree. Ensure it is mounted at the application root so `useContactSubmission` can resolve `EP.contact` correctly.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.delivery.md b/react-embedding-example/src/pages/.delivery.md
new file mode 100644
index 000000000..29c0f2c7c
--- /dev/null
+++ b/react-embedding-example/src/pages/.delivery.md
@@ -0,0 +1,29 @@
+<!-- source-hash: 6e34aa8824892d31fdfc6c10e3b00031 -->
+Thin page-level component that wires the Delivery section's API endpoints into the shared `DevSectionPage` + `DeliveryLists` shell from `openframe-frontend-core`.
+
+## Key Components
+
+- **`DeliveryPage`** — Stateless page component; its sole responsibility is supplying the two API route constants (`EP.deliveryCompleted`, `EP.deliveryInProgress`) to `DeliveryLists`. All UI chrome (hero, search, task-type filter, URL-param wiring) and table rendering are delegated to the core library.
+
+## Usage Example
+
+```typescript
+// Route registration (e.g. React Router / Next.js)
+import { DeliveryPage } from './pages/delivery'
+
+<Route path="/delivery" element={<DeliveryPage />} />
+```
+
+```typescript
+// Endpoint config (config/endpoints.ts)
+export const EP = {
+  deliveryCompleted:   '/api/delivery/completed',
+  deliveryInProgress:  '/api/delivery/in-progress',
+}
+```
+
+## Notes
+
+- No local state or hooks — fully controlled by URL search params via `DevSectionPage`.
+- To change displayed data, update `EP.deliveryCompleted` / `EP.deliveryInProgress` in the endpoints config; no changes to this file are needed.
+- Filter and search behaviour lives in `DeliveryLists` (core library); extend it there, not here.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.home.md b/react-embedding-example/src/pages/.home.md
new file mode 100644
index 000000000..950c6d6ce
--- /dev/null
+++ b/react-embedding-example/src/pages/.home.md
@@ -0,0 +1,33 @@
+<!-- source-hash: 5ba7b9019f3ded472c8d96de4c56c125 -->
+Navigation hub component for the OpenFrame embedding demo app, rendering a grid of links to all available surfaces/routes with their descriptions.
+
+## Key Components
+
+- **`SURFACES`** — Static array of route descriptors (`to`, `title`, `desc`) covering all demo surfaces
+- **`HomePage`** — Default export component rendering the landing page grid
+
+## Usage Example
+
+```typescript
+import { HomePage } from './home'
+
+// Used as the index route in your router config
+const router = createBrowserRouter([
+  { path: '/', element: <HomePage /> },
+  // ... other surface routes
+])
+```
+
+## Surface Routes
+
+| Route | Surface |
+|-------|---------|
+| `/onboarding-guides` | Onboarding guides catalog |
+| `/roadmap` | Voting grid |
+| `/delivery` | Bug-fix & enhancement tables |
+| `/releases` | Product releases list + detail |
+| `/legal/privacy` | Privacy / Terms pages |
+| `/contact` | Contact form |
+| `/tickets` | Help center / tickets |
+
+> Each card links to a real `@flamingo-stack/openframe-frontend-core` component proxied through `/content`, which injects the chat secret and a fixed identity for the floating **Ask AI** widget.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.legal.md b/react-embedding-example/src/pages/.legal.md
new file mode 100644
index 000000000..37f63fbe5
--- /dev/null
+++ b/react-embedding-example/src/pages/.legal.md
@@ -0,0 +1,26 @@
+<!-- source-hash: ff96e0b568c7b2ffa5f2bb78f7e561f1 -->
+Renders the legal document page for OpenFrame, supporting both Privacy Policy and Terms of Service routes via a single parameterized component.
+
+## Key Components
+
+- **`COPY`** — Static record mapping `docType` slugs (`"privacy"` | `"terms"`) to per-document UI strings (title, contact email, error/empty state messages)
+- **`LegalPage`** — Route-level component that reads the `docType` URL param, resolves the matching copy, and delegates rendering to `LegalDocumentPage` from `openframe-frontend-core`
+
+## Usage Example
+
+```typescript
+// Route setup (e.g. react-router-dom)
+<Route path="/legal/:docType" element={<LegalPage />} />
+
+// Navigating to a specific doc
+// /legal/privacy  → renders Privacy Policy
+// /legal/terms    → renders Terms of Service
+// /legal/unknown  → falls back to Privacy Policy copy
+```
+
+## Notes
+
+- Falls back to `COPY.privacy` for any unrecognised `docType` param
+- The API endpoint is resolved via `EP.legal(docType)` from the shared endpoint config
+- `backButton` is disabled (`false`) — this is a standalone destination page, not a modal or nested view
+- Replaces the hub's previous separate `/privacy` and `/terms` pages with a single parameterized surface
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.onboarding-catalog.md b/react-embedding-example/src/pages/.onboarding-catalog.md
new file mode 100644
index 000000000..15afa2189
--- /dev/null
+++ b/react-embedding-example/src/pages/.onboarding-catalog.md
@@ -0,0 +1,41 @@
+<!-- source-hash: 89ec5104a923b981298992d0d9b619ff -->
+Thin page component that wires the onboarding guides catalog into the app shell by supplying API endpoint configuration — all rendering logic (RAG search, section pills, guide grid) is delegated to the library component.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `OnboardingCatalogPage` | React component | Page entry point that composes `DevSectionPage` and `OnboardingGuidesCatalogView` |
+
+**Dependencies:**
+- `DevSectionPage` — provides page chrome (hero + back button) via `sectionKey="onboarding"`
+- `OnboardingGuidesCatalogView` — library component handling RAG search, section pills, guide grid, and internal data fetching
+- `EP` — centralized endpoint config supplying `onboarding` and `onboardingSections` routes
+
+## Usage Example
+
+```typescript
+// Route registration (e.g., React Router / Next.js equivalent)
+import { OnboardingCatalogPage } from './pages/onboarding-catalog'
+
+// In your router config:
+{ path: '/onboarding-guides', element: <OnboardingCatalogPage /> }
+```
+
+```typescript
+// The component itself requires no props — endpoints and base path are
+// resolved from the centralized EP config
+export function OnboardingCatalogPage() {
+  return (
+    <DevSectionPage sectionKey="onboarding">
+      <OnboardingGuidesCatalogView
+        guidesEndpoint={EP.onboarding}
+        sectionsEndpoint={EP.onboardingSections}
+        basePath="/onboarding-guides"
+      />
+    </DevSectionPage>
+  )
+}
+```
+
+> **Note:** URL-based filtering is handled internally by `OnboardingGuidesCatalogView` via the `?section=` query param — no additional state management is needed at the page level.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.onboarding-detail.md b/react-embedding-example/src/pages/.onboarding-detail.md
new file mode 100644
index 000000000..e8ffcce17
--- /dev/null
+++ b/react-embedding-example/src/pages/.onboarding-detail.md
@@ -0,0 +1,42 @@
+<!-- source-hash: 2c80a63c65bcb123c9edf883c1efaee7 -->
+Thin page component that renders an onboarding guide detail view by extracting the `slug` route parameter and wiring it to the shared `OnboardingGuideDetailView` from the core library.
+
+## Key Components
+
+- **`OnboardingDetailPage`** — Route-level page component; reads `slug` from URL params and delegates all data fetching and rendering to `OnboardingGuideDetailView`
+- **`OnboardingGuideDetailView`** — Core library component (from `@flamingo-stack/openframe-frontend-core`) that handles guide fetching and display internally
+- **`EP.onboardingBySlug`** — API endpoint constant injected as `guideEndpoint` prop
+
+## Props Passed to `OnboardingGuideDetailView`
+
+| Prop | Value | Description |
+|------|-------|-------------|
+| `slug` | `useParams().slug` | Guide identifier extracted from the URL |
+| `guideEndpoint` | `EP.onboardingBySlug` | API route used to fetch the guide |
+| `basePath` | `"/onboarding-guides"` | Base navigation path for back-links |
+
+## Usage Example
+
+```typescript
+// Registered in your router (e.g. react-router-dom)
+{
+  path: '/onboarding-guides/:slug',
+  element: <OnboardingDetailPage />,
+}
+```
+
+```typescript
+// The component itself — no additional configuration needed
+export function OnboardingDetailPage() {
+  const { slug = '' } = useParams()
+  return (
+    <OnboardingGuideDetailView
+      slug={slug}
+      guideEndpoint={EP.onboardingBySlug}
+      basePath="/onboarding-guides"
+    />
+  )
+}
+```
+
+> This page intentionally contains no business logic. All data fetching, loading states, and error handling are owned by `OnboardingGuideDetailView`, keeping this component a pure routing adapter.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.release-detail.md b/react-embedding-example/src/pages/.release-detail.md
new file mode 100644
index 000000000..d9ef1cc19
--- /dev/null
+++ b/react-embedding-example/src/pages/.release-detail.md
@@ -0,0 +1,35 @@
+<!-- source-hash: 97b3f2077871da258b4522c06f76fb0c -->
+Route component that renders a full product release detail page by composing injected section components (`RoadmapSection`, `VideoDisplaySection`, `DeliverySection`) with the core library's `ReleaseDetailPage`.
+
+## Key Components
+
+- **`ReleaseDetailRoute`** — Main exported route component; reads `slug` from URL params and wires all dependencies into `ReleaseDetailPage`
+- **`useRelease`** — Host-supplied data hook that fetches a single release by slug via `EP.productReleaseBySlug`, integrated with the app's `QueryClient`
+- **`RoadmapSection`** — Wraps `RoadmapGrid` with hub-scoped endpoints for voting and refresh
+- **`VideoDisplaySection`** — Injects `EntityVideoSection` to render a single tabbed player (Full Video / Highlights) instead of the lib's default multiple-player fallback
+- **`DeliverySection`** — Renders `DeliveryTable` for completed and in-progress delivery items from the `DeliveryResponse`; gates on data presence
+
+## Usage Example
+
+```typescript
+// Registered as a React Router route:
+import { ReleaseDetailRoute } from './routes/release-detail'
+
+<Route path="/releases/:slug" element={<ReleaseDetailRoute />} />
+```
+
+```typescript
+// ReleaseDetailRoute resolves to:
+<ReleaseDetailPage
+  slug={slug}
+  useRelease={useRelease}
+  RoadmapSection={RoadmapSection}
+  DeliverySection={DeliverySection}
+  VideoDisplaySection={VideoDisplaySection}
+  roadmapApiEndpoint={EP.roadmap}
+  deliveryApiEndpoint={EP.delivery}
+  backButton={{ label: 'Back to releases', href: '/releases' }}
+/>
+```
+
+> All section components are structural wrappers — they accept props typed by the core lib (`VideoDisplaySectionProps`, `DeliveryResponse`, `RoadmapItem`) and forward them verbatim, keeping the host app decoupled from lib internals.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.releases.md b/react-embedding-example/src/pages/.releases.md
new file mode 100644
index 000000000..0ab5414df
--- /dev/null
+++ b/react-embedding-example/src/pages/.releases.md
@@ -0,0 +1,29 @@
+<!-- source-hash: f9ad64208694f322fee733028f755aa9 -->
+Thin page component that composes the Releases list view by wiring the configured API endpoint into the shared `ProductReleasesView` and wrapping it with `DevSectionPage` chrome (hero, search, and release-status filter — all URL-param-driven).
+
+## Key Components
+
+- **`ReleasesPage`** — Default page export; config-only, supplies no layout or state logic of its own
+- **`DevSectionPage`** (`sectionKey="releases"`) — Provides hero, search, and release-status filter UI; pulls the page title from the section registry
+- **`ProductReleasesView`** — Reads URL params, fetches, paginates, and renders the release list
+- **`EP.productReleases`** — The sole configuration this page contributes; maps to the API route for product releases
+
+## Usage Example
+
+```typescript
+// Route registration (e.g. React Router / Next.js)
+import { ReleasesPage } from './releases'
+
+// In your router config:
+{ path: '/releases', element: <ReleasesPage /> }
+```
+
+```typescript
+// EP.productReleases (config/endpoints.ts) — the only value this page depends on
+export const EP = {
+  productReleases: '/api/products/releases',
+  // ...
+}
+```
+
+> **Design note:** All filter state (search query, release status) lives in URL params managed by `DevSectionPage`. To change the data source, update `EP.productReleases` — no changes to this file are needed.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.roadmap.md b/react-embedding-example/src/pages/.roadmap.md
new file mode 100644
index 000000000..6a068632b
--- /dev/null
+++ b/react-embedding-example/src/pages/.roadmap.md
@@ -0,0 +1,30 @@
+<!-- source-hash: 27022d73ea2917ee82b4b061684f9f6d -->
+Thin page-level wrapper that wires the Roadmap feature to its API endpoints with zero UI logic of its own.
+
+## Key Components
+
+- **`RoadmapPage`** — Exported page component; composes `DevSectionPage` and `RoadmapView` with endpoint config
+- **`DevSectionPage`** (`sectionKey="roadmap"`) — Provides chrome: hero, search input, and status filter pills, all URL-param-driven
+- **`RoadmapView`** — Handles data fetching, filtered grid rendering, and voting interactions by consuming URL params
+- **`EP`** — Centralized endpoint constants (`EP.roadmap`, `EP.roadmapById`, `EP.roadmapVote`)
+
+## Usage Example
+
+```typescript
+// Route registration (e.g., React Router / Next.js)
+import { RoadmapPage } from './pages/roadmap'
+
+// Simply mount the page — all filtering, fetching, and voting
+// behavior is driven by URL params and endpoint config
+<Route path="/roadmap" element={<RoadmapPage />} />
+```
+
+## Endpoint Wiring
+
+| Prop | Endpoint | Purpose |
+|------|----------|---------|
+| `endpoint` | `EP.roadmap` | Fetch filtered roadmap item list |
+| `buildRefreshUrl` | `EP.roadmapById` | Refresh a single item after interaction |
+| `votingOptions.voteApiEndpoint` | `EP.roadmapVote` | Submit upvotes/downvotes |
+
+> All UI state (search query, status filters, pagination) lives in URL params managed by `DevSectionPage`, keeping this file intentionally config-only — add new behavior by extending `EP` or `RoadmapView` props, not here.
\ No newline at end of file
diff --git a/react-embedding-example/src/pages/.tickets.md b/react-embedding-example/src/pages/.tickets.md
new file mode 100644
index 000000000..9977e9fa3
--- /dev/null
+++ b/react-embedding-example/src/pages/.tickets.md
@@ -0,0 +1,31 @@
+<!-- source-hash: 61d1596bf9d3f4c3381627b063558488 -->
+Thin page-level wrapper that renders the `HelpCenterList` component from the OpenFrame frontend core library as the Tickets/Help Center route.
+
+## Key Components
+
+- **`TicketsPage`** — Stateless React page component; delegates all rendering and logic to `HelpCenterList`
+- **`HelpCenterList`** *(from `@flamingo-stack/openframe-frontend-core`)* — Composes the full Help Center UI including:
+  - Dev section page chrome
+  - Ticket creation form
+  - Ticket list
+  - Customer identification via `ChatRuntime` (proxy-injected)
+
+## Usage Example
+
+```typescript
+// Typically registered as a route in your router config
+import { TicketsPage } from './tickets'
+
+const routes = [
+  {
+    path: '/tickets',
+    element: <TicketsPage />,
+  },
+]
+```
+
+## Notes
+
+- API calls within `HelpCenterList` target `/api/chat/agent/*` and rely on the dev-only proxy fallback configured in `vite.config.ts`
+- Once the optional `agentBaseUrl` seam is available in the core lib, the proxy dependency can be removed
+- No props or local state — all behaviour is encapsulated inside the core library component
\ No newline at end of file
diff --git a/react-embedding-example/src/providers/.app-providers.md b/react-embedding-example/src/providers/.app-providers.md
new file mode 100644
index 000000000..f6402c83c
--- /dev/null
+++ b/react-embedding-example/src/providers/.app-providers.md
@@ -0,0 +1,42 @@
+<!-- source-hash: bce3767f28d61a959ac8f45710a801ae -->
+Wraps the entire embed application in the required runtime and data-fetching providers, establishing a single shared context tree for chat identity, API endpoints, and server-state caching.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `AppProviders` | React component | Root provider tree; accepts `children: ReactNode` |
+| `queryClient` | `QueryClient` | Module-level singleton; shared across all hooks using `@tanstack/react-query` |
+
+**Provider nesting order (outermost → innermost):**
+
+```text
+QueryClientProvider         ← react-query cache (tickets, onboarding, chat hooks)
+  └─ ChatRuntimeContext     ← memoized chat runtime (buildChatRuntime)
+       └─ ChatIdentityProvider  ← single /identity fetch for the whole embed
+            └─ EndpointsRuntimeContext  ← memoized endpoints runtime
+                 └─ {children}
+```
+
+> `ChatIdentityProvider` must sit **inside** `ChatRuntimeContext` (reads `identityUrl` from it) and **above** `EndpointsRuntimeContext` so that the persistent chat shell, `/tickets` page, and contact form all share one identity resolution instead of triggering duplicate fetches.
+
+## Usage Example
+
+```typescript
+// main.tsx / entry point
+import { AppProviders } from './app-providers'
+import { AppShell } from './app-shell'
+
+export function App() {
+  return (
+    <AppProviders>
+      <AppShell />
+    </AppProviders>
+  )
+}
+```
+
+## Notes
+
+- Both runtimes (`chatRuntime`, `endpointsRuntime`) are wrapped in `useMemo` with empty deps — stable references required by the lib's embedder contract to prevent context re-renders.
+- Theme is applied via `data-theme="dark"` on `<html>` (in `index.html`) rather than a provider; ODS design tokens resolve directly from that attribute.
\ No newline at end of file
diff --git a/react-embedding-example/src/providers/.content-runtime.md b/react-embedding-example/src/providers/.content-runtime.md
new file mode 100644
index 000000000..a2210f9e1
--- /dev/null
+++ b/react-embedding-example/src/providers/.content-runtime.md
@@ -0,0 +1,36 @@
+<!-- source-hash: ca6e6fc9b9240a614a6bf4c32abd69ef -->
+Single factory module that constructs both `ChatRuntime` and `EndpointsRuntime` configuration objects for the OpenFrame embedder, wiring all API endpoints, navigation behavior, and content URL resolution from a single source.
+
+## Key Components
+
+**`HOSTED_TYPES`**
+A `Set` of content types (`onboarding_guide`, `product_release`) whose detail routes are owned by this embedder (e.g. `/onboarding-guides/:slug`). Used by `makeComposeContentUrl` to emit relative in-app hrefs for soft navigation vs. canonical hub URLs for everything else.
+
+**`buildChatRuntime()`**
+Returns an `Omit<ChatRuntime, 'source'>` object containing:
+- `endpoints` — all proxied API URLs via `EP.*` and `CONTENT_PREFIX` (chat stream, approval, commands, uploads, identity, image proxy)
+- `navigation.mode: 'host'` — delegates routing to the embedded react-router instance via the lib's embed-router-bridge
+- `composeContentUrl` — resolves content item URLs using `makeComposeContentUrl`, with explicit overrides for `roadmap_item` and `delivery_item` that deep-link into filtered list views (`?search=<id>`) rather than non-existent detail pages
+- `docPlatformTargets` — routes `markdown` docs to Flamingo's knowledge hub and `data_room_doc` to the company hub
+
+**`buildEndpointsRuntime()`**
+Returns an `EndpointsRuntime` with announcement, access code validation/consumption, and contact endpoints.
+
+## Usage Example
+
+```typescript
+// app-providers.tsx (memoized at app root)
+import { buildChatRuntime, buildEndpointsRuntime } from './content-runtime'
+
+const chatRuntime = useMemo(() => buildChatRuntime(), [])
+const endpointsRuntime = useMemo(() => buildEndpointsRuntime(), [])
+
+// Pass into lib context providers
+<ChatRuntimeProvider value={chatRuntime}>
+  <EndpointsRuntimeProvider value={endpointsRuntime}>
+    {children}
+  </EndpointsRuntimeProvider>
+</ChatRuntimeProvider>
+```
+
+> **Note:** `source` is intentionally omitted from `ChatRuntime` — it is resolved server-side from the proxied hub's `currentPlatform()`, making this factory platform-agnostic.
\ No newline at end of file
diff --git a/react-embedding-example/src/providers/.embed-router-bridge.md b/react-embedding-example/src/providers/.embed-router-bridge.md
new file mode 100644
index 000000000..e2e0b331c
--- /dev/null
+++ b/react-embedding-example/src/providers/.embed-router-bridge.md
@@ -0,0 +1,29 @@
+<!-- source-hash: d0c59e83925a907d34406e58547daca7 -->
+Adapts React Router's navigation hooks and `<Link>` component into the shape expected by `@flamingo-stack/openframe-frontend-core`'s embed-shims, enabling all lib surfaces to navigate and re-render correctly within this SPA.
+
+## Key Components
+
+- **`LinkAdapter`** — A `forwardRef` wrapper that maps the Next.js `<Link>` prop shape (`href`, `prefetch`, `replace`, `scroll`) to React Router's `<Link to=...>`, dropping Next-only props.
+- **`registerEmbedRouterBridge()`** — One-time registration function (guarded by a `registered` flag) that calls `registerNavigation` and `registerLink` from the embed-shims with adapted React Router hooks.
+- **`registerNavigation` adapters** — Bridges the hook shape mismatch:
+  - `useRouter()` → wraps `useNavigate()` into a `RouterStub` (`push`, `replace`, `back`, `forward`, `refresh`, `prefetch`), memoized to prevent unnecessary re-renders.
+  - `usePathname()` → returns `useLocation().pathname` as a bare string.
+  - `useSearchParams()` → unwraps React Router's `[params, setter]` tuple to return only the bare `URLSearchParams`.
+
+## Usage Example
+
+Call **once** before any lib surface renders, typically in `main.tsx`:
+
+```typescript
+import { registerEmbedRouterBridge } from './embed-router-bridge'
+
+registerEmbedRouterBridge()
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <BrowserRouter>
+    <App />
+  </BrowserRouter>
+)
+```
+
+> **Note:** `registerEmbedRouterBridge()` is idempotent — subsequent calls after the first are a no-op. Never register the raw React Router hooks directly into the shims; the hook return shapes are incompatible with the `NavigationImpl` contract.
\ No newline at end of file
diff --git a/react-embedding-example/src/stubs/.next-font-google.md b/react-embedding-example/src/stubs/.next-font-google.md
new file mode 100644
index 000000000..d03fdccb1
--- /dev/null
+++ b/react-embedding-example/src/stubs/.next-font-google.md
@@ -0,0 +1,36 @@
+<!-- source-hash: 237d9e5a8d4d84f0e74e33d317a97195 -->
+Vite alias stub that replaces `next/font/google` with harmless no-ops, preventing build crashes when a bundler encounters Next.js compiler macros like `Azeret_Mono()` or `DM_Sans()` that cannot be evaluated outside the Next.js compiler.
+
+## Key Components
+
+- **`FontResult`** — Type describing the shape returned by Next.js font functions (`className`, `variable`, `style.fontFamily`)
+- **`noop`** — Factory returning an empty `FontResult`; used as a safe stand-in for any font constructor call
+- **`Azeret_Mono`** / **`DM_Sans`** — Named exports matching the real `next/font/google` API, each resolving to `noop`
+- **`default` (Proxy)** — Catch-all default export that returns `noop` for any property access, covering any other Google font name not explicitly stubbed
+
+## Usage Example
+
+This module is **not imported directly** — it is wired in via a Vite alias in `vite.config.ts`:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  resolve: {
+    alias: {
+      'next/font/google': path.resolve(__dirname, './stubs/next-font-google.ts'),
+    },
+  },
+})
+```
+
+Any transitive import of `next/font/google` then resolves to the stub:
+
+```typescript
+// Resolved transparently to the stub — no build error
+import { DM_Sans } from 'next/font/google'
+
+const font = DM_Sans({ subsets: ['latin'] })
+// → { className: '', variable: '', style: { fontFamily: '' } }
+```
+
+> **Note:** Fonts in this project are delivered via the `./styles` CSS import, so this stub acts purely as a defensive guard — it is not expected to be exercised at runtime in normal operation.
\ No newline at end of file

From 4d00e9d5bb31f7c238506587d5d3103eb00256e4 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 19:17:38 +0000
Subject: [PATCH 4/7] chore(docs): Remove 2 orphaned inline files [skip ci]

---
 .doc-pipeline-status.md                       |  5 ---
 .../data/service/.TenantIdProvider.md         | 37 -------------------
 2 files changed, 42 deletions(-)
 delete mode 100644 .doc-pipeline-status.md
 delete mode 100644 openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.TenantIdProvider.md

diff --git a/.doc-pipeline-status.md b/.doc-pipeline-status.md
deleted file mode 100644
index 53e79aa7d..000000000
--- a/.doc-pipeline-status.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Documentation Pipeline Started
-
-Run ID: doc-orchestrator-2026-06-04T17-54-24.845Z
-Status: In Progress
-Started: 2026-06-04 17:54:44 UTC
diff --git a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.TenantIdProvider.md b/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.TenantIdProvider.md
deleted file mode 100644
index 11ee702a9..000000000
--- a/openframe-data-mongo-sync/src/main/java/com/openframe/data/service/.TenantIdProvider.md
+++ /dev/null
@@ -1,37 +0,0 @@
-<!-- source-hash: ab7e2d0ecd5857da3801fcc7871dcb7c -->
-Resolves and caches the active tenant ID for use in Pinot shared tables, falling back to a cluster-level environment variable when no tenant is registered in MongoDB.
-
-## Key Components
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `getTenantId()` | `public String` | Returns the active tenant ID — from MongoDB cache or `TENANT_ID` env var fallback |
-| `isTenantRegistered()` | `public boolean` | Checks whether a tenant exists in MongoDB; used to gate deferred operations (e.g. Debezium connector setup) |
-| `getCachedTenant()` | `private Tenant` | Lazy-loads and permanently caches the first tenant found in MongoDB for pod lifetime |
-| `fallbackTenantId` | `@Value` field | Defaults to `"oss"` if `TENANT_ID` env var is not set |
-| `cachedTenant` | in-memory field | Pod-lifetime cache; safe because one tenant per cluster never changes while pod is alive |
-
-## Usage Example
-
-```java
-@Service
-@RequiredArgsConstructor
-public class DebeziumConnectorService {
-
-    private final TenantIdProvider tenantIdProvider;
-
-    public void setupConnector() {
-        // Gate connector creation until a tenant is registered
-        if (!tenantIdProvider.isTenantRegistered()) {
-            log.warn("Skipping Debezium setup — tenant not yet registered");
-            return;
-        }
-
-        String tenantId = tenantIdProvider.getTenantId();
-        // Use tenantId to scope Pinot shared table operations
-        createConnectorForTenant(tenantId);
-    }
-}
-```
-
-> **Caching behaviour:** The first successful MongoDB lookup is cached for the pod's lifetime. Pre-registration calls continue hitting MongoDB until a tenant appears, then cache forever. Cluster recycling destroys the pod, so stale cache is not a concern.
\ No newline at end of file

From 3aa6d9ddd56c7da7986a9043e96504f0534b357a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 19:24:07 +0000
Subject: [PATCH 5/7] docs: Stage 2 - Architecture analysis (9 files) [skip ci]

---
 docs/diagrams/architecture/.gitignore         |   8 +
 docs/diagrams/architecture/README-10.mmd      |  15 +
 docs/diagrams/architecture/README-11.mmd      |  17 +
 docs/diagrams/architecture/README-2.mmd       |   4 +
 docs/diagrams/architecture/README-3.mmd       |   8 +
 docs/diagrams/architecture/README-4.mmd       |   5 +
 docs/diagrams/architecture/README-5.mmd       |   8 +
 docs/diagrams/architecture/README-6.mmd       |   6 +
 docs/diagrams/architecture/README-7.mmd       |   5 +
 docs/diagrams/architecture/README-8.mmd       |  10 +
 docs/diagrams/architecture/README-9.mmd       |   6 +
 docs/diagrams/architecture/README.mmd         |  21 +
 .../architecture/api-lib-contracts-2.mmd      |   6 +
 .../architecture/api-lib-contracts-3.mmd      |   9 +
 .../architecture/api-lib-contracts-4.mmd      |   5 +
 .../architecture/api-lib-contracts-5.mmd      |  13 +
 .../architecture/api-lib-contracts.mmd        |   8 +
 .../api-service-core-http-and-graphql-2.mmd   |  12 +
 .../api-service-core-http-and-graphql-3.mmd   |   7 +
 .../api-service-core-http-and-graphql-4.mmd   |   8 +
 .../api-service-core-http-and-graphql-5.mmd   |   8 +
 .../api-service-core-http-and-graphql-6.mmd   |   6 +
 .../api-service-core-http-and-graphql-7.mmd   |   5 +
 .../api-service-core-http-and-graphql.mmd     |  14 +
 .../authorization-service-core-10.mmd         |   8 +
 .../authorization-service-core-11.mmd         |   5 +
 .../authorization-service-core-12.mmd         |  14 +
 .../authorization-service-core-2.mmd          |   5 +
 .../authorization-service-core-3.mmd          |   7 +
 .../authorization-service-core-4.mmd          |   7 +
 .../authorization-service-core-5.mmd          |   4 +
 .../authorization-service-core-6.mmd          |   8 +
 .../authorization-service-core-7.mmd          |   5 +
 .../authorization-service-core-8.mmd          |   8 +
 .../authorization-service-core-9.mmd          |   7 +
 .../authorization-service-core.mmd            |   7 +
 .../data-models-and-repositories-mongo-2.mmd  |   5 +
 .../data-models-and-repositories-mongo-3.mmd  |   5 +
 .../data-models-and-repositories-mongo-4.mmd  |   6 +
 .../data-models-and-repositories-mongo-5.mmd  |   4 +
 .../data-models-and-repositories-mongo.mmd    |   9 +
 .../frontend-core-ui-and-chat-10.mmd          |   9 +
 .../frontend-core-ui-and-chat-2.mmd           |  11 +
 .../frontend-core-ui-and-chat-3.mmd           |   5 +
 .../frontend-core-ui-and-chat-4.mmd           |   6 +
 .../frontend-core-ui-and-chat-5.mmd           |   4 +
 .../frontend-core-ui-and-chat-6.mmd           |   6 +
 .../frontend-core-ui-and-chat-7.mmd           |   5 +
 .../frontend-core-ui-and-chat-8.mmd           |   5 +
 .../frontend-core-ui-and-chat-9.mmd           |   5 +
 .../frontend-core-ui-and-chat.mmd             |  24 +
 .../architecture/gateway-service-core-2.mmd   |  12 +
 .../architecture/gateway-service-core-3.mmd   |   6 +
 .../architecture/gateway-service-core-4.mmd   |   8 +
 .../architecture/gateway-service-core-5.mmd   |   6 +
 .../architecture/gateway-service-core-6.mmd   |   5 +
 .../architecture/gateway-service-core.mmd     |  11 +
 .../management-service-core-2.mmd             |   3 +
 .../management-service-core-3.mmd             |   5 +
 .../management-service-core-4.mmd             |   5 +
 .../management-service-core-5.mmd             |   6 +
 .../management-service-core-6.mmd             |   6 +
 .../management-service-core-7.mmd             |   4 +
 .../management-service-core-8.mmd             |   5 +
 .../architecture/management-service-core.mmd  |  11 +
 .../stream-processing-kafka-2.mmd             |   6 +
 .../stream-processing-kafka-3.mmd             |   3 +
 .../stream-processing-kafka-4.mmd             |   6 +
 .../stream-processing-kafka-5.mmd             |   5 +
 .../stream-processing-kafka-6.mmd             |   4 +
 .../stream-processing-kafka-7.mmd             |   5 +
 .../stream-processing-kafka-8.mmd             |  10 +
 .../architecture/stream-processing-kafka.mmd  |  11 +
 docs/reference/architecture/.gitignore        |   8 +
 docs/reference/architecture/README.md         | 405 ++++++++++++++++
 .../api-lib-contracts/api-lib-contracts.md    | 455 ++++++++++++++++++
 .../api-service-core-http-and-graphql.md      | 358 ++++++++++++++
 .../authorization-service-core.md             | 380 +++++++++++++++
 .../data-models-and-repositories-mongo.md     | 441 +++++++++++++++++
 .../frontend-core-ui-and-chat.md              | 444 +++++++++++++++++
 .../gateway-service-core.md                   | 367 ++++++++++++++
 .../management-service-core.md                | 421 ++++++++++++++++
 .../stream-processing-kafka.md                | 353 ++++++++++++++
 83 files changed, 4183 insertions(+)
 create mode 100644 docs/diagrams/architecture/.gitignore
 create mode 100644 docs/diagrams/architecture/README-10.mmd
 create mode 100644 docs/diagrams/architecture/README-11.mmd
 create mode 100644 docs/diagrams/architecture/README-2.mmd
 create mode 100644 docs/diagrams/architecture/README-3.mmd
 create mode 100644 docs/diagrams/architecture/README-4.mmd
 create mode 100644 docs/diagrams/architecture/README-5.mmd
 create mode 100644 docs/diagrams/architecture/README-6.mmd
 create mode 100644 docs/diagrams/architecture/README-7.mmd
 create mode 100644 docs/diagrams/architecture/README-8.mmd
 create mode 100644 docs/diagrams/architecture/README-9.mmd
 create mode 100644 docs/diagrams/architecture/README.mmd
 create mode 100644 docs/diagrams/architecture/api-lib-contracts-2.mmd
 create mode 100644 docs/diagrams/architecture/api-lib-contracts-3.mmd
 create mode 100644 docs/diagrams/architecture/api-lib-contracts-4.mmd
 create mode 100644 docs/diagrams/architecture/api-lib-contracts-5.mmd
 create mode 100644 docs/diagrams/architecture/api-lib-contracts.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql-2.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql-3.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql-4.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql-5.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql-6.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql-7.mmd
 create mode 100644 docs/diagrams/architecture/api-service-core-http-and-graphql.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-10.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-11.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-12.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-2.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-3.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-4.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-5.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-6.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-7.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-8.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core-9.mmd
 create mode 100644 docs/diagrams/architecture/authorization-service-core.mmd
 create mode 100644 docs/diagrams/architecture/data-models-and-repositories-mongo-2.mmd
 create mode 100644 docs/diagrams/architecture/data-models-and-repositories-mongo-3.mmd
 create mode 100644 docs/diagrams/architecture/data-models-and-repositories-mongo-4.mmd
 create mode 100644 docs/diagrams/architecture/data-models-and-repositories-mongo-5.mmd
 create mode 100644 docs/diagrams/architecture/data-models-and-repositories-mongo.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-10.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-2.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-3.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-4.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-5.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-6.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-7.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-8.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat-9.mmd
 create mode 100644 docs/diagrams/architecture/frontend-core-ui-and-chat.mmd
 create mode 100644 docs/diagrams/architecture/gateway-service-core-2.mmd
 create mode 100644 docs/diagrams/architecture/gateway-service-core-3.mmd
 create mode 100644 docs/diagrams/architecture/gateway-service-core-4.mmd
 create mode 100644 docs/diagrams/architecture/gateway-service-core-5.mmd
 create mode 100644 docs/diagrams/architecture/gateway-service-core-6.mmd
 create mode 100644 docs/diagrams/architecture/gateway-service-core.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-2.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-3.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-4.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-5.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-6.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-7.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core-8.mmd
 create mode 100644 docs/diagrams/architecture/management-service-core.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-2.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-3.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-4.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-5.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-6.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-7.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka-8.mmd
 create mode 100644 docs/diagrams/architecture/stream-processing-kafka.mmd
 create mode 100644 docs/reference/architecture/.gitignore
 create mode 100644 docs/reference/architecture/README.md
 create mode 100644 docs/reference/architecture/api-lib-contracts/api-lib-contracts.md
 create mode 100644 docs/reference/architecture/api-service-core-http-and-graphql/api-service-core-http-and-graphql.md
 create mode 100644 docs/reference/architecture/authorization-service-core/authorization-service-core.md
 create mode 100644 docs/reference/architecture/data-models-and-repositories-mongo/data-models-and-repositories-mongo.md
 create mode 100644 docs/reference/architecture/frontend-core-ui-and-chat/frontend-core-ui-and-chat.md
 create mode 100644 docs/reference/architecture/gateway-service-core/gateway-service-core.md
 create mode 100644 docs/reference/architecture/management-service-core/management-service-core.md
 create mode 100644 docs/reference/architecture/stream-processing-kafka/stream-processing-kafka.md

diff --git a/docs/diagrams/architecture/.gitignore b/docs/diagrams/architecture/.gitignore
new file mode 100644
index 000000000..b4f4c7a6c
--- /dev/null
+++ b/docs/diagrams/architecture/.gitignore
@@ -0,0 +1,8 @@
+# CodeWiki temp files (dependency graphs can be 7GB+)
+temp/
+dependency_graphs/
+
+# JSON intermediate files (except schema/config)
+*.json
+!*-schema.json
+!*-config.json
diff --git a/docs/diagrams/architecture/README-10.mmd b/docs/diagrams/architecture/README-10.mmd
new file mode 100644
index 000000000..936f0059c
--- /dev/null
+++ b/docs/diagrams/architecture/README-10.mmd
@@ -0,0 +1,15 @@
+sequenceDiagram
+    participant User
+    participant Gateway
+    participant Auth
+    participant API
+    participant Stream
+    participant Data
+
+    User->>Gateway: Login Request
+    Gateway->>Auth: OAuth2 Flow
+    Auth-->>Gateway: JWT
+    Gateway->>API: Authenticated Request
+    API->>Data: CRUD Operation
+    API->>Stream: Emit Event
+    Stream->>Data: Persist Unified Event
diff --git a/docs/diagrams/architecture/README-11.mmd b/docs/diagrams/architecture/README-11.mmd
new file mode 100644
index 000000000..1d85c2f60
--- /dev/null
+++ b/docs/diagrams/architecture/README-11.mmd
@@ -0,0 +1,17 @@
+flowchart LR
+    Frontend
+    Gateway
+    Auth
+    API
+    Management
+    Data
+    Stream
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    API --> Data
+    API --> Stream
+    Stream --> Data
+    Management --> Data
+    Management --> Stream
diff --git a/docs/diagrams/architecture/README-2.mmd b/docs/diagrams/architecture/README-2.mmd
new file mode 100644
index 000000000..70c43b485
--- /dev/null
+++ b/docs/diagrams/architecture/README-2.mmd
@@ -0,0 +1,4 @@
+flowchart LR
+    Frontend --> API
+    API --> Contracts["Api Lib Contracts"]
+    Contracts --> Data
diff --git a/docs/diagrams/architecture/README-3.mmd b/docs/diagrams/architecture/README-3.mmd
new file mode 100644
index 000000000..5d31642f1
--- /dev/null
+++ b/docs/diagrams/architecture/README-3.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    Client["Frontend / API Client"] --> Gateway
+    Gateway --> API
+    API --> Controllers
+    API --> GraphQL
+    Controllers --> Services
+    GraphQL --> Services
+    Services --> Data
diff --git a/docs/diagrams/architecture/README-4.mmd b/docs/diagrams/architecture/README-4.mmd
new file mode 100644
index 000000000..c952c366c
--- /dev/null
+++ b/docs/diagrams/architecture/README-4.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    User --> AuthServer["Authorization Service Core"]
+    AuthServer --> JWT["Tenant-Scoped JWT"]
+    JWT --> Gateway
+    Gateway --> API
diff --git a/docs/diagrams/architecture/README-5.mmd b/docs/diagrams/architecture/README-5.mmd
new file mode 100644
index 000000000..058bc5856
--- /dev/null
+++ b/docs/diagrams/architecture/README-5.mmd
@@ -0,0 +1,8 @@
+flowchart LR
+    Browser --> Gateway
+    Agent --> Gateway
+    ExternalAPI --> Gateway
+
+    Gateway --> API
+    Gateway --> Auth
+    Gateway --> Tools
diff --git a/docs/diagrams/architecture/README-6.mmd b/docs/diagrams/architecture/README-6.mmd
new file mode 100644
index 000000000..cb2493c0c
--- /dev/null
+++ b/docs/diagrams/architecture/README-6.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Startup --> Initializers
+    Initializers --> Data
+    Scheduler --> Redis["ShedLock (Redis)"]
+    Scheduler --> Data
+    Scheduler --> Stream
diff --git a/docs/diagrams/architecture/README-7.mmd b/docs/diagrams/architecture/README-7.mmd
new file mode 100644
index 000000000..f008ad9ae
--- /dev/null
+++ b/docs/diagrams/architecture/README-7.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Services --> Repositories
+    Repositories --> CustomImpl["Custom Repository"]
+    CustomImpl --> MongoTemplate
+    MongoTemplate --> MongoDB
diff --git a/docs/diagrams/architecture/README-8.mmd b/docs/diagrams/architecture/README-8.mmd
new file mode 100644
index 000000000..06d0df681
--- /dev/null
+++ b/docs/diagrams/architecture/README-8.mmd
@@ -0,0 +1,10 @@
+flowchart TD
+    Tools --> Debezium
+    Debezium --> KafkaTopic
+    KafkaTopic --> Listener
+    Listener --> Deserializer
+    Deserializer --> Enrichment
+    Enrichment --> Mapper
+    Mapper --> Handler
+    Handler --> Cassandra
+    Handler --> OutboundKafka
diff --git a/docs/diagrams/architecture/README-9.mmd b/docs/diagrams/architecture/README-9.mmd
new file mode 100644
index 000000000..14d825ff4
--- /dev/null
+++ b/docs/diagrams/architecture/README-9.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    EmbeddableChat --> UnifiedChat
+    UnifiedChat --> GuideMode["SSE Mode"]
+    UnifiedChat --> MingoMode["NATS Mode"]
+    GuideMode --> API
+    MingoMode --> Stream
diff --git a/docs/diagrams/architecture/README.mmd b/docs/diagrams/architecture/README.mmd
new file mode 100644
index 000000000..28ee9ef52
--- /dev/null
+++ b/docs/diagrams/architecture/README.mmd
@@ -0,0 +1,21 @@
+flowchart TD
+    Frontend["Frontend Core UI and Chat"]
+    Gateway["Gateway Service Core"]
+    Auth["Authorization Service Core"]
+    API["API Service Core (HTTP + GraphQL)"]
+    Management["Management Service Core"]
+    Data["Data Models and Repositories Mongo"]
+    Stream["Stream Processing Kafka"]
+    Cassandra["Cassandra (Unified Events)"]
+    Tools["Integrated Tools (MeshCentral, Tactical, Fleet)"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    API --> Data
+    API --> Stream
+    Stream --> Cassandra
+    Stream --> Data
+    Management --> Data
+    Management --> Stream
+    Tools --> Stream
diff --git a/docs/diagrams/architecture/api-lib-contracts-2.mmd b/docs/diagrams/architecture/api-lib-contracts-2.mmd
new file mode 100644
index 000000000..a80679195
--- /dev/null
+++ b/docs/diagrams/architecture/api-lib-contracts-2.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Client["Client Filters"] --> Criteria["DeviceFilterCriteria"]
+    Criteria --> Service["Service Layer"]
+    Service --> Repo["Mongo Repository"]
+    Repo --> Results["Filtered Devices"]
+    Results --> Filters["DeviceFilters Response"]
diff --git a/docs/diagrams/architecture/api-lib-contracts-3.mmd b/docs/diagrams/architecture/api-lib-contracts-3.mmd
new file mode 100644
index 000000000..c527b4e78
--- /dev/null
+++ b/docs/diagrams/architecture/api-lib-contracts-3.mmd
@@ -0,0 +1,9 @@
+sequenceDiagram
+    participant Client
+    participant ApiService as "API Service"
+    participant Agent
+
+    Client->>ApiService: RunCommandInput
+    ApiService->>Agent: Dispatch command
+    Agent-->>ApiService: executionId
+    ApiService-->>Client: CommandDispatchResponse
diff --git a/docs/diagrams/architecture/api-lib-contracts-4.mmd b/docs/diagrams/architecture/api-lib-contracts-4.mmd
new file mode 100644
index 000000000..f607e202e
--- /dev/null
+++ b/docs/diagrams/architecture/api-lib-contracts-4.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Request["Create / Update Request"] --> Mapper["OrganizationMapper"]
+    Mapper --> Entity["Organization Entity"]
+    Entity --> Mapper
+    Mapper --> Response["OrganizationResponse"]
diff --git a/docs/diagrams/architecture/api-lib-contracts-5.mmd b/docs/diagrams/architecture/api-lib-contracts-5.mmd
new file mode 100644
index 000000000..0f0bfefab
--- /dev/null
+++ b/docs/diagrams/architecture/api-lib-contracts-5.mmd
@@ -0,0 +1,13 @@
+flowchart TD
+    Contracts["Api Lib Contracts"]
+    Api["API Service Core"]
+    Auth["Authorization Service"]
+    Data["Mongo Data Layer"]
+    Gateway["Gateway Service"]
+    Frontend["Frontend UI"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> Api
+    Api --> Contracts
+    Api --> Data
diff --git a/docs/diagrams/architecture/api-lib-contracts.mmd b/docs/diagrams/architecture/api-lib-contracts.mmd
new file mode 100644
index 000000000..cf600b21c
--- /dev/null
+++ b/docs/diagrams/architecture/api-lib-contracts.mmd
@@ -0,0 +1,8 @@
+flowchart LR
+    Frontend["Frontend UI and Chat"] -->|"GraphQL / REST"| ApiService["API Service Core"]
+    ApiService -->|"Uses DTOs"| Contracts["Api Lib Contracts"]
+    Contracts -->|"Maps to"| DataModels["Mongo Data Models"]
+    ApiService -->|"Queries"| DataModels
+    Stream["Stream Processing Kafka"] -->|"Publishes Events"| DataModels
+    Gateway["Gateway Service Core"] -->|"Secured Requests"| ApiService
+    Auth["Authorization Service Core"] -->|"JWT / Tenant Context"| ApiService
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql-2.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql-2.mmd
new file mode 100644
index 000000000..2e2bbe913
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql-2.mmd
@@ -0,0 +1,12 @@
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant ApiService
+    participant AuthServer
+
+    Client->>Gateway: HTTP Request
+    Gateway->>AuthServer: Validate JWT
+    AuthServer-->>Gateway: Token valid
+    Gateway->>ApiService: Forward request with Authorization header
+    ApiService->>ApiService: Resolve AuthPrincipal
+    ApiService-->>Client: JSON / GraphQL response
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql-3.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql-3.mmd
new file mode 100644
index 000000000..80ee1fa69
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql-3.mmd
@@ -0,0 +1,7 @@
+flowchart LR
+    Request["HTTP Request"] --> Controller["@RestController"]
+    Controller --> Service["Application Service"]
+    Service --> Repository["Mongo Repository"]
+    Repository --> Service
+    Service --> Controller
+    Controller --> Response["HTTP Response"]
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql-4.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql-4.mmd
new file mode 100644
index 000000000..045bb0fd2
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql-4.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    Query["GraphQL Query"] --> DataFetcher["@DgsQuery / @DgsMutation"]
+    DataFetcher --> Mapper["GraphQL Mapper"]
+    Mapper --> Service["Domain Service"]
+    Service --> Repository["Mongo Repository"]
+    Repository --> Service
+    Service --> Mapper
+    Mapper --> Connection["Connection / Edge DTO"]
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql-5.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql-5.mmd
new file mode 100644
index 000000000..89a994dbb
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql-5.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    NodeQuery["node(id)"] --> NodeFetcher["NodeDataFetcher"]
+    NodeFetcher --> TypeSwitch["NodeTypeResolver"]
+    TypeSwitch --> Machine["Machine"]
+    TypeSwitch --> Organization["Organization"]
+    TypeSwitch --> Event["Event"]
+    TypeSwitch --> Ticket["Ticket"]
+    TypeSwitch --> KnowledgeBaseItem["KnowledgeBaseItem"]
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql-6.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql-6.mmd
new file mode 100644
index 000000000..0e10121f9
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql-6.mmd
@@ -0,0 +1,6 @@
+flowchart LR
+    ClientArgs["first / after"] --> ConnectionArgs
+    ConnectionArgs --> CursorCriteria
+    CursorCriteria --> ServiceQuery
+    ServiceQuery --> QueryResult
+    QueryResult --> ConnectionDTO
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql-7.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql-7.mmd
new file mode 100644
index 000000000..00ff28fb2
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql-7.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    GraphQLField["Resolve field"] --> DataLoader
+    DataLoader --> BatchLoad["Batch Repository Query"]
+    BatchLoad --> ResultMap
+    ResultMap --> Response
diff --git a/docs/diagrams/architecture/api-service-core-http-and-graphql.mmd b/docs/diagrams/architecture/api-service-core-http-and-graphql.mmd
new file mode 100644
index 000000000..338c84359
--- /dev/null
+++ b/docs/diagrams/architecture/api-service-core-http-and-graphql.mmd
@@ -0,0 +1,14 @@
+flowchart TD
+    Client["Frontend / API Client"] --> Gateway["Gateway Service Core"]
+    Gateway --> ApiService["Api Service Core Http And Graphql"]
+
+    ApiService --> Controllers["REST Controllers"]
+    ApiService --> GraphQL["GraphQL DataFetchers"]
+
+    Controllers --> Services["Application Services"]
+    GraphQL --> Services
+
+    Services --> Mongo["Mongo Repositories"]
+    Services --> Stream["Kafka / Stream Processing"]
+
+    ApiService --> Authz["Authorization Service Core"]
diff --git a/docs/diagrams/architecture/authorization-service-core-10.mmd b/docs/diagrams/architecture/authorization-service-core-10.mmd
new file mode 100644
index 000000000..be2730515
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-10.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    User --> Request["POST /password-reset/request"]
+    Request --> Service["PasswordResetService"]
+    Service --> Token["Generate Reset Token"]
+
+    User --> Confirm["POST /password-reset/confirm"]
+    Confirm --> Validate["Validate Token"]
+    Validate --> Update["Update Password"]
diff --git a/docs/diagrams/architecture/authorization-service-core-11.mmd b/docs/diagrams/architecture/authorization-service-core-11.mmd
new file mode 100644
index 000000000..088a3aff3
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-11.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    AuthServer["OAuth2Authorization"] --> Mapper["MongoAuthorizationMapper"]
+    Mapper --> Entity["MongoOAuth2Authorization"]
+    Entity --> Repo["MongoOAuth2AuthorizationRepository"]
+    Repo --> Mongo[("MongoDB")]
diff --git a/docs/diagrams/architecture/authorization-service-core-12.mmd b/docs/diagrams/architecture/authorization-service-core-12.mmd
new file mode 100644
index 000000000..cefd0c8f1
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-12.mmd
@@ -0,0 +1,14 @@
+flowchart LR
+    Frontend["Frontend"] --> Gateway
+    Gateway -->|"Bearer Token"| Api
+    Gateway -->|"JWT Validation"| Authorization
+    Authorization -->|"Token Issuance"| Gateway
+
+    Authorization --> Data
+
+    subgraph Services["OpenFrame Services"]
+        Authorization["Authorization Service Core"]
+        Api["API Service Core"]
+        Gateway["Gateway Service Core"]
+        Data["Mongo Data Layer"]
+    end
diff --git a/docs/diagrams/architecture/authorization-service-core-2.mmd b/docs/diagrams/architecture/authorization-service-core-2.mmd
new file mode 100644
index 000000000..f14a05a67
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-2.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Request["Incoming HTTP Request"] --> Filter["TenantContextFilter"]
+    Filter --> Context["TenantContext (ThreadLocal)"]
+    Context --> AuthFlow["Authentication / Token Flow"]
+    AuthFlow --> Clear["TenantContext.clear()"]
diff --git a/docs/diagrams/architecture/authorization-service-core-3.mmd b/docs/diagrams/architecture/authorization-service-core-3.mmd
new file mode 100644
index 000000000..82be9be87
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-3.mmd
@@ -0,0 +1,7 @@
+flowchart TD
+    Config["AuthorizationServerConfig"] --> SecurityChain["SecurityFilterChain (Order 1)"]
+    SecurityChain --> OAuth2["OAuth2AuthorizationServerConfigurer"]
+    OAuth2 --> OIDC["OIDC Enabled"]
+    OAuth2 --> JWT["JWT Resource Server"]
+    Config --> JWKSource["Tenant-aware JWKSource"]
+    Config --> TokenCustomizer["JWT Token Customizer"]
diff --git a/docs/diagrams/architecture/authorization-service-core-4.mmd b/docs/diagrams/architecture/authorization-service-core-4.mmd
new file mode 100644
index 000000000..4a77a4089
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-4.mmd
@@ -0,0 +1,7 @@
+flowchart TD
+    TokenRequest["Access Token Request"] --> KeyService["TenantKeyService"]
+    KeyService --> Repo["TenantKeyRepository"]
+    KeyService --> Generator["RsaAuthenticationKeyPairGenerator"]
+    KeyService --> Encrypt["EncryptionService"]
+    KeyService --> JWT["RSAKey (JWK)"]
+    JWT --> Encoder["NimbusJwtEncoder"]
diff --git a/docs/diagrams/architecture/authorization-service-core-5.mmd b/docs/diagrams/architecture/authorization-service-core-5.mmd
new file mode 100644
index 000000000..779361d14
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-5.mmd
@@ -0,0 +1,4 @@
+flowchart TD
+    Principal["Authenticated User"] --> Customizer["OAuth2TokenCustomizer"]
+    Customizer --> Claims["Add Claims"]
+    Claims --> JWT["Signed JWT"]
diff --git a/docs/diagrams/architecture/authorization-service-core-6.mmd b/docs/diagrams/architecture/authorization-service-core-6.mmd
new file mode 100644
index 000000000..debed29b2
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-6.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    User["User"] -->|"/login"| FormLogin["Form Login"]
+    User -->|"/oauth2/authorization/{provider}"| OAuthLogin["OIDC Login"]
+
+    OAuthLogin --> DecoderFactory["Microsoft-Aware JWT Decoder"]
+    OAuthLogin --> OidcUserService["Custom OIDC User Service"]
+    OidcUserService --> AutoProvision["Auto Provisioning"]
+    AutoProvision --> UserService["UserService"]
diff --git a/docs/diagrams/architecture/authorization-service-core-7.mmd b/docs/diagrams/architecture/authorization-service-core-7.mmd
new file mode 100644
index 000000000..77d8d4cd0
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-7.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    OAuthFlow["OAuth2 Login Flow"] --> Repo["DynamicClientRegistrationRepository"]
+    Repo --> Context["TenantContext"]
+    Repo --> DynamicService["DynamicClientRegistrationService"]
+    DynamicService --> Client["ClientRegistration"]
diff --git a/docs/diagrams/architecture/authorization-service-core-8.mmd b/docs/diagrams/architecture/authorization-service-core-8.mmd
new file mode 100644
index 000000000..ebc11c745
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-8.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    User --> Init["/oauth/register/sso"]
+    Init --> Cookie["Set SSO Registration Cookie"]
+    Cookie --> Provider["Redirect to Google/Microsoft"]
+    Provider --> Callback["OIDC Callback"]
+    Callback --> Handler["TenantRegSsoHandler"]
+    Handler --> TenantService["TenantRegistrationService"]
+    TenantService --> Redirect["Redirect to Tenant OAuth Flow"]
diff --git a/docs/diagrams/architecture/authorization-service-core-9.mmd b/docs/diagrams/architecture/authorization-service-core-9.mmd
new file mode 100644
index 000000000..7e526636a
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core-9.mmd
@@ -0,0 +1,7 @@
+flowchart TD
+    User --> Accept["/invitations/accept/sso"]
+    Accept --> Cookie["Set Invite Cookie"]
+    Cookie --> Provider["Redirect to Provider"]
+    Provider --> Callback["OIDC Callback"]
+    Callback --> InviteHandler["InviteSsoHandler"]
+    InviteHandler --> InviteService["InvitationRegistrationService"]
diff --git a/docs/diagrams/architecture/authorization-service-core.mmd b/docs/diagrams/architecture/authorization-service-core.mmd
new file mode 100644
index 000000000..7312b2799
--- /dev/null
+++ b/docs/diagrams/architecture/authorization-service-core.mmd
@@ -0,0 +1,7 @@
+flowchart LR
+    Browser["User Browser"] -->|"Login / OAuth2"| AuthServer["Authorization Service Core"]
+    AuthServer -->|"JWT Access Token"| Gateway["Gateway Service Core"]
+    Gateway -->|"Validated Request"| ApiService["API Service Core"]
+
+    AuthServer -->|"Persist Authorizations"| Mongo[("MongoDB")]
+    AuthServer -->|"Load Users / Tenants"| DataLayer["Data Models & Repositories"]
diff --git a/docs/diagrams/architecture/data-models-and-repositories-mongo-2.mmd b/docs/diagrams/architecture/data-models-and-repositories-mongo-2.mmd
new file mode 100644
index 000000000..1a0d74b3a
--- /dev/null
+++ b/docs/diagrams/architecture/data-models-and-repositories-mongo-2.mmd
@@ -0,0 +1,5 @@
+flowchart LR
+    Request["Incoming Request"] --> TenantContext["TenantIdProvider"]
+    TenantContext --> Repository["Tenant-Scoped Repository"]
+    Repository --> Query["Mongo Query with tenantId"]
+    Query --> MongoDB[("MongoDB")]
diff --git a/docs/diagrams/architecture/data-models-and-repositories-mongo-3.mmd b/docs/diagrams/architecture/data-models-and-repositories-mongo-3.mmd
new file mode 100644
index 000000000..2b9d5764e
--- /dev/null
+++ b/docs/diagrams/architecture/data-models-and-repositories-mongo-3.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    GraphQL["GraphQL Input Filter"] --> FilterObject["QueryFilter DTO"]
+    FilterObject --> CustomRepo["Custom Repository"]
+    CustomRepo --> MongoQuery["Mongo Query + Criteria"]
+    MongoQuery --> MongoDB[("MongoDB")]
diff --git a/docs/diagrams/architecture/data-models-and-repositories-mongo-4.mmd b/docs/diagrams/architecture/data-models-and-repositories-mongo-4.mmd
new file mode 100644
index 000000000..bc69eb6fb
--- /dev/null
+++ b/docs/diagrams/architecture/data-models-and-repositories-mongo-4.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Client["Client"] --> QueryBuilder["Build Query"]
+    QueryBuilder --> ApplyCursor["Apply _id comparison"]
+    ApplyCursor --> ApplySort["Apply Sort + Limit"]
+    ApplySort --> Execute["mongoTemplate.find"]
+    Execute --> Page["Result Page"]
diff --git a/docs/diagrams/architecture/data-models-and-repositories-mongo-5.mmd b/docs/diagrams/architecture/data-models-and-repositories-mongo-5.mmd
new file mode 100644
index 000000000..b68e44ca4
--- /dev/null
+++ b/docs/diagrams/architecture/data-models-and-repositories-mongo-5.mmd
@@ -0,0 +1,4 @@
+flowchart LR
+    Tickets[("tickets collection")] --> Group["$group"]
+    Group --> Project["$project"]
+    Project --> Metrics["Aggregated Metrics"]
diff --git a/docs/diagrams/architecture/data-models-and-repositories-mongo.mmd b/docs/diagrams/architecture/data-models-and-repositories-mongo.mmd
new file mode 100644
index 000000000..1d29cfd72
--- /dev/null
+++ b/docs/diagrams/architecture/data-models-and-repositories-mongo.mmd
@@ -0,0 +1,9 @@
+flowchart TD
+    Controllers["API / GraphQL / Auth Controllers"] --> Services["Application Services"]
+    Services --> Repositories["Mongo Repositories"]
+    Repositories --> CustomImpl["Custom Repository Implementations"]
+    Repositories --> ReactiveImpl["Reactive Repositories"]
+    CustomImpl --> MongoTemplate["MongoTemplate"]
+    ReactiveImpl --> ReactiveMongo["ReactiveMongoRepository"]
+    MongoTemplate --> MongoDB[("MongoDB")]
+    ReactiveMongo --> MongoDB
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-10.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-10.mmd
new file mode 100644
index 000000000..48421720f
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-10.mmd
@@ -0,0 +1,9 @@
+flowchart LR
+    Backend --> NATS["NATS / JetStream"]
+    Backend --> SSE["SSE"]
+
+    NATS --> Subscription["useNatsDialogSubscription"]
+    SSE --> Adapter["useSseChatAdapter"]
+
+    Subscription --> Processor
+    Adapter --> Processor
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-2.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-2.mmd
new file mode 100644
index 000000000..7233b0d37
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-2.mmd
@@ -0,0 +1,11 @@
+flowchart TD
+    EmbeddableChat --> UnifiedChat["useUnifiedChat"]
+
+    UnifiedChat --> GuideMode["Guide Mode (SSE)"]
+    UnifiedChat --> MingoMode["Mingo Mode (NATS)"]
+
+    GuideMode --> SSEAdapter["useSseChatAdapter"]
+    MingoMode --> NatsAdapter["useNatsChatAdapter"]
+
+    SSEAdapter --> SSEBackend["API Service (SSE)"]
+    NatsAdapter --> NatsBackend["Stream Processing (NATS)"]
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-3.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-3.mmd
new file mode 100644
index 000000000..600120e7a
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-3.mmd
@@ -0,0 +1,5 @@
+flowchart LR
+    Chunk["ChunkData"] --> Processor["useRealtimeChunkProcessor"]
+    Processor --> Segments["MessageSegment[]"]
+    Segments --> Message["Message"]
+    Message --> UI["ChatMessageRow"]
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-4.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-4.mmd
new file mode 100644
index 000000000..d8cbbad61
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-4.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    DialogList --> History["MingoChatHistory"]
+    History --> Row["History Row"]
+    Row --> Rename["Rename Modal"]
+    Row --> Archive["Archive Modal"]
+    Archive --> ArchivePage["ChatArchivePage"]
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-5.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-5.mmd
new file mode 100644
index 000000000..ccf35792c
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-5.mmd
@@ -0,0 +1,4 @@
+flowchart TD
+    Identity["useChatIdentity"] --> Check{Auth Tier?}
+    Check -->|anon| Empty["Sign-in EmptyState"]
+    Check -->|authenticated| TicketCenterAuthed
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-6.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-6.mmd
new file mode 100644
index 000000000..60a1eac56
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-6.mmd
@@ -0,0 +1,6 @@
+flowchart LR
+    Ticket["TicketCard"] --> DndContext
+    DndContext --> DragStart
+    DragStart --> DragOver
+    DragOver --> DragEnd
+    DragEnd --> OnChange["BoardChange"]
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-7.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-7.mmd
new file mode 100644
index 000000000..c24face0b
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-7.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    NotificationContext --> Drawer
+    Drawer --> UnreadList
+    UnreadList --> Tile["NotificationTile"]
+    Tile --> MarkRead
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-8.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-8.mmd
new file mode 100644
index 000000000..c46153050
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-8.mmd
@@ -0,0 +1,5 @@
+flowchart LR
+    Table --> Header
+    Table --> Row
+    Header --> SortChange
+    Row --> RowClick
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat-9.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat-9.mmd
new file mode 100644
index 000000000..42b843ba9
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat-9.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Viewport --> Breakpoint{md / lg?}
+    Breakpoint -->|Desktop| PersistentSidebar
+    Breakpoint -->|Tablet| OverlaySidebar
+    OverlaySidebar --> Backdrop
diff --git a/docs/diagrams/architecture/frontend-core-ui-and-chat.mmd b/docs/diagrams/architecture/frontend-core-ui-and-chat.mmd
new file mode 100644
index 000000000..8f742ff26
--- /dev/null
+++ b/docs/diagrams/architecture/frontend-core-ui-and-chat.mmd
@@ -0,0 +1,24 @@
+flowchart LR
+    User["User"] --> UI["Frontend Core Ui And Chat"]
+
+    subgraph ChatLayer["Chat System"]
+        EmbeddableChat["EmbeddableChat"]
+        Composer["ChatComposer"]
+        MessageRow["ChatMessageRow"]
+        DialogHistory["MingoChatHistory"]
+    end
+
+    subgraph FeatureLayer["Feature Surfaces"]
+        TicketCenter["TicketCenter"]
+        Board["Board"]
+        Notifications["NotificationDrawer"]
+        DataTable["DataTable Components"]
+    end
+
+    UI --> ChatLayer
+    UI --> FeatureLayer
+
+    ChatLayer --> Runtime["Chat Runtime Context"]
+    ChatLayer --> Transport["SSE / NATS / WebSocket"]
+
+    Transport --> Backend["API Service + Stream Processing"]
diff --git a/docs/diagrams/architecture/gateway-service-core-2.mmd b/docs/diagrams/architecture/gateway-service-core-2.mmd
new file mode 100644
index 000000000..3df57ecea
--- /dev/null
+++ b/docs/diagrams/architecture/gateway-service-core-2.mmd
@@ -0,0 +1,12 @@
+flowchart TD
+    Netty["Netty & WebFlux Runtime"] --> Filters["Security & Global Filters"]
+    Filters --> Controllers["REST Controllers"]
+    Filters --> WsRoutes["WebSocket Routes"]
+
+    Controllers --> RestProxy["REST Proxy Layer"]
+    WsRoutes --> WsProxy["WebSocket Proxy Layer"]
+
+    RestProxy --> UpstreamResolvers["Tool Upstream Resolvers"]
+    WsProxy --> UpstreamResolvers
+
+    UpstreamResolvers --> Downstream["Integrated Tools / Services"]
diff --git a/docs/diagrams/architecture/gateway-service-core-3.mmd b/docs/diagrams/architecture/gateway-service-core-3.mmd
new file mode 100644
index 000000000..39cba02f7
--- /dev/null
+++ b/docs/diagrams/architecture/gateway-service-core-3.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Request["Incoming JWT"] --> IssuerResolver["Issuer Resolver"]
+    IssuerResolver --> Cache["Caffeine Cache"]
+    Cache --> JwtDecoder["JWT Decoder"]
+    JwtDecoder --> Validator["Issuer + Default Validators"]
+    Validator --> Authenticated["Authenticated Principal"]
diff --git a/docs/diagrams/architecture/gateway-service-core-4.mmd b/docs/diagrams/architecture/gateway-service-core-4.mmd
new file mode 100644
index 000000000..478726b86
--- /dev/null
+++ b/docs/diagrams/architecture/gateway-service-core-4.mmd
@@ -0,0 +1,8 @@
+flowchart TD
+    Req["Request /external-api/**"] --> CheckHeader["X-API-Key Present?"]
+    CheckHeader -->|"No"| Reject["401 Unauthorized"]
+    CheckHeader -->|"Yes"| Validate["Validate API Key"]
+    Validate -->|"Invalid"| Reject
+    Validate -->|"Valid"| RateCheck["Rate Limit Check"]
+    RateCheck -->|"Exceeded"| TooMany["429 Too Many Requests"]
+    RateCheck -->|"Allowed"| Forward["Forward Request"]
diff --git a/docs/diagrams/architecture/gateway-service-core-5.mmd b/docs/diagrams/architecture/gateway-service-core-5.mmd
new file mode 100644
index 000000000..2570ddb42
--- /dev/null
+++ b/docs/diagrams/architecture/gateway-service-core-5.mmd
@@ -0,0 +1,6 @@
+flowchart LR
+    ClientWS["WebSocket Client"] --> GatewayWS["WebSocket Gateway"]
+    GatewayWS --> ToolResolver["Tool Upstream Resolver"]
+    ToolResolver --> Mesh["MeshCentral"]
+    ToolResolver --> Tactical["Tactical RMM"]
+    GatewayWS --> Nats["NATS"]
diff --git a/docs/diagrams/architecture/gateway-service-core-6.mmd b/docs/diagrams/architecture/gateway-service-core-6.mmd
new file mode 100644
index 000000000..f429dbe05
--- /dev/null
+++ b/docs/diagrams/architecture/gateway-service-core-6.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Request["Tool Request"] --> ResolverRegistry["Resolver Registry"]
+    ResolverRegistry -->|"meshcentral-server"| MeshResolver["MeshCentral Resolver"]
+    ResolverRegistry -->|"tactical-rmm"| TacticalResolver["Tactical RMM Resolver"]
+    ResolverRegistry -->|"other"| DefaultResolver["Default Resolver"]
diff --git a/docs/diagrams/architecture/gateway-service-core.mmd b/docs/diagrams/architecture/gateway-service-core.mmd
new file mode 100644
index 000000000..a54c6bc60
--- /dev/null
+++ b/docs/diagrams/architecture/gateway-service-core.mmd
@@ -0,0 +1,11 @@
+flowchart LR
+    Browser["Frontend UI"] --> Gateway["Gateway Service Core"]
+    Agent["OpenFrame Agent"] --> Gateway
+    ExternalAPI["External API Client"] --> Gateway
+
+    Gateway --> ApiService["API Service Core"]
+    Gateway --> AuthService["Authorization Service Core"]
+    Gateway --> Management["Management Service Core"]
+    Gateway --> ToolMesh["MeshCentral"]
+    Gateway --> ToolTactical["Tactical RMM"]
+    Gateway --> Nats["NATS WebSocket"]
diff --git a/docs/diagrams/architecture/management-service-core-2.mmd b/docs/diagrams/architecture/management-service-core-2.mmd
new file mode 100644
index 000000000..4922e6f3a
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-2.mmd
@@ -0,0 +1,3 @@
+flowchart LR
+    Scheduler["Scheduled Task"] --> ShedLock["ShedLock"]
+    ShedLock --> Redis["Redis Lock Provider"]
diff --git a/docs/diagrams/architecture/management-service-core-3.mmd b/docs/diagrams/architecture/management-service-core-3.mmd
new file mode 100644
index 000000000..ad36b5703
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-3.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Controller["DevicePinotResyncController"] --> Repo["MachineRepository"]
+    Controller --> EventService["MachineTagEventService"]
+    Repo --> Mongo["MongoDB"]
+    EventService --> Stream["Event Processing"]
diff --git a/docs/diagrams/architecture/management-service-core-4.mmd b/docs/diagrams/architecture/management-service-core-4.mmd
new file mode 100644
index 000000000..946391f1e
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-4.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Request["Save Tool Request"] --> Service["IntegratedToolService"]
+    Service --> Mongo["MongoDB"]
+    Service --> Debezium["DebeziumService"]
+    Service --> Hooks["Post Save Hooks"]
diff --git a/docs/diagrams/architecture/management-service-core-5.mmd b/docs/diagrams/architecture/management-service-core-5.mmd
new file mode 100644
index 000000000..dd403dd31
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-5.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Startup["Application Startup"] --> SecretInit["Agent Registration Secret"]
+    Startup --> ToolAgentInit["Integrated Tool Agent Config"]
+    Startup --> NatsInit["NATS Stream Config"]
+    Startup --> ClientInit["Client Configuration"]
+    Startup --> TacticalInit["Tactical RMM Scripts"]
diff --git a/docs/diagrams/architecture/management-service-core-6.mmd b/docs/diagrams/architecture/management-service-core-6.mmd
new file mode 100644
index 000000000..176a7cdfd
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-6.mmd
@@ -0,0 +1,6 @@
+flowchart LR
+    Init["NATS Stream Initializer"] --> Stream1["TOOL_INSTALLATION"]
+    Init --> Stream2["CLIENT_UPDATE"]
+    Init --> Stream3["TOOL_UPDATE"]
+    Init --> Stream4["TOOL_CONNECTIONS"]
+    Init --> Stream5["INSTALLED_AGENTS"]
diff --git a/docs/diagrams/architecture/management-service-core-7.mmd b/docs/diagrams/architecture/management-service-core-7.mmd
new file mode 100644
index 000000000..1517f80b8
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-7.mmd
@@ -0,0 +1,4 @@
+flowchart TD
+    Migration["Mongock Migration"] --> BackfillVersion["Backfill Document Version"]
+    Migration --> BackfillOrder["Backfill Ticket Order"]
+    Migration --> StatusMigration["Migrate Ticket Status Model"]
diff --git a/docs/diagrams/architecture/management-service-core-8.mmd b/docs/diagrams/architecture/management-service-core-8.mmd
new file mode 100644
index 000000000..2bf43f931
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core-8.mmd
@@ -0,0 +1,5 @@
+flowchart TD
+    Scheduler["Schedulers"] --> AgentVersion["Agent Version Fallback"]
+    Scheduler --> ApiKeySync["API Key Stats Sync"]
+    Scheduler --> Heartbeat["Device Offline Detection"]
+    Scheduler --> FleetMdm["Fleet MDM Setup"]
diff --git a/docs/diagrams/architecture/management-service-core.mmd b/docs/diagrams/architecture/management-service-core.mmd
new file mode 100644
index 000000000..941b3f5f5
--- /dev/null
+++ b/docs/diagrams/architecture/management-service-core.mmd
@@ -0,0 +1,11 @@
+flowchart TD
+    Gateway["Gateway Service Core"] --> API["API Service Core HTTP and GraphQL"]
+    API --> Data["Data Models and Repositories Mongo"]
+    API --> Stream["Stream Processing Kafka"]
+
+    Management["Management Service Core"] --> Data
+    Management --> Redis["Redis"]
+    Management --> NATS["NATS Streams"]
+    Management --> KafkaConnect["Kafka Connect / Debezium"]
+
+    Stream --> Data
diff --git a/docs/diagrams/architecture/stream-processing-kafka-2.mmd b/docs/diagrams/architecture/stream-processing-kafka-2.mmd
new file mode 100644
index 000000000..2934888be
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-2.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Config["KafkaStreamsConfig"] --> AppId["Application ID"]
+    Config --> Serdes["Custom JSON Serdes"]
+    Config --> ConsumerCfg["Consumer Config"]
+    Config --> ProducerCfg["Producer Config"]
+    Config --> StateDir["State Store Directory"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka-3.mmd b/docs/diagrams/architecture/stream-processing-kafka-3.mmd
new file mode 100644
index 000000000..4161fe769
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-3.mmd
@@ -0,0 +1,3 @@
+flowchart LR
+    Topics["Inbound Kafka Topics"] --> Listener["JsonKafkaListener"]
+    Listener --> Processor["GenericJsonMessageProcessor"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka-4.mmd b/docs/diagrams/architecture/stream-processing-kafka-4.mmd
new file mode 100644
index 000000000..6ea679c95
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-4.mmd
@@ -0,0 +1,6 @@
+flowchart TD
+    Source["Tool Event"] --> ToolType["IntegratedToolType"]
+    Source --> SourceType["Source Event Type"]
+    ToolType --> Mapper["EventTypeMapper"]
+    SourceType --> Mapper
+    Mapper --> Unified["UnifiedEventType"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka-5.mmd b/docs/diagrams/architecture/stream-processing-kafka-5.mmd
new file mode 100644
index 000000000..c14b6a60f
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-5.mmd
@@ -0,0 +1,5 @@
+flowchart LR
+    Event["DeserializedDebeziumMessage"] --> Enrichment
+    Enrichment --> MachineCache["MachineIdCacheService"]
+    Enrichment --> TenantResolver["Tenant Resolver"]
+    Enrichment --> Enriched["IntegratedToolEnrichedData"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka-6.mmd b/docs/diagrams/architecture/stream-processing-kafka-6.mmd
new file mode 100644
index 000000000..aa055b136
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-6.mmd
@@ -0,0 +1,4 @@
+flowchart TD
+    DebeziumMsg["DeserializedDebeziumMessage"] --> Transform
+    Transform --> Unified["UnifiedLogEvent"]
+    Unified --> Cassandra["Cassandra Repository"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka-7.mmd b/docs/diagrams/architecture/stream-processing-kafka-7.mmd
new file mode 100644
index 000000000..4d9dc7cfb
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-7.mmd
@@ -0,0 +1,5 @@
+flowchart LR
+    Activity["Activity Topic"] --> Join
+    HostActivity["HostActivity Topic"] --> Join
+    Join --> Enriched["Enriched Activity"]
+    Enriched --> Output["Fleet MDM Events Topic"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka-8.mmd b/docs/diagrams/architecture/stream-processing-kafka-8.mmd
new file mode 100644
index 000000000..a19885a6a
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka-8.mmd
@@ -0,0 +1,10 @@
+flowchart TD
+    A["Integrated Tool"] --> B["Debezium CDC"]
+    B --> C["Kafka Topic"]
+    C --> D["JsonKafkaListener"]
+    D --> E["Deserializer"]
+    E --> F["Data Enrichment"]
+    F --> G["EventTypeMapper"]
+    G --> H["Message Handler"]
+    H --> I["Cassandra"]
+    H --> J["Outbound Kafka"]
diff --git a/docs/diagrams/architecture/stream-processing-kafka.mmd b/docs/diagrams/architecture/stream-processing-kafka.mmd
new file mode 100644
index 000000000..7ae199d1c
--- /dev/null
+++ b/docs/diagrams/architecture/stream-processing-kafka.mmd
@@ -0,0 +1,11 @@
+flowchart LR
+    ToolA["Integrated Tools\nMeshCentral / Tactical / Fleet"] --> Debezium["Debezium CDC"]
+    Debezium --> KafkaIn["Kafka Inbound Topics"]
+    KafkaIn --> Listener["JsonKafkaListener"]
+    Listener --> Processor["GenericJsonMessageProcessor"]
+    Processor --> Deserializer["Tool-Specific Deserializers"]
+    Deserializer --> Enrichment["IntegratedToolDataEnrichmentService"]
+    Enrichment --> Mapper["EventTypeMapper"]
+    Mapper --> Handler["DebeziumMessageHandler"]
+    Handler --> Cassandra["Cassandra (UnifiedLogEvent)"]
+    Handler --> KafkaOut["Outbound Kafka Topics"]
diff --git a/docs/reference/architecture/.gitignore b/docs/reference/architecture/.gitignore
new file mode 100644
index 000000000..b4f4c7a6c
--- /dev/null
+++ b/docs/reference/architecture/.gitignore
@@ -0,0 +1,8 @@
+# CodeWiki temp files (dependency graphs can be 7GB+)
+temp/
+dependency_graphs/
+
+# JSON intermediate files (except schema/config)
+*.json
+!*-schema.json
+!*-config.json
diff --git a/docs/reference/architecture/README.md b/docs/reference/architecture/README.md
new file mode 100644
index 000000000..c234fea88
--- /dev/null
+++ b/docs/reference/architecture/README.md
@@ -0,0 +1,405 @@
+# OpenFrame OSS Lib – Repository Overview
+
+The **`openframe-oss-lib`** repository is the modular backbone of the OpenFrame platform — Flamingo’s AI-powered MSP stack.  
+
+It provides:
+
+- ✅ Multi-tenant identity & OAuth2 authorization  
+- ✅ Reactive API layer (REST + GraphQL)  
+- ✅ Gateway & WebSocket routing  
+- ✅ MongoDB data layer (reactive + sync)  
+- ✅ Kafka-based stream processing & enrichment  
+- ✅ Operational management services  
+- ✅ Frontend UI & AI Chat foundation  
+- ✅ Shared API contract definitions  
+
+This repository is structured as independent but composable modules forming a full end-to-end MSP platform stack.
+
+---
+
+# High-Level Architecture
+
+Below is the complete system architecture represented across modules in this repository.
+
+```mermaid
+flowchart TD
+    Frontend["Frontend Core UI and Chat"]
+    Gateway["Gateway Service Core"]
+    Auth["Authorization Service Core"]
+    API["API Service Core (HTTP + GraphQL)"]
+    Management["Management Service Core"]
+    Data["Data Models and Repositories Mongo"]
+    Stream["Stream Processing Kafka"]
+    Cassandra["Cassandra (Unified Events)"]
+    Tools["Integrated Tools (MeshCentral, Tactical, Fleet)"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    API --> Data
+    API --> Stream
+    Stream --> Cassandra
+    Stream --> Data
+    Management --> Data
+    Management --> Stream
+    Tools --> Stream
+```
+
+---
+
+# Repository Modules
+
+## 1. `api-lib-contracts`
+
+**Purpose:**  
+Defines all shared DTOs, filters, pagination primitives, and API boundary contracts.
+
+### Responsibilities
+
+- Device, Organization, Script, Tool, KnowledgeBase DTOs  
+- Relay-style pagination (`ConnectionArgs`, `CursorCodec`)  
+- Filter criteria objects (DeviceFilterCriteria, LogFilterCriteria, etc.)  
+- Command dispatch contracts  
+- Shared mappers (e.g., `OrganizationMapper`)  
+
+### Architectural Role
+
+```mermaid
+flowchart LR
+    Frontend --> API
+    API --> Contracts["Api Lib Contracts"]
+    Contracts --> Data
+```
+
+📘 See module documentation: **Api Lib Contracts**
+
+---
+
+## 2. `api-service-core-http-and-graphql`
+
+**Purpose:**  
+Primary application-layer API surface.
+
+Exposes:
+
+- REST endpoints
+- GraphQL (Netflix DGS)
+- Relay global node resolution
+- DataLoader batching
+- OAuth2 Resource Server security
+
+### Key Components
+
+- Controllers (Device, Organization, User, Invitation, SSOConfig, etc.)
+- GraphQL DataFetchers
+- DataLoaders (N+1 prevention)
+- SecurityConfig (JWT validation)
+- Relay Node resolvers
+
+### API Flow
+
+```mermaid
+flowchart TD
+    Client["Frontend / API Client"] --> Gateway
+    Gateway --> API
+    API --> Controllers
+    API --> GraphQL
+    Controllers --> Services
+    GraphQL --> Services
+    Services --> Data
+```
+
+📘 See module documentation: **Api Service Core HTTP And GraphQL**
+
+---
+
+## 3. `authorization-service-core`
+
+**Purpose:**  
+Multi-tenant OAuth2 + OIDC Authorization Server.
+
+Handles:
+
+- JWT issuance
+- Tenant-aware signing keys
+- Dynamic OIDC client registration
+- SSO (Google, Microsoft)
+- Password reset & invitations
+- OAuth2 persistence in Mongo
+
+### Token Flow
+
+```mermaid
+flowchart TD
+    User --> AuthServer["Authorization Service Core"]
+    AuthServer --> JWT["Tenant-Scoped JWT"]
+    JWT --> Gateway
+    Gateway --> API
+```
+
+Each tenant has:
+
+- Independent RSA keypair
+- Isolated issuer
+- Custom JWT claims
+
+📘 See module documentation: **Authorization Service Core**
+
+---
+
+## 4. `gateway-service-core`
+
+**Purpose:**  
+Reactive edge layer (Spring Cloud Gateway + WebFlux).
+
+Handles:
+
+- JWT validation
+- API key authentication
+- Rate limiting
+- REST & WebSocket proxying
+- Tool-specific upstream resolution
+
+### Edge Routing
+
+```mermaid
+flowchart LR
+    Browser --> Gateway
+    Agent --> Gateway
+    ExternalAPI --> Gateway
+
+    Gateway --> API
+    Gateway --> Auth
+    Gateway --> Tools
+```
+
+Supports:
+
+- MeshCentral
+- Tactical RMM
+- Fleet MDM
+- NATS WebSocket streams
+
+📘 See module documentation: **Gateway Service Core**
+
+---
+
+## 5. `management-service-core`
+
+**Purpose:**  
+Operational control plane.
+
+Handles:
+
+- Cluster version coordination
+- Tool lifecycle management
+- Initializers (NATS, agents, configs)
+- Distributed schedulers (ShedLock + Redis)
+- Mongo migrations (Mongock)
+- Background health tasks
+
+### Operational Flow
+
+```mermaid
+flowchart TD
+    Startup --> Initializers
+    Initializers --> Data
+    Scheduler --> Redis["ShedLock (Redis)"]
+    Scheduler --> Data
+    Scheduler --> Stream
+```
+
+📘 See module documentation: **Management Service Core**
+
+---
+
+## 6. `data-models-and-repositories-mongo`
+
+**Purpose:**  
+MongoDB persistence backbone.
+
+Includes:
+
+- Core documents (User, Device, Ticket, Organization, Event, Notification)
+- QueryFilter objects
+- Reactive + Sync repositories
+- Custom MongoTemplate implementations
+- Cursor pagination
+- Aggregation metrics
+
+### Data Layer Architecture
+
+```mermaid
+flowchart TD
+    Services --> Repositories
+    Repositories --> CustomImpl["Custom Repository"]
+    CustomImpl --> MongoTemplate
+    MongoTemplate --> MongoDB
+```
+
+Multi-tenant isolation enforced via `tenantId` field.
+
+📘 See module documentation: **Data Models And Repositories Mongo**
+
+---
+
+## 7. `stream-processing-kafka`
+
+**Purpose:**  
+Event ingestion & normalization pipeline.
+
+Consumes:
+
+- Debezium CDC events
+- MeshCentral
+- Tactical RMM
+- Fleet MDM
+
+Performs:
+
+- Tool-specific deserialization
+- Event normalization
+- Tenant resolution
+- Kafka Streams enrichment
+- Cassandra persistence
+
+### Event Pipeline
+
+```mermaid
+flowchart TD
+    Tools --> Debezium
+    Debezium --> KafkaTopic
+    KafkaTopic --> Listener
+    Listener --> Deserializer
+    Deserializer --> Enrichment
+    Enrichment --> Mapper
+    Mapper --> Handler
+    Handler --> Cassandra
+    Handler --> OutboundKafka
+```
+
+📘 See module documentation: **Stream Processing Kafka**
+
+---
+
+## 8. `frontend-core-ui-and-chat`
+
+**Purpose:**  
+Reusable UI foundation + AI Chat engine.
+
+Includes:
+
+- Embeddable AI assistant (Guide + Mingo modes)
+- Ticket Center
+- Kanban Board
+- Notifications Drawer
+- Data Tables
+- Runtime-driven navigation
+
+### Chat Architecture
+
+```mermaid
+flowchart TD
+    EmbeddableChat --> UnifiedChat
+    UnifiedChat --> GuideMode["SSE Mode"]
+    UnifiedChat --> MingoMode["NATS Mode"]
+    GuideMode --> API
+    MingoMode --> Stream
+```
+
+Designed for:
+
+- Platform embedding
+- Runtime injection
+- Transport abstraction
+- Segment-based streaming messages
+
+📘 See module documentation: **Frontend Core UI And Chat**
+
+---
+
+# End-to-End Request Flow
+
+Below is a full lifecycle example: user logs in, performs an action, and event propagates.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Gateway
+    participant Auth
+    participant API
+    participant Stream
+    participant Data
+
+    User->>Gateway: Login Request
+    Gateway->>Auth: OAuth2 Flow
+    Auth-->>Gateway: JWT
+    Gateway->>API: Authenticated Request
+    API->>Data: CRUD Operation
+    API->>Stream: Emit Event
+    Stream->>Data: Persist Unified Event
+```
+
+---
+
+# Core Design Principles
+
+1. **Tenant-first architecture**
+2. **Strict module separation**
+3. **Reactive edge + streaming core**
+4. **Cursor-based pagination**
+5. **Tool-agnostic event normalization**
+6. **Extensible processors and hooks**
+7. **Shared contract spine**
+
+---
+
+# How Everything Fits Together
+
+```mermaid
+flowchart LR
+    Frontend
+    Gateway
+    Auth
+    API
+    Management
+    Data
+    Stream
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    API --> Data
+    API --> Stream
+    Stream --> Data
+    Management --> Data
+    Management --> Stream
+```
+
+The repository forms:
+
+- 🔐 Identity & trust layer (Authorization)
+- 🌐 Edge & routing layer (Gateway)
+- 🧠 Application API layer (API Core)
+- 🗄 Data persistence layer (Mongo)
+- 🔄 Event processing layer (Kafka)
+- ⚙ Operational control plane (Management)
+- 💬 UI & AI interaction layer (Frontend Core)
+
+---
+
+# Conclusion
+
+The **`openframe-oss-lib`** repository is the complete modular backbone of OpenFrame’s open-source MSP platform.
+
+It delivers:
+
+- Multi-tenant security  
+- Unified API contracts  
+- Reactive gateway & API  
+- Scalable Mongo persistence  
+- Event-driven stream processing  
+- Distributed operational control  
+- Embeddable AI-powered UI  
+
+Together, these modules form a production-grade, extensible, and tenant-safe platform for modern MSP automation.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-lib-contracts/api-lib-contracts.md b/docs/reference/architecture/api-lib-contracts/api-lib-contracts.md
new file mode 100644
index 000000000..fa2f21a75
--- /dev/null
+++ b/docs/reference/architecture/api-lib-contracts/api-lib-contracts.md
@@ -0,0 +1,455 @@
+# Api Lib Contracts
+
+## Overview
+
+Api Lib Contracts is the shared contract module for the OpenFrame backend. It defines:
+
+- Data Transfer Objects (DTOs) for queries, mutations, filters, and responses
+- Shared pagination primitives (Relay-style connections and cursors)
+- Command input and dispatch contracts
+- Filter criteria models for devices, logs, events, tools, scripts, and organizations
+- Cross-layer mappers (e.g., OrganizationMapper)
+
+This module contains **no transport logic** (no controllers, no GraphQL resolvers, no persistence). Instead, it acts as the stable contract layer between:
+
+- HTTP + GraphQL services
+- Management and stream-processing services
+- Mongo data models and repositories
+- Frontend clients
+
+By centralizing contracts here, OpenFrame ensures type consistency and reduces duplication across services.
+
+---
+
+## Architectural Role in the System
+
+```mermaid
+flowchart LR
+    Frontend["Frontend UI and Chat"] -->|"GraphQL / REST"| ApiService["API Service Core"]
+    ApiService -->|"Uses DTOs"| Contracts["Api Lib Contracts"]
+    Contracts -->|"Maps to"| DataModels["Mongo Data Models"]
+    ApiService -->|"Queries"| DataModels
+    Stream["Stream Processing Kafka"] -->|"Publishes Events"| DataModels
+    Gateway["Gateway Service Core"] -->|"Secured Requests"| ApiService
+    Auth["Authorization Service Core"] -->|"JWT / Tenant Context"| ApiService
+```
+
+### Key Responsibilities
+
+1. **Defines API boundaries** (inputs and outputs).
+2. **Decouples transport from persistence**.
+3. **Enforces validation constraints** using Jakarta Validation.
+4. **Implements Relay-style pagination primitives**.
+5. **Provides shared mapping utilities**.
+
+---
+
+# Core Contract Categories
+
+## 1. Generic Query & Pagination Contracts
+
+### CountedGenericQueryResult
+
+`CountedGenericQueryResult<T>` extends a generic query result and adds:
+
+- `filteredCount` – total number of items after filters are applied
+
+This is typically used in filtered list endpoints where:
+
+- The UI needs total counts
+- Filtering and pagination occur simultaneously
+
+### Relay Pagination Support
+
+#### ConnectionArgs
+
+Encapsulates forward and backward pagination arguments:
+
+- `first` + `after`
+- `last` + `before`
+
+Validation constraints:
+
+- Minimum: 1
+- Maximum: 100
+
+#### CursorCodec
+
+Utility for encoding and decoding opaque cursors.
+
+```text
+Raw cursor (e.g. "timestamp_eventId")
+    ↓ Base64 encode
+Opaque cursor returned to client
+    ↓ Base64 decode
+Raw internal cursor
+```
+
+This ensures:
+
+- Internal identifiers remain hidden
+- Pagination logic can evolve without breaking clients
+
+#### MutationDeleteInput
+
+Standard delete input wrapper:
+
+- `id` (required)
+
+Used for GraphQL mutation patterns requiring explicit input objects.
+
+---
+
+## 2. Device Filtering Contracts
+
+### DeviceFilterCriteria
+
+Defines server-side filtering logic:
+
+- Device statuses
+- Device types
+- OS types
+- Organization IDs
+- Tag key/value filtering
+
+### DeviceFilterOption & TagFilterOption
+
+Used for UI filter dropdowns:
+
+- `value` / `label`
+- `count`
+
+### DeviceFilters
+
+Aggregated filter response model containing:
+
+- Status options
+- Device type options
+- OS type options
+- Organization options
+- Tag keys
+- `filteredCount`
+
+```mermaid
+flowchart TD
+    Client["Client Filters"] --> Criteria["DeviceFilterCriteria"]
+    Criteria --> Service["Service Layer"]
+    Service --> Repo["Mongo Repository"]
+    Repo --> Results["Filtered Devices"]
+    Results --> Filters["DeviceFilters Response"]
+```
+
+---
+
+## 3. Audit & Event Filtering Contracts
+
+### LogFilterCriteria
+
+Supports advanced audit filtering:
+
+- Date range
+- Event types
+- Tool types
+- Severities
+- Organization IDs
+- Device ID
+
+### LogFilters
+
+Provides UI-ready filter options:
+
+- Tool types
+- Event types
+- Severities
+- Organization dropdown options
+
+### EventFilterCriteria & EventFilters
+
+Used for querying core event documents:
+
+- User IDs
+- Event types
+- Date ranges
+
+These contracts map closely to Mongo query filters in the data layer.
+
+---
+
+## 4. Command Execution Contracts
+
+### RunCommandInput
+
+GraphQL input for dispatching ad-hoc commands to agents:
+
+- `machineId`
+- `command`
+- `shell`
+- `privilegeLevel`
+- `timeoutSeconds`
+
+Validation ensures:
+
+- Required fields are present
+- Timeout is positive
+
+### CommandDispatchResponse
+
+Returns:
+
+- `executionId`
+
+### CancelExecutionInput & CancelDispatchResponse
+
+Used to cancel agent executions.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant ApiService as "API Service"
+    participant Agent
+
+    Client->>ApiService: RunCommandInput
+    ApiService->>Agent: Dispatch command
+    Agent-->>ApiService: executionId
+    ApiService-->>Client: CommandDispatchResponse
+```
+
+---
+
+## 5. Knowledge Base Contracts
+
+### CreateArticleCommand
+
+Defines article creation fields:
+
+- Name, content, summary
+- Parent hierarchy
+- Status
+- Tag assignments
+- Organization / device / ticket links
+
+### UpdateArticleCommand
+
+Partial update for article metadata and content.
+
+### KnowledgeBaseFilterCriteria
+
+Filtering by:
+
+- Parent
+- Type
+- Tags
+- Statuses
+
+### KnowledgeBaseAttachmentUpload
+
+Returns:
+
+- Attachment metadata
+- Pre-signed upload URL
+
+---
+
+## 6. Script Management Contracts
+
+### CreateScriptInput
+
+Defines script creation fields:
+
+- Name
+- Shell
+- Script body
+- Supported platforms
+- Default timeout
+- Default arguments
+- Environment variables
+
+### ScriptEnvVarInput
+
+Symmetric DTO used for:
+
+- Input
+- Output
+
+Contains:
+
+- Name
+- Value
+- `secret` flag
+
+### ScriptFilterInput
+
+Supports filtering by:
+
+- Shells
+- Statuses
+- Platforms
+- Tag
+
+### UpdateScriptInput
+
+Implements full-replacement semantics (PUT-style):
+
+- All fields must be provided
+- Null clears optional fields
+
+### ScriptResponse
+
+API-facing representation:
+
+- Omits tenantId
+- Serializes enums as names
+- Includes lifecycle metadata
+
+---
+
+## 7. Organization Contracts & Mapping
+
+### OrganizationResponse
+
+Shared response model for both GraphQL and REST.
+
+Contains:
+
+- Business metadata
+- Financial metadata
+- Contract dates
+- Contact information
+- Status and lifecycle fields
+
+### OrganizationList
+
+Wrapper for returning multiple organizations.
+
+### OrganizationFilterOptions
+
+Internal filtering metadata:
+
+- Category
+- Employee range
+- Contract status
+
+### OrganizationMapper
+
+A Spring component responsible for:
+
+- Mapping create requests to entities
+- Performing partial updates
+- Converting entities to OrganizationResponse
+- Mapping nested contact information
+
+```mermaid
+flowchart TD
+    Request["Create / Update Request"] --> Mapper["OrganizationMapper"]
+    Mapper --> Entity["Organization Entity"]
+    Entity --> Mapper
+    Mapper --> Response["OrganizationResponse"]
+```
+
+Key design decisions:
+
+- `organizationId` is generated as UUID
+- Immutable once created
+- Partial updates ignore null fields
+- Mailing address may mirror physical address
+
+---
+
+## 8. Tool Filtering Contracts
+
+### ToolFilterCriteria
+
+Server-side filtering fields:
+
+- Enabled
+- Type
+- Category
+- Platform category
+
+### ToolFilters
+
+UI-oriented aggregated filter options.
+
+### ToolList
+
+Wrapper returning:
+
+- List of integrated tool entities
+
+---
+
+# Design Principles
+
+## 1. Separation of Concerns
+
+- DTOs contain no persistence logic
+- No repository or controller code
+- No service orchestration
+
+This ensures portability across services.
+
+## 2. Validation at the Boundary
+
+Jakarta validation annotations enforce:
+
+- Required fields
+- Numeric constraints
+- Input integrity
+
+Transport layers trigger validation automatically.
+
+## 3. Tenant Safety
+
+Certain fields (e.g., tenantId) are intentionally excluded from API contracts.
+
+Tenant context is derived from authentication layers, not from client input.
+
+## 4. Opaque Pagination
+
+CursorCodec ensures:
+
+- Internal identifiers remain hidden
+- Backward-compatible pagination evolution
+
+---
+
+# How Api Lib Contracts Fits Into OpenFrame
+
+```mermaid
+flowchart TD
+    Contracts["Api Lib Contracts"]
+    Api["API Service Core"]
+    Auth["Authorization Service"]
+    Data["Mongo Data Layer"]
+    Gateway["Gateway Service"]
+    Frontend["Frontend UI"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> Api
+    Api --> Contracts
+    Api --> Data
+```
+
+Api Lib Contracts is the **contract spine** of the backend. It:
+
+- Standardizes API inputs and outputs
+- Ensures consistent filter and pagination behavior
+- Enables both REST and GraphQL to share models
+- Decouples transport, business logic, and persistence
+
+Without this module, every service would redefine overlapping DTOs, increasing coupling and breaking consistency.
+
+---
+
+# Summary
+
+Api Lib Contracts is a foundational module that:
+
+- Defines all core API DTOs
+- Implements filter and pagination primitives
+- Supports device, event, audit, organization, script, tool, and knowledge base domains
+- Provides shared mapping utilities
+- Enforces validation at API boundaries
+
+It is intentionally lightweight but architecturally critical — serving as the shared language between OpenFrame services and clients.
\ No newline at end of file
diff --git a/docs/reference/architecture/api-service-core-http-and-graphql/api-service-core-http-and-graphql.md b/docs/reference/architecture/api-service-core-http-and-graphql/api-service-core-http-and-graphql.md
new file mode 100644
index 000000000..e1689929d
--- /dev/null
+++ b/docs/reference/architecture/api-service-core-http-and-graphql/api-service-core-http-and-graphql.md
@@ -0,0 +1,358 @@
+# Api Service Core Http And Graphql
+
+## Overview
+
+The **Api Service Core Http And Graphql** module is the central application layer of the OpenFrame backend. It exposes:
+
+- REST endpoints for operational and administrative APIs
+- GraphQL APIs (queries, mutations, Relay-style node resolution)
+- Security integration as an OAuth2 Resource Server
+- DataLoader-based batching to prevent N+1 query problems
+- DTOs and connection models aligned with the `api-lib-contracts` module
+
+This module acts as the orchestration layer between:
+
+- Gateway (edge routing and JWT handling)
+- Authorization Service (OAuth2 / OIDC)
+- Mongo repositories and domain services
+- Stream-processing and external integrations
+- Frontend (GraphQL + REST consumers)
+
+It does **not** contain core domain persistence logic. Instead, it delegates to services and repositories defined in other modules.
+
+---
+
+## High-Level Architecture
+
+```mermaid
+flowchart TD
+    Client["Frontend / API Client"] --> Gateway["Gateway Service Core"]
+    Gateway --> ApiService["Api Service Core Http And Graphql"]
+
+    ApiService --> Controllers["REST Controllers"]
+    ApiService --> GraphQL["GraphQL DataFetchers"]
+
+    Controllers --> Services["Application Services"]
+    GraphQL --> Services
+
+    Services --> Mongo["Mongo Repositories"]
+    Services --> Stream["Kafka / Stream Processing"]
+
+    ApiService --> Authz["Authorization Service Core"]
+```
+
+### Responsibilities
+
+| Layer | Responsibility |
+|--------|----------------|
+| REST Controllers | HTTP endpoints for operational APIs |
+| GraphQL DataFetchers | GraphQL queries & mutations via DGS |
+| DataLoaders | Batch loading & N+1 prevention |
+| DTOs | GraphQL and REST data contracts |
+| SecurityConfig | OAuth2 Resource Server integration |
+| Services | Business orchestration (delegated to domain services) |
+
+---
+
+## Security Architecture
+
+Security is intentionally minimal in this module.
+
+### Key Principle
+
+The **Gateway Service Core** performs:
+
+- JWT validation
+- Cookie extraction
+- Authorization header injection
+- PermitAll path filtering
+
+The Api Service Core Http And Graphql module:
+
+- Acts as an OAuth2 Resource Server
+- Supports `@AuthenticationPrincipal` resolution
+- Caches JWT decoders by issuer
+
+### Security Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant ApiService
+    participant AuthServer
+
+    Client->>Gateway: HTTP Request
+    Gateway->>AuthServer: Validate JWT
+    AuthServer-->>Gateway: Token valid
+    Gateway->>ApiService: Forward request with Authorization header
+    ApiService->>ApiService: Resolve AuthPrincipal
+    ApiService-->>Client: JSON / GraphQL response
+```
+
+### Core Security Components
+
+- `SecurityConfig` – Configures OAuth2 Resource Server and issuer-based JWT resolution
+- `AuthenticationConfig` – Registers `AuthPrincipalArgumentResolver`
+- `ApiApplicationConfig` – Provides `PasswordEncoder`
+- Caffeine cache for `JwtAuthenticationProvider`
+
+---
+
+## REST Layer
+
+The REST controllers provide operational APIs and administrative endpoints.
+
+### Key Controllers
+
+| Controller | Responsibility |
+|------------|----------------|
+| `HealthController` | Health probe endpoint |
+| `MeController` | Authenticated user info |
+| `ApiKeyController` | API key lifecycle |
+| `OrganizationController` | Organization mutations |
+| `UserController` | User management |
+| `InvitationController` | User invitation lifecycle |
+| `SSOConfigController` | SSO provider configuration |
+| `AgentRegistrationSecretController` | Agent bootstrap secrets |
+| `ForceAgentController` | Forced tool / agent operations |
+| `ReleaseVersionController` | Current release metadata |
+| `OpenFrameClientConfigurationController` | Client config exposure |
+
+### REST Processing Flow
+
+```mermaid
+flowchart LR
+    Request["HTTP Request"] --> Controller["@RestController"]
+    Controller --> Service["Application Service"]
+    Service --> Repository["Mongo Repository"]
+    Repository --> Service
+    Service --> Controller
+    Controller --> Response["HTTP Response"]
+```
+
+Controllers are thin and delegate logic to service classes.
+
+---
+
+## GraphQL Layer (DGS)
+
+The GraphQL API is implemented using Netflix DGS.
+
+### Categories of DataFetchers
+
+| Category | Examples |
+|----------|----------|
+| Core Entities | DeviceDataFetcher, OrganizationDataFetcher |
+| Events & Logs | EventDataFetcher, LogDataFetcher |
+| Knowledge Base | KnowledgeBaseDataFetcher |
+| Assignments | AssignmentDataFetcher |
+| Notifications | NotificationDataFetcher |
+| Tools & Scripts | ToolsDataFetcher, ScriptDataFetcher |
+| Relay Node | NodeDataFetcher |
+
+### GraphQL Query Flow
+
+```mermaid
+flowchart TD
+    Query["GraphQL Query"] --> DataFetcher["@DgsQuery / @DgsMutation"]
+    DataFetcher --> Mapper["GraphQL Mapper"]
+    Mapper --> Service["Domain Service"]
+    Service --> Repository["Mongo Repository"]
+    Repository --> Service
+    Service --> Mapper
+    Mapper --> Connection["Connection / Edge DTO"]
+```
+
+---
+
+## Relay and Global ID Model
+
+This module implements Relay-style node resolution.
+
+### Global ID Handling
+
+- IDs are encoded using `Relay.toGlobalId(type, id)`
+- Resolved using `Relay.fromGlobalId(id)`
+- Centralized resolution via `NodeDataFetcher`
+
+### Node Type Resolution
+
+```mermaid
+flowchart TD
+    NodeQuery["node(id)"] --> NodeFetcher["NodeDataFetcher"]
+    NodeFetcher --> TypeSwitch["NodeTypeResolver"]
+    TypeSwitch --> Machine["Machine"]
+    TypeSwitch --> Organization["Organization"]
+    TypeSwitch --> Event["Event"]
+    TypeSwitch --> Ticket["Ticket"]
+    TypeSwitch --> KnowledgeBaseItem["KnowledgeBaseItem"]
+```
+
+This ensures consistent object lookup across all GraphQL types.
+
+---
+
+## Pagination Model
+
+The module implements cursor-based pagination.
+
+### Core DTOs
+
+- `GenericEdge<T>`
+- `CountedGenericConnection<T>`
+- `ConnectionArgs`
+- `CursorPaginationCriteria`
+
+### Pagination Flow
+
+```mermaid
+flowchart LR
+    ClientArgs["first / after"] --> ConnectionArgs
+    ConnectionArgs --> CursorCriteria
+    CursorCriteria --> ServiceQuery
+    ServiceQuery --> QueryResult
+    QueryResult --> ConnectionDTO
+```
+
+This model provides:
+
+- Forward and backward pagination
+- Filtered count tracking
+- Stable cursors
+
+---
+
+## DataLoader Layer
+
+To prevent N+1 query issues in GraphQL, the module defines multiple DataLoaders.
+
+### Examples
+
+- `MachineDataLoader`
+- `OrganizationDataLoader`
+- `UserDataLoader`
+- `KnowledgeBaseAttachmentDataLoader`
+- `TagDataLoader`
+- `TicketDataLoader`
+
+### N+1 Prevention Pattern
+
+```mermaid
+flowchart TD
+    GraphQLField["Resolve field"] --> DataLoader
+    DataLoader --> BatchLoad["Batch Repository Query"]
+    BatchLoad --> ResultMap
+    ResultMap --> Response
+```
+
+Each DataLoader:
+
+- Accepts a list of IDs
+- Performs a single batched query
+- Returns results in original order
+
+---
+
+## Knowledge Base Subsystem
+
+The Knowledge Base GraphQL implementation is one of the most complex subsystems.
+
+Capabilities include:
+
+- Folder and article tree structure
+- Tag assignment
+- Assignment to devices / tickets / organizations
+- Archive and publish lifecycle
+- Temporary attachment upload
+- Permanent attachment linking
+
+It demonstrates:
+
+- Use of Relay global IDs
+- DataLoader integration
+- Mutation error wrapping
+- Author resolution via `UserDataLoader`
+
+---
+
+## Notification Subsystem
+
+The Notification GraphQL implementation supports:
+
+- Cursor-based notification listing
+- Category-based unread counters
+- Actor-type resolution (USER vs AGENT)
+- Bulk mark-as-read and delete operations
+
+Security is enforced using method-level authorization:
+
+- `@PreAuthorize("hasAnyAuthority('ADMIN', 'AGENT')")`
+
+Recipient resolution depends on `AuthPrincipal` and JWT claims.
+
+---
+
+## SSO Configuration Management
+
+The SSOConfigService manages:
+
+- Provider enable/disable
+- Client secret encryption
+- Domain validation
+- Microsoft-specific tenant validation
+- Post-save processing hooks
+
+The service integrates with:
+
+- EncryptionService
+- SSOConfigRepository
+- SSOConfigProcessor
+
+This allows OSS deployments to override behavior via conditional beans.
+
+---
+
+## Extensibility Model
+
+Several extension points exist:
+
+| Extension Type | Mechanism |
+|----------------|-----------|
+| Post-processing hooks | `@ConditionalOnMissingBean` processors |
+| SSO provider strategies | Strategy pattern |
+| User enrichment | `UserProcessor` |
+| Agent secret lifecycle | `AgentRegistrationSecretProcessor` |
+
+This enables SaaS or enterprise editions to inject custom behavior.
+
+---
+
+## Relationship to Other Modules
+
+The Api Service Core Http And Graphql module depends on:
+
+- Authorization Service Core (JWT issuance and OAuth2 flows)
+- Gateway Service Core (edge authentication and routing)
+- Data Models and Repositories Mongo (persistence layer)
+- Stream Processing Kafka (event ingestion and enrichment)
+- Api Lib Contracts (shared DTOs)
+
+It serves as the primary application API surface consumed by the Frontend Core UI and Chat module.
+
+---
+
+## Summary
+
+The **Api Service Core Http And Graphql** module is the application-layer backbone of OpenFrame.
+
+It provides:
+
+- REST APIs for operational management
+- A fully Relay-compliant GraphQL API
+- Cursor-based pagination
+- DataLoader batching
+- Minimal but robust OAuth2 Resource Server security
+- Extensible processor-based hooks
+
+It sits between the Gateway and domain services, translating transport-layer requests into structured domain interactions while maintaining consistent API contracts across the platform.
diff --git a/docs/reference/architecture/authorization-service-core/authorization-service-core.md b/docs/reference/architecture/authorization-service-core/authorization-service-core.md
new file mode 100644
index 000000000..e1aca4036
--- /dev/null
+++ b/docs/reference/architecture/authorization-service-core/authorization-service-core.md
@@ -0,0 +1,380 @@
+# Authorization Service Core
+
+The Authorization Service Core module is the security backbone of OpenFrame. It implements a **multi-tenant OAuth2 Authorization Server**, supports **OIDC-based Single Sign-On (SSO)** (Google and Microsoft), and manages **tenant-scoped authentication, token issuance, and user lifecycle events**.
+
+This module is responsible for:
+
+- Acting as an OAuth2 / OpenID Connect Authorization Server
+- Issuing JWT access and refresh tokens
+- Managing tenant-aware signing keys
+- Supporting dynamic OIDC client registration per tenant
+- Handling SSO onboarding and invitation flows
+- Managing password resets and user authentication
+- Persisting OAuth2 authorizations in MongoDB
+
+It integrates tightly with the data layer (MongoDB repositories), the Gateway Service Core (JWT validation), and the API Service Core (resource protection).
+
+---
+
+## High-Level Architecture
+
+```mermaid
+flowchart LR
+    Browser["User Browser"] -->|"Login / OAuth2"| AuthServer["Authorization Service Core"]
+    AuthServer -->|"JWT Access Token"| Gateway["Gateway Service Core"]
+    Gateway -->|"Validated Request"| ApiService["API Service Core"]
+
+    AuthServer -->|"Persist Authorizations"| Mongo[("MongoDB")]
+    AuthServer -->|"Load Users / Tenants"| DataLayer["Data Models & Repositories"]
+```
+
+### Responsibilities by Boundary
+
+| Layer | Responsibility |
+|--------|---------------|
+| Authorization Server | OAuth2, OIDC, JWT issuance |
+| Security Layer | Form login, SSO login, JWT validation |
+| Tenant Context | Multi-tenant request isolation |
+| Key Management | Per-tenant RSA signing keys |
+| Persistence | Mongo-based token + client storage |
+
+---
+
+# Core Architectural Concepts
+
+## 1. Multi-Tenant Isolation
+
+Each request is bound to a **Tenant Context** stored in a `ThreadLocal`.
+
+```mermaid
+flowchart TD
+    Request["Incoming HTTP Request"] --> Filter["TenantContextFilter"]
+    Filter --> Context["TenantContext (ThreadLocal)"]
+    Context --> AuthFlow["Authentication / Token Flow"]
+    AuthFlow --> Clear["TenantContext.clear()"]
+```
+
+### Key Components
+
+- `TenantContext` – Thread-local storage of current tenant ID
+- `TenantContextFilter` – Extracts tenant ID from:
+  - URL path (e.g. `/sas/{tenant}/oauth2/...`)
+  - Query parameter `tenant`
+  - Existing HTTP session
+- Session switching logic for SSO onboarding flows
+
+This ensures:
+
+- Tokens are tenant-scoped
+- Keys are tenant-scoped
+- Users are tenant-scoped
+
+---
+
+## 2. OAuth2 Authorization Server Configuration
+
+The module uses Spring Authorization Server via `AuthorizationServerConfig`.
+
+### Capabilities
+
+- Multiple issuers allowed (multi-tenant support)
+- OIDC enabled
+- JWT resource server configuration
+- Custom authentication entry point
+- Tenant-aware JWK source
+
+```mermaid
+flowchart TD
+    Config["AuthorizationServerConfig"] --> SecurityChain["SecurityFilterChain (Order 1)"]
+    SecurityChain --> OAuth2["OAuth2AuthorizationServerConfigurer"]
+    OAuth2 --> OIDC["OIDC Enabled"]
+    OAuth2 --> JWT["JWT Resource Server"]
+    Config --> JWKSource["Tenant-aware JWKSource"]
+    Config --> TokenCustomizer["JWT Token Customizer"]
+```
+
+---
+
+## 3. Tenant-Aware JWT Signing
+
+Each tenant has its own RSA key pair.
+
+### Flow
+
+```mermaid
+flowchart TD
+    TokenRequest["Access Token Request"] --> KeyService["TenantKeyService"]
+    KeyService --> Repo["TenantKeyRepository"]
+    KeyService --> Generator["RsaAuthenticationKeyPairGenerator"]
+    KeyService --> Encrypt["EncryptionService"]
+    KeyService --> JWT["RSAKey (JWK)"]
+    JWT --> Encoder["NimbusJwtEncoder"]
+```
+
+### Key Management Components
+
+- `TenantKeyService`
+  - Retrieves active key
+  - Generates key if missing
+  - Encrypts private key before storage
+- `RsaAuthenticationKeyPairGenerator`
+  - Generates RSA key pair
+  - Assigns unique `kid`
+- `PemUtil`
+  - Converts RSA keys to/from PEM
+
+This guarantees:
+
+- Token isolation between tenants
+- Independent key rotation
+- JWK endpoint serves tenant-specific key
+
+---
+
+## 4. JWT Customization
+
+Access tokens are enriched via `OAuth2TokenCustomizer`.
+
+### Custom Claims Added
+
+- `tenant_id`
+- `userId`
+- `roles`
+
+Role logic:
+
+- `OWNER` automatically implies `ADMIN`
+- Roles are emitted as strings
+
+```mermaid
+flowchart TD
+    Principal["Authenticated User"] --> Customizer["OAuth2TokenCustomizer"]
+    Customizer --> Claims["Add Claims"]
+    Claims --> JWT["Signed JWT"]
+```
+
+---
+
+# Security Configuration
+
+The `SecurityConfig` handles all **non-authorization-server endpoints**.
+
+## Responsibilities
+
+- Form login
+- OAuth2 login (SSO)
+- Microsoft issuer validation
+- Auto-provisioning SSO users
+- Authentication failure handling
+
+```mermaid
+flowchart TD
+    User["User"] -->|"/login"| FormLogin["Form Login"]
+    User -->|"/oauth2/authorization/{provider}"| OAuthLogin["OIDC Login"]
+
+    OAuthLogin --> DecoderFactory["Microsoft-Aware JWT Decoder"]
+    OAuthLogin --> OidcUserService["Custom OIDC User Service"]
+    OidcUserService --> AutoProvision["Auto Provisioning"]
+    AutoProvision --> UserService["UserService"]
+```
+
+---
+
+# Single Sign-On (SSO)
+
+## Supported Providers
+
+- Google
+- Microsoft
+
+Provider configuration includes:
+
+- Tenant-specific credentials
+- Default system-level credentials
+- Dynamic client registration
+
+### Dynamic Client Registration
+
+`DynamicClientRegistrationRepository` resolves clients at runtime using:
+
+- Current tenant
+- Session fallback
+
+```mermaid
+flowchart TD
+    OAuthFlow["OAuth2 Login Flow"] --> Repo["DynamicClientRegistrationRepository"]
+    Repo --> Context["TenantContext"]
+    Repo --> DynamicService["DynamicClientRegistrationService"]
+    DynamicService --> Client["ClientRegistration"]
+```
+
+---
+
+# SSO Flows
+
+## 1. Tenant Registration via SSO
+
+Handled by:
+
+- `TenantRegistrationController`
+- `TenantRegSsoHandler`
+
+Flow:
+
+```mermaid
+flowchart TD
+    User --> Init["/oauth/register/sso"]
+    Init --> Cookie["Set SSO Registration Cookie"]
+    Cookie --> Provider["Redirect to Google/Microsoft"]
+    Provider --> Callback["OIDC Callback"]
+    Callback --> Handler["TenantRegSsoHandler"]
+    Handler --> TenantService["TenantRegistrationService"]
+    TenantService --> Redirect["Redirect to Tenant OAuth Flow"]
+```
+
+---
+
+## 2. Invitation Acceptance via SSO
+
+Handled by:
+
+- `InvitationRegistrationController`
+- `InviteSsoHandler`
+
+Flow:
+
+```mermaid
+flowchart TD
+    User --> Accept["/invitations/accept/sso"]
+    Accept --> Cookie["Set Invite Cookie"]
+    Cookie --> Provider["Redirect to Provider"]
+    Provider --> Callback["OIDC Callback"]
+    Callback --> InviteHandler["InviteSsoHandler"]
+    InviteHandler --> InviteService["InvitationRegistrationService"]
+```
+
+---
+
+# Password Reset Flow
+
+Implemented via `PasswordResetController`.
+
+```mermaid
+flowchart TD
+    User --> Request["POST /password-reset/request"]
+    Request --> Service["PasswordResetService"]
+    Service --> Token["Generate Reset Token"]
+
+    User --> Confirm["POST /password-reset/confirm"]
+    Confirm --> Validate["Validate Token"]
+    Validate --> Update["Update Password"]
+```
+
+Reset tokens are generated using secure random Base64 URL encoding.
+
+---
+
+# Mongo-Based Authorization Persistence
+
+OAuth2 authorizations are stored in MongoDB.
+
+## Components
+
+- `MongoAuthorizationService`
+- `MongoAuthorizationMapper`
+- `MongoRegisteredClientRepository`
+
+```mermaid
+flowchart TD
+    AuthServer["OAuth2Authorization"] --> Mapper["MongoAuthorizationMapper"]
+    Mapper --> Entity["MongoOAuth2Authorization"]
+    Entity --> Repo["MongoOAuth2AuthorizationRepository"]
+    Repo --> Mongo[("MongoDB")]
+```
+
+### Stored Artifacts
+
+- Authorization codes
+- Access tokens
+- Refresh tokens
+- PKCE parameters
+- Client settings
+
+PKCE parameters are preserved across serialization/deserialization.
+
+---
+
+# Authentication Success Handling
+
+`AuthSuccessHandler` performs:
+
+- Update `lastLogin`
+- Mark email verified when appropriate
+- Delegate to SSO flow continuation handler
+
+This ensures login success does not disrupt SSO onboarding flows.
+
+---
+
+# Default Extension Points
+
+The module provides default no-op processors:
+
+- `DefaultRegistrationProcessor`
+- `DefaultUserDeactivationProcessor`
+- `DefaultUserEmailVerifiedProcessor`
+
+These allow customization without modifying core logic.
+
+---
+
+# How It Fits Into OpenFrame
+
+```mermaid
+flowchart LR
+    Frontend["Frontend"] --> Gateway
+    Gateway -->|"Bearer Token"| Api
+    Gateway -->|"JWT Validation"| Authorization
+    Authorization -->|"Token Issuance"| Gateway
+
+    Authorization --> Data
+
+    subgraph Services["OpenFrame Services"]
+        Authorization["Authorization Service Core"]
+        Api["API Service Core"]
+        Gateway["Gateway Service Core"]
+        Data["Mongo Data Layer"]
+    end
+```
+
+### Summary of Role
+
+The Authorization Service Core:
+
+- Issues tenant-scoped JWTs
+- Validates and manages OAuth2 flows
+- Handles SSO onboarding and invitations
+- Provides secure multi-tenant isolation
+- Supplies JWK endpoints for downstream verification
+- Persists token state in MongoDB
+
+It is the **identity and trust authority** for the entire OpenFrame platform.
+
+---
+
+# Key Design Principles
+
+1. Tenant-first architecture
+2. Stateless JWT with tenant-aware signing
+3. Secure default flows
+4. Extensible processors
+5. Provider-aware OIDC validation
+6. PKCE-first OAuth2 implementation
+
+---
+
+# Conclusion
+
+The Authorization Service Core is a production-grade, multi-tenant identity provider tailored for OpenFrame. It integrates OAuth2, OIDC, tenant isolation, Mongo persistence, and extensible SSO flows into a cohesive authentication backbone.
+
+All other services in the platform rely on it for trust, token validation, and identity enforcement.
\ No newline at end of file
diff --git a/docs/reference/architecture/data-models-and-repositories-mongo/data-models-and-repositories-mongo.md b/docs/reference/architecture/data-models-and-repositories-mongo/data-models-and-repositories-mongo.md
new file mode 100644
index 000000000..5db954810
--- /dev/null
+++ b/docs/reference/architecture/data-models-and-repositories-mongo/data-models-and-repositories-mongo.md
@@ -0,0 +1,441 @@
+# Data Models And Repositories Mongo
+
+## Overview
+
+The **Data Models And Repositories Mongo** module provides the MongoDB-backed persistence layer for the OpenFrame platform. It defines:
+
+- Core MongoDB document models (users, tickets, devices, organizations, events, notifications, etc.)
+- Query filter objects for advanced searching
+- Base repository abstractions (technology-agnostic)
+- Reactive and synchronous repository implementations
+- Custom MongoTemplate-based query logic with cursor pagination
+- Multi-tenant support via tenant-aware scoping
+
+This module is the foundation for higher-level modules such as:
+
+- API Service Core HTTP And GraphQL  
+- Authorization Service Core  
+- Management Service Core  
+- Gateway Service Core (indirectly via upstream services)
+
+It centralizes all MongoDB persistence logic to keep business services storage-agnostic.
+
+---
+
+## High-Level Architecture
+
+```mermaid
+flowchart TD
+    Controllers["API / GraphQL / Auth Controllers"] --> Services["Application Services"]
+    Services --> Repositories["Mongo Repositories"]
+    Repositories --> CustomImpl["Custom Repository Implementations"]
+    Repositories --> ReactiveImpl["Reactive Repositories"]
+    CustomImpl --> MongoTemplate["MongoTemplate"]
+    ReactiveImpl --> ReactiveMongo["ReactiveMongoRepository"]
+    MongoTemplate --> MongoDB[("MongoDB")]
+    ReactiveMongo --> MongoDB
+```
+
+### Responsibilities by Layer
+
+- **Document Models** → Define MongoDB collections and indexes  
+- **Query Filters** → Encapsulate search and filtering logic  
+- **Base Repositories** → Provide technology-agnostic contracts  
+- **Reactive Repositories** → Used by reactive services (e.g., auth flows)  
+- **Custom Repositories** → Advanced queries, aggregation, cursor pagination  
+- **Tenant Provider** → Injects tenant context into queries
+
+---
+
+## Multi-Tenancy Model
+
+Most domain documents implement `TenantScoped`, containing a `tenantId` field indexed for isolation.
+
+```mermaid
+flowchart LR
+    Request["Incoming Request"] --> TenantContext["TenantIdProvider"]
+    TenantContext --> Repository["Tenant-Scoped Repository"]
+    Repository --> Query["Mongo Query with tenantId"]
+    Query --> MongoDB[("MongoDB")]
+```
+
+### Tenant ID Resolution
+
+`DefaultTenantIdProvider`:
+
+- Reads tenant ID from `TENANT_ID` environment variable
+- Defaults to `oss`
+- Can be overridden by custom `TenantIdProvider` bean
+
+This enables:
+
+- SaaS multi-tenant isolation  
+- OSS single-tenant mode  
+- Authorization server tenant-aware domain resolution
+
+---
+
+# Core Document Models
+
+## User and AuthUser
+
+### User
+Collection: `users`
+
+Fields:
+- `email` (indexed, normalized to lowercase)
+- `roles`
+- `status`
+- `emailVerified`
+- `createdAt`, `updatedAt`
+- `tenantId`
+
+### AuthUser
+Extends `User`.
+Collection: `users` (same inheritance hierarchy).
+
+Additional fields:
+- `passwordHash`
+- `loginProvider` (LOCAL, GOOGLE, etc.)
+- `externalUserId`
+- `lastLogin`
+- `imageUrl` (SSO profile cache)
+
+Compound index:
+
+```text
+{ tenantId: 1, email: 1 } (unique)
+```
+
+Used heavily by:
+- Authorization Service Core
+- API Service Core
+
+---
+
+## Organization
+
+Collection: `organizations`
+
+Key features:
+- Unique `organizationId`
+- Soft deletion (`status` = ACTIVE, ARCHIVED, DELETED)
+- Contract lifecycle tracking
+- Indexed search fields
+
+Business helpers:
+- `isContractActive()`
+- `isArchived()`
+- `isDeleted()`
+
+Custom queries handled by `CustomOrganizationRepositoryImpl`.
+
+---
+
+## Device
+
+Collection: `devices`
+
+Fields include:
+- `machineId`
+- `serialNumber`
+- `status`
+- `type`
+- `lastCheckin`
+
+Indexed on `tenantId`.
+
+Used by:
+- Device controllers
+- Fleet integrations
+- Management schedulers
+
+---
+
+## Ticket
+
+Collection: `tickets`
+
+Compound indexes:
+
+```text
+{ tenantId:1, ticketNumber:1 } (unique)
+{ status:1, order:1 }
+{ statusKind:1 }
+{ statusId:1, order:1 }
+```
+
+Supports:
+- Legacy `status`
+- Lifecycle-based `statusId` and `statusKind`
+- Cursor pagination
+- Aggregation metrics
+- Bulk updates
+
+`CustomTicketRepositoryImpl` provides:
+
+- Cursor-based pagination  
+- Aggregation counts by status  
+- Average resolution time  
+- Bulk status reassignment  
+- Search across title, device, org, assignee
+
+---
+
+## CoreEvent
+
+Collection: `events`
+
+Fields:
+- `type`
+- `payload`
+- `timestamp`
+- `userId`
+- `status`
+
+Used by:
+- Stream Processing Kafka module
+- Activity dashboards
+- Audit queries
+
+`CustomEventRepositoryImpl` supports:
+- Date range filtering
+- Cursor pagination
+- Distinct event types
+- Distinct user IDs
+
+---
+
+## Notification
+
+Collection: `notifications`
+
+Supports:
+- Severity levels
+- Context embedding
+- Created date auto-population
+
+`CustomNotificationRepositoryImpl` provides:
+- Recipient-based pagination
+- Read/unread filtering
+- Cursor-based navigation
+- Status joining with read state
+
+---
+
+# Query Filter Objects
+
+Filter objects encapsulate dynamic search logic.
+
+Examples:
+
+- `EventQueryFilter`
+- `OrganizationQueryFilter`
+- `TicketQueryFilter`
+- `ToolQueryFilter`
+- `UserQueryFilter`
+
+These objects:
+- Avoid controller-level query construction  
+- Enable reusable MongoTemplate queries  
+- Support complex combinations of AND / OR criteria
+
+Example flow:
+
+```mermaid
+flowchart TD
+    GraphQL["GraphQL Input Filter"] --> FilterObject["QueryFilter DTO"]
+    FilterObject --> CustomRepo["Custom Repository"]
+    CustomRepo --> MongoQuery["Mongo Query + Criteria"]
+    MongoQuery --> MongoDB[("MongoDB")]
+```
+
+---
+
+# Repository Architecture
+
+## Base Repository Contracts
+
+Technology-agnostic interfaces:
+
+- `BaseUserRepository`
+- `BaseTenantRepository`
+- `BaseApiKeyRepository`
+- `BaseIntegratedToolRepository`
+
+These abstract return types:
+
+- Blocking (`Optional`, `boolean`, `List`)
+- Reactive (`Mono`, `Flux`)
+
+This enables both reactive and synchronous implementations.
+
+---
+
+## Reactive Repositories
+
+Located under `openframe-data-mongo-reactive`.
+
+Examples:
+- `ReactiveUserRepository`
+- `ReactiveTenantRepository`
+- `ReactiveOAuthClientRepository`
+
+Used primarily by:
+- Authorization Service Core
+- Reactive authentication flows
+
+Built on `ReactiveMongoRepository`.
+
+---
+
+## Synchronous Configuration
+
+Two configurations control repository activation:
+
+- `MongoSyncConfig`
+- `TenantAwareSyncConfig`
+
+Activation is controlled via properties:
+
+```text
+spring.data.mongodb.enabled
+openframe.tenant-isolation.enabled
+```
+
+This allows:
+- Tenant-aware repositories
+- Shared cluster mode
+- Flexible deployment strategies
+
+---
+
+# Custom Repository Implementations
+
+Custom implementations use `MongoTemplate` for advanced querying.
+
+Common capabilities:
+
+- Cursor-based pagination using `_id`
+- Multi-field sorting
+- Compound search with `$or` and `$and`
+- Aggregation pipelines
+- Distinct field retrieval
+- Bulk updates
+
+## Cursor Pagination Pattern
+
+```mermaid
+flowchart TD
+    Client["Client"] --> QueryBuilder["Build Query"]
+    QueryBuilder --> ApplyCursor["Apply _id comparison"]
+    ApplyCursor --> ApplySort["Apply Sort + Limit"]
+    ApplySort --> Execute["mongoTemplate.find"]
+    Execute --> Page["Result Page"]
+```
+
+Behavior:
+- If sort field is `_id`, compare directly
+- Otherwise:
+  - Compare primary sort field
+  - Tie-break using `_id`
+- Invalid cursor logs warning and returns first page
+
+Implemented in:
+- CustomMachineRepositoryImpl  
+- CustomTicketRepositoryImpl  
+- CustomEventRepositoryImpl  
+- CustomOrganizationRepositoryImpl  
+- CustomScriptRepositoryImpl  
+- CustomNotificationRepositoryImpl  
+- CustomIntegratedToolRepositoryImpl  
+- CustomUserRepositoryImpl
+
+---
+
+# Aggregation and Metrics
+
+Ticket repository provides aggregation-based metrics:
+
+- Count by `status`
+- Count by `statusKind`
+- Count by `statusId`
+- Average resolution time
+
+Uses MongoDB Aggregation Framework.
+
+```mermaid
+flowchart LR
+    Tickets[("tickets collection")] --> Group["$group"]
+    Group --> Project["$project"]
+    Project --> Metrics["Aggregated Metrics"]
+```
+
+---
+
+# Integration with Other Modules
+
+## API Service Core HTTP And GraphQL
+
+Uses:
+- Document models
+- Query filters
+- Custom repositories
+- Pagination utilities
+
+GraphQL resolvers delegate persistence to this module.
+
+## Authorization Service Core
+
+Uses:
+- AuthUser document
+- ReactiveUserRepository
+- ReactiveTenantRepository
+- MongoAuthorizationService
+
+Enables domain-based tenancy and OAuth client storage.
+
+## Management Service Core
+
+Uses:
+- Device
+- Ticket
+- IntegratedTool
+- Script repositories
+
+For schedulers, migrations, and background processing.
+
+## Stream Processing Kafka
+
+Consumes events and writes:
+- CoreEvent documents
+- Enriched activity records
+
+---
+
+# Design Principles
+
+1. Clear separation between domain model and service logic  
+2. Technology-agnostic repository contracts  
+3. Multi-tenant safety by default  
+4. Cursor-based pagination for scalability  
+5. Aggregation-driven metrics  
+6. Index-first design  
+7. Reactive + synchronous support
+
+---
+
+# Summary
+
+The **Data Models And Repositories Mongo** module is the persistence backbone of OpenFrame.
+
+It provides:
+
+- Strongly typed MongoDB documents  
+- Multi-tenant data isolation  
+- Reactive and blocking repository layers  
+- Advanced filtering and pagination  
+- Aggregation-based analytics  
+- Custom query implementations for complex domains
+
+All higher-level services rely on this module for consistent, scalable, and tenant-safe data access.
\ No newline at end of file
diff --git a/docs/reference/architecture/frontend-core-ui-and-chat/frontend-core-ui-and-chat.md b/docs/reference/architecture/frontend-core-ui-and-chat/frontend-core-ui-and-chat.md
new file mode 100644
index 000000000..d23e8d657
--- /dev/null
+++ b/docs/reference/architecture/frontend-core-ui-and-chat/frontend-core-ui-and-chat.md
@@ -0,0 +1,444 @@
+# Frontend Core Ui And Chat
+
+The **Frontend Core Ui And Chat** module provides the reusable UI foundation and real-time AI chat experience for the OpenFrame platform.
+
+It is designed to be:
+
+- ✅ **Embeddable** – works inside Hub, standalone apps, or third-party platforms
+- ✅ **Runtime-driven** – all navigation, identity, and endpoints flow through runtime context
+- ✅ **Transport-agnostic** – supports SSE (Guide mode) and NATS/WebSocket (Mingo mode)
+- ✅ **Design-system aligned** – built entirely on ODS tokens and shared UI primitives
+
+This module powers:
+
+- The floating **"Ask AI"** assistant panel
+- AI-driven conversations (Guide + Mingo modes)
+- Ticket Center
+- Board (Kanban-style) views
+- Notifications Drawer
+- Data Tables and filtering surfaces
+- Navigation and layout primitives
+
+---
+
+## 1. Architectural Overview
+
+At a high level, the module sits on top of platform runtime and backend services while remaining UI-focused and transport-agnostic.
+
+```mermaid
+flowchart LR
+    User["User"] --> UI["Frontend Core Ui And Chat"]
+
+    subgraph ChatLayer["Chat System"]
+        EmbeddableChat["EmbeddableChat"]
+        Composer["ChatComposer"]
+        MessageRow["ChatMessageRow"]
+        DialogHistory["MingoChatHistory"]
+    end
+
+    subgraph FeatureLayer["Feature Surfaces"]
+        TicketCenter["TicketCenter"]
+        Board["Board"]
+        Notifications["NotificationDrawer"]
+        DataTable["DataTable Components"]
+    end
+
+    UI --> ChatLayer
+    UI --> FeatureLayer
+
+    ChatLayer --> Runtime["Chat Runtime Context"]
+    ChatLayer --> Transport["SSE / NATS / WebSocket"]
+
+    Transport --> Backend["API Service + Stream Processing"]
+```
+
+### Key Concepts
+
+- **Runtime-first design**: `useRequiredChatRuntime()` injects identity, endpoints, platform source, and navigation behavior.
+- **Mode-based chat engine**: Guide (SSE/RAG) and Mingo (NATS/agent) are pluggable via `useUnifiedChat`.
+- **Composable UI primitives**: All surfaces share ODS-based components (Button, Card, Drawer, Tag, etc.).
+- **Strict separation of concerns**:
+  - Transport + state: hooks
+  - Rendering: components
+  - Platform integration: runtime context
+
+---
+
+# 2. Chat System
+
+The Chat system is the core of this module and is built around `EmbeddableChat`.
+
+## 2.1 EmbeddableChat
+
+**Core component:**
+
+- `EmbeddableChatProps`
+
+`EmbeddableChat` is a portable AI assistant panel that:
+
+- Supports controlled and uncontrolled open state
+- Can render inside a Drawer shell or as a shell-less body
+- Switches between Guide and Mingo modes
+- Manages dialog history, archive view, rename/archive modals
+- Renders streaming messages with inline entity cards
+
+### Mode Architecture
+
+```mermaid
+flowchart TD
+    EmbeddableChat --> UnifiedChat["useUnifiedChat"]
+
+    UnifiedChat --> GuideMode["Guide Mode (SSE)"]
+    UnifiedChat --> MingoMode["Mingo Mode (NATS)"]
+
+    GuideMode --> SSEAdapter["useSseChatAdapter"]
+    MingoMode --> NatsAdapter["useNatsChatAdapter"]
+
+    SSEAdapter --> SSEBackend["API Service (SSE)"]
+    NatsAdapter --> NatsBackend["Stream Processing (NATS)"]
+```
+
+### Responsibilities
+
+- Floating trigger button
+- Drawer rendering (Radix-based)
+- Identity-aware greeting
+- Slash command onboarding
+- Attachment support (Guide-only)
+- Source citation chips
+- Archive page
+- Inline entity card dispatch
+
+---
+
+## 2.2 Message Model
+
+The chat uses a **segment-based message architecture**.
+
+Core message types:
+
+- `TextMessageData`
+- `ExecutedToolMessageData`
+- `AIMetadataMessageData`
+- `ApprovalRequest`
+- `ApprovalBatchData`
+
+Messages are rendered using:
+
+- `ChatMessageRow`
+- `ChatMessageList`
+- Segment-aware renderers (tool execution, approvals, thinking, etc.)
+
+### Segment Flow
+
+```mermaid
+flowchart LR
+    Chunk["ChunkData"] --> Processor["useRealtimeChunkProcessor"]
+    Processor --> Segments["MessageSegment[]"]
+    Segments --> Message["Message"]
+    Message --> UI["ChatMessageRow"]
+```
+
+This design allows:
+
+- Streaming token updates
+- Inline tool execution state
+- Approval workflows
+- Context compaction visualization
+
+---
+
+## 2.3 Chat Composer
+
+**Core component:**
+
+- `ChatComposerProps`
+
+`ChatComposer` renders:
+
+- `ChatInput`
+- Model usage row (`ModelDisplay`)
+- Attachment add button (Guide mode only)
+- Archived state placeholder
+
+It integrates with:
+
+- Slash commands
+- Token usage reporting
+- Streaming stop control
+- Attachment staging and upload state
+
+---
+
+## 2.4 Dialog History & Archive
+
+Core components:
+
+- `MingoChatHistoryProps`
+- `ChatArchivePageProps`
+
+Features:
+
+- Grouping: Today / Yesterday / Older
+- Infinite scroll with sentinel
+- Rename / Archive actions
+- Restore archived dialogs
+- Scroll fade affordances
+
+```mermaid
+flowchart TD
+    DialogList --> History["MingoChatHistory"]
+    History --> Row["History Row"]
+    Row --> Rename["Rename Modal"]
+    Row --> Archive["Archive Modal"]
+    Archive --> ArchivePage["ChatArchivePage"]
+```
+
+---
+
+# 3. Ticket Center
+
+**Core component:**
+
+- `TicketCenterProps`
+
+The Ticket Center provides a customer-facing support surface tightly integrated with chat identity.
+
+### Identity Gate
+
+```mermaid
+flowchart TD
+    Identity["useChatIdentity"] --> Check{Auth Tier?}
+    Check -->|anon| Empty["Sign-in EmptyState"]
+    Check -->|authenticated| TicketCenterAuthed
+```
+
+### Features
+
+- Optimistic ticket creation
+- Inline conversation threads
+- Close / reopen actions
+- Refetch and cache management
+- Support system health awareness
+
+TicketCenter intentionally does not bundle providers; embedders supply:
+
+- QueryClientProvider
+- ChatRuntimeContext
+
+---
+
+# 4. Board (Kanban Surface)
+
+Core components:
+
+- `BoardProps`
+- `TicketCardProps`
+
+The Board implements a drag-and-drop Kanban system using `@dnd-kit`.
+
+### Drag Flow
+
+```mermaid
+flowchart LR
+    Ticket["TicketCard"] --> DndContext
+    DndContext --> DragStart
+    DragStart --> DragOver
+    DragOver --> DragEnd
+    DragEnd --> OnChange["BoardChange"]
+```
+
+Capabilities:
+
+- Cross-column drag with allowedFromColumns rules
+- Optimistic reordering
+- Infinite scroll per column
+- Overlay preview during drag
+- Horizontal scrollbar with custom thumb
+
+---
+
+# 5. Notifications Drawer
+
+**Core component:**
+
+- `NotificationDrawerProps`
+
+Features:
+
+- Right-side Drawer
+- Infinite scroll unread list
+- "Complete All" bulk action
+- Live pop-up toggle
+- History navigation callback
+
+```mermaid
+flowchart TD
+    NotificationContext --> Drawer
+    Drawer --> UnreadList
+    UnreadList --> Tile["NotificationTile"]
+    Tile --> MarkRead
+```
+
+---
+
+# 6. Data Table System
+
+Core components:
+
+- `DataTableHeaderProps`
+- `DataTableRowProps`
+- `TableProps` (deprecated legacy types)
+
+Built on:
+
+- `@tanstack/react-table`
+
+### Header Capabilities
+
+- Consumer-driven sorting
+- Filter dropdown integration
+- Sticky header support
+- Responsive column hiding
+
+### Row Behavior
+
+- Full-row link mode
+- Action bubbling guard via `data-no-row-click`
+- Portal-safe click handling
+
+```mermaid
+flowchart LR
+    Table --> Header
+    Table --> Row
+    Header --> SortChange
+    Row --> RowClick
+```
+
+---
+
+# 7. Navigation & Layout Primitives
+
+Core components:
+
+- `HeaderProps`
+- `NavigationSidebarProps`
+- `PageLayoutProps`
+
+### Sidebar Behavior
+
+```mermaid
+flowchart TD
+    Viewport --> Breakpoint{md / lg?}
+    Breakpoint -->|Desktop| PersistentSidebar
+    Breakpoint -->|Tablet| OverlaySidebar
+    OverlaySidebar --> Backdrop
+```
+
+Features:
+
+- Persisted minimized state (localStorage)
+- Tablet overlay mode
+- Escape-to-close
+- Disabled state for full navigation lock
+
+---
+
+# 8. Shared UI Components
+
+Additional reusable UI primitives included:
+
+- `OrganizationCard`
+- `TagsManager`
+- `FilterModal`
+- `ChatTicketList`
+
+These are fully ODS-aligned and used across:
+
+- Board
+- Ticket Center
+- Admin surfaces
+- Data listing pages
+
+---
+
+# 9. Network & Transport Types
+
+Core transport types:
+
+- `NetworkResponse`
+- `PaginatedResponse`
+- `WebSocketConfig`
+- `WebSocketMessage`
+- `ChunkData`
+
+### Real-Time Pipeline
+
+```mermaid
+flowchart LR
+    Backend --> NATS["NATS / JetStream"]
+    Backend --> SSE["SSE"]
+
+    NATS --> Subscription["useNatsDialogSubscription"]
+    SSE --> Adapter["useSseChatAdapter"]
+
+    Subscription --> Processor
+    Adapter --> Processor
+```
+
+The real-time system supports:
+
+- Reconnection backoff tuning
+- Chunk catch-up
+- Token usage telemetry
+- Approval lifecycle events
+
+---
+
+# 10. How This Module Fits Into OpenFrame
+
+The **Frontend Core Ui And Chat** module is the presentation and interaction layer for:
+
+- `api-service-core-http-and-graphql` (SSE Guide mode)
+- `stream-processing-kafka` (via NATS agent streaming)
+- `authorization-service-core` (identity via runtime)
+- `gateway-service-core` (WebSocket + routing)
+
+It does **not**:
+
+- Own authentication
+- Own data persistence
+- Own API contracts
+
+Instead, it consumes them via:
+
+- Runtime context
+- Hooks
+- Transport adapters
+
+---
+
+# 11. Design Principles
+
+1. **Runtime abstraction over hard imports**
+2. **Segment-first message rendering**
+3. **Feature-flag-driven extensibility**
+4. **Platform-neutral embedding**
+5. **Strict separation of transport and presentation**
+
+---
+
+# Conclusion
+
+The **Frontend Core Ui And Chat** module is the reusable UI and AI interaction layer of OpenFrame.
+
+It provides:
+
+- A fully embeddable AI assistant
+- Real-time streaming with approval workflows
+- Ticket management
+- Drag-and-drop board workflows
+- Data-table and filtering primitives
+- Responsive navigation framework
+
+By centralizing chat logic, UI components, and interaction patterns in a single portable module, OpenFrame ensures consistent UX across Hub, customer portals, and embedded third-party environments.
\ No newline at end of file
diff --git a/docs/reference/architecture/gateway-service-core/gateway-service-core.md b/docs/reference/architecture/gateway-service-core/gateway-service-core.md
new file mode 100644
index 000000000..d7ddf2952
--- /dev/null
+++ b/docs/reference/architecture/gateway-service-core/gateway-service-core.md
@@ -0,0 +1,367 @@
+# Gateway Service Core
+
+The **Gateway Service Core** module is the reactive edge layer of the OpenFrame platform. It acts as the unified entry point for:
+
+- REST API traffic
+- WebSocket connections
+- Tool integrations (MeshCentral, Tactical RMM, and others)
+- External API access with API keys and rate limiting
+- Multi-tenant JWT validation and security enforcement
+
+Built on **Spring Cloud Gateway + WebFlux (Netty)**, this module provides high-performance, non-blocking request routing and security orchestration between frontend clients, agents, and downstream services.
+
+---
+
+## 1. Architectural Overview
+
+The Gateway Service Core sits between clients (UI, agents, integrations) and internal services or integrated tools.
+
+```mermaid
+flowchart LR
+    Browser["Frontend UI"] --> Gateway["Gateway Service Core"]
+    Agent["OpenFrame Agent"] --> Gateway
+    ExternalAPI["External API Client"] --> Gateway
+
+    Gateway --> ApiService["API Service Core"]
+    Gateway --> AuthService["Authorization Service Core"]
+    Gateway --> Management["Management Service Core"]
+    Gateway --> ToolMesh["MeshCentral"]
+    Gateway --> ToolTactical["Tactical RMM"]
+    Gateway --> Nats["NATS WebSocket"]
+```
+
+### Responsibilities
+
+1. **Authentication & Authorization** (JWT, roles, scopes)
+2. **API Key validation and rate limiting**
+3. **Tenant-aware issuer resolution**
+4. **REST and WebSocket proxying**
+5. **Tool-specific upstream resolution strategies**
+6. **CORS and security header enforcement**
+7. **Reactive performance tuning (Netty + WebClient)**
+
+---
+
+## 2. Core Layers Inside the Gateway
+
+```mermaid
+flowchart TD
+    Netty["Netty & WebFlux Runtime"] --> Filters["Security & Global Filters"]
+    Filters --> Controllers["REST Controllers"]
+    Filters --> WsRoutes["WebSocket Routes"]
+
+    Controllers --> RestProxy["REST Proxy Layer"]
+    WsRoutes --> WsProxy["WebSocket Proxy Layer"]
+
+    RestProxy --> UpstreamResolvers["Tool Upstream Resolvers"]
+    WsProxy --> UpstreamResolvers
+
+    UpstreamResolvers --> Downstream["Integrated Tools / Services"]
+```
+
+The module is structured around five main concerns:
+
+- **Runtime & Networking Configuration**
+- **Security & JWT Infrastructure**
+- **API Key & Rate Limiting**
+- **Tool Routing & Upstream Resolution**
+- **WebSocket Proxying**
+
+---
+
+# 3. Runtime & Networking Configuration
+
+### NettySocketConfig
+
+Optimizes the embedded Netty server and client:
+
+- Disables `SO_LINGER`
+- Enables `TCP_NODELAY`
+- Customizes both server and HTTP client behavior
+- Provides a dedicated `ReactorNettyWebSocketClient`
+
+This ensures low-latency proxy behavior for high-frequency WebSocket and REST traffic.
+
+### WebClientConfig
+
+Defines a tuned `WebClient.Builder` with:
+
+- 30s connect timeout
+- 30s read/write timeout
+- Response timeout configuration
+
+Used internally by proxy and integration services.
+
+---
+
+# 4. Security Architecture
+
+Security in the Gateway Service Core is fully reactive and role-driven.
+
+## 4.1 GatewaySecurityConfig
+
+Configures:
+
+- OAuth2 Resource Server (JWT validation)
+- Role-based access rules
+- WebFlux security filter chain
+- Endpoint-level role constraints
+
+### Role Model
+
+- `ROLE_ADMIN`
+- `ROLE_AGENT`
+- `SCOPE_*` authorities
+
+### Path-Based Access
+
+Path constants define security zones:
+
+- `/api/**` → ADMIN
+- `/tools/agent/**` → AGENT
+- `/ws/tools/**` → ADMIN or AGENT (depending on route)
+- `/clients/**` → AGENT
+- `/chat/**` → AGENT or ADMIN
+
+---
+
+## 4.2 JWT Multi-Tenant Validation
+
+### JwtAuthConfig
+
+Implements:
+
+- Dynamic issuer-based authentication manager resolution
+- Caffeine cache of `ReactiveAuthenticationManager`
+- Strict issuer validation
+
+```mermaid
+flowchart TD
+    Request["Incoming JWT"] --> IssuerResolver["Issuer Resolver"]
+    IssuerResolver --> Cache["Caffeine Cache"]
+    Cache --> JwtDecoder["JWT Decoder"]
+    JwtDecoder --> Validator["Issuer + Default Validators"]
+    Validator --> Authenticated["Authenticated Principal"]
+```
+
+### DefaultIssuerUrlProvider
+
+OSS fallback for single-tenant deployments:
+
+- Uses `allowed-issuer-base + super-tenant-id`
+- Avoids database lookup
+
+---
+
+## 4.3 Authorization Header Injection
+
+### AddAuthorizationHeaderFilter
+
+Pre-auth filter that ensures an `Authorization` header exists by resolving the token from:
+
+1. `access_token` cookie
+2. Custom header
+3. Query parameter
+
+This enables:
+
+- WebSocket auth
+- Browser cookie-based sessions
+- Backward compatibility with legacy clients
+
+---
+
+## 4.4 CORS Handling
+
+Two configurations:
+
+- **CorsConfig** → Standard configurable CORS
+- **CorsDisableConfig** → Permissive CORS (SaaS mode)
+
+Controlled via `openframe.gateway.disable-cors` property.
+
+---
+
+# 5. API Key Authentication & Rate Limiting
+
+The gateway protects `/external-api/**` endpoints via a global filter.
+
+## ApiKeyAuthenticationFilter
+
+Flow:
+
+```mermaid
+flowchart TD
+    Req["Request /external-api/**"] --> CheckHeader["X-API-Key Present?"]
+    CheckHeader -->|"No"| Reject["401 Unauthorized"]
+    CheckHeader -->|"Yes"| Validate["Validate API Key"]
+    Validate -->|"Invalid"| Reject
+    Validate -->|"Valid"| RateCheck["Rate Limit Check"]
+    RateCheck -->|"Exceeded"| TooMany["429 Too Many Requests"]
+    RateCheck -->|"Allowed"| Forward["Forward Request"]
+```
+
+### Responsibilities
+
+- Validates API key
+- Increments usage statistics
+- Applies minute/hour/day limits
+- Adds headers:
+  - `X-RateLimit-Limit-*`
+  - `X-RateLimit-Remaining-*`
+- Injects user context headers
+
+This enables secure external tool integrations and third-party automation.
+
+---
+
+# 6. REST Tool Proxying
+
+## IntegrationController
+
+Handles tool-based routing under:
+
+- `/tools/{toolId}/**`
+- `/tools/agent/{toolId}/**`
+
+Capabilities:
+
+- Health checks
+- Integration tests
+- Transparent REST proxying
+
+Delegates to:
+
+- `IntegrationService`
+- `RestProxyService`
+
+---
+
+# 7. WebSocket Gateway
+
+WebSocket routing is handled via Spring Cloud Gateway route definitions.
+
+## WebSocketGatewayConfig
+
+Defines routes for:
+
+- `/ws/tools/agent/{toolId}/**`
+- `/ws/tools/{toolId}/**`
+- `/ws/nats`
+- `/ws/nats-api`
+
+Also provides:
+
+- Optional proxy session cleanup
+- WebSocket security decorator
+- Traffic metrics integration
+
+```mermaid
+flowchart LR
+    ClientWS["WebSocket Client"] --> GatewayWS["WebSocket Gateway"]
+    GatewayWS --> ToolResolver["Tool Upstream Resolver"]
+    ToolResolver --> Mesh["MeshCentral"]
+    ToolResolver --> Tactical["Tactical RMM"]
+    GatewayWS --> Nats["NATS"]
+```
+
+---
+
+# 8. Tool Upstream Resolution Strategy
+
+The gateway uses a pluggable `ToolUpstreamResolver` strategy.
+
+## DefaultToolUpstreamResolver
+
+- Reads tool URLs from Mongo
+- Supports REST and WS
+- Fallback for all tools
+
+## MeshCentralUpstreamResolver
+
+Optimized routing:
+
+- Avoids Mongo lookup per request
+- Reads config from `openframe.tools.meshcentral.*`
+- Supports path prefix injection for tenant scoping
+
+## TacticalRmmUpstreamResolver
+
+Path-aware routing:
+
+- REST → backend
+- WS → Daphne
+- WS with NATS path prefix → NATS upstream
+
+```mermaid
+flowchart TD
+    Request["Tool Request"] --> ResolverRegistry["Resolver Registry"]
+    ResolverRegistry -->|"meshcentral-server"| MeshResolver["MeshCentral Resolver"]
+    ResolverRegistry -->|"tactical-rmm"| TacticalResolver["Tactical RMM Resolver"]
+    ResolverRegistry -->|"other"| DefaultResolver["Default Resolver"]
+```
+
+This design allows each tool to define:
+
+- Independent REST upstream
+- Independent WebSocket upstream
+- Path-based internal fan-out
+
+Without modifying core gateway logic.
+
+---
+
+# 9. Origin Sanitization & Internal Probes
+
+## OriginSanitizerFilter
+
+Removes `Origin: null` headers to avoid WebSocket/CORS edge-case failures.
+
+## InternalAuthProbeController
+
+Optional internal probe endpoint:
+
+- `/internal/authz/probe`
+- Enabled only via configuration
+
+Used for health or sidecar verification.
+
+---
+
+# 10. Interaction with Other Modules
+
+The Gateway Service Core coordinates with:
+
+- **Authorization Service Core** → Issues JWT tokens
+- **API Service Core (HTTP & GraphQL)** → Business APIs
+- **Management Service Core** → Tool initialization and lifecycle
+- **Data Models & Mongo Repositories** → Tool and API key metadata
+- **Stream Processing (Kafka)** → Event-driven backend processing
+- **Frontend Core UI & Chat** → Consumes REST and WebSocket endpoints
+
+The gateway itself remains stateless and reactive, delegating persistence and business logic to downstream modules.
+
+---
+
+# 11. Design Principles
+
+1. **Reactive First** – Non-blocking I/O everywhere
+2. **Multi-Tenant Secure by Default**
+3. **Pluggable Tool Routing**
+4. **Protocol-Agnostic Proxy (REST + WS)**
+5. **Clear Role Segmentation (ADMIN vs AGENT)**
+6. **OSS and SaaS Compatibility**
+
+---
+
+# Conclusion
+
+The **Gateway Service Core** is the high-performance security and routing backbone of OpenFrame. It:
+
+- Enforces authentication and authorization
+- Validates API keys and rate limits
+- Dynamically resolves JWT issuers per tenant
+- Transparently proxies REST and WebSocket traffic
+- Implements tool-specific upstream routing strategies
+
+It enables OpenFrame to integrate diverse IT tools, agents, and clients behind a unified, secure, and reactive edge layer.
\ No newline at end of file
diff --git a/docs/reference/architecture/management-service-core/management-service-core.md b/docs/reference/architecture/management-service-core/management-service-core.md
new file mode 100644
index 000000000..5089d81ed
--- /dev/null
+++ b/docs/reference/architecture/management-service-core/management-service-core.md
@@ -0,0 +1,421 @@
+# Management Service Core
+
+## Overview
+
+The **Management Service Core** module is the operational backbone of the OpenFrame platform. It is responsible for:
+
+- Cluster and release version coordination  
+- Integrated tool lifecycle management  
+- Agent and client configuration bootstrapping  
+- Scheduled background maintenance tasks  
+- MongoDB migrations and data backfills  
+- Distributed job coordination via Redis-based locking  
+
+While the API and Authorization modules expose external interfaces, the Management Service Core ensures that the platform is correctly initialized, synchronized, and maintained over time.
+
+---
+
+## Architectural Role in the Platform
+
+The Management Service Core sits between infrastructure-level components (MongoDB, Redis, NATS, Kafka Connect) and higher-level services such as API, Gateway, and Stream Processing.
+
+```mermaid
+flowchart TD
+    Gateway["Gateway Service Core"] --> API["API Service Core HTTP and GraphQL"]
+    API --> Data["Data Models and Repositories Mongo"]
+    API --> Stream["Stream Processing Kafka"]
+
+    Management["Management Service Core"] --> Data
+    Management --> Redis["Redis"]
+    Management --> NATS["NATS Streams"]
+    Management --> KafkaConnect["Kafka Connect / Debezium"]
+
+    Stream --> Data
+```
+
+### Responsibilities by Layer
+
+| Layer | Responsibility |
+|--------|----------------|
+| Configuration | Bootstraps encoders, retry, scheduling, locking |
+| Initialization | Seeds secrets, tools, streams, client configs |
+| Controllers | Administrative operational endpoints |
+| Migrations | Schema and data evolution (Mongock) |
+| Schedulers | Periodic distributed background tasks |
+| Services | Domain-specific operational logic |
+| Hooks | Extensibility points after tool persistence |
+
+---
+
+# Core Configuration
+
+## ManagementConfiguration
+
+Provides the base Spring configuration and defines a `PasswordEncoder` bean using BCrypt for secure hashing.
+
+Key aspects:
+
+- Component scanning across `com.openframe`  
+- Excludes Cassandra health indicator  
+- Registers BCrypt password encoder  
+
+This configuration ensures Management Service Core can operate independently without requiring Cassandra dependencies.
+
+---
+
+## RetryConfiguration
+
+Enables Spring Retry across the module.
+
+```text
+@Configuration
+@EnableRetry
+```
+
+This allows service methods to use retry semantics for:
+
+- External integrations  
+- Transient infrastructure failures  
+- Messaging retries  
+
+---
+
+## ShedLockConfig
+
+Enables distributed scheduling using Redis-backed locks.
+
+```mermaid
+flowchart LR
+    Scheduler["Scheduled Task"] --> ShedLock["ShedLock"]
+    ShedLock --> Redis["Redis Lock Provider"]
+```
+
+Key characteristics:
+
+- Multi-instance safe scheduling  
+- Tenant-scoped lock keys  
+- Environment-aware locking namespace  
+
+Lock keys follow a tenant-scoped pattern:
+
+```text
+of:{tenantId}:job-lock:{environment}:{lockName}
+```
+
+This guarantees only one instance of a scheduled job runs across the cluster.
+
+---
+
+# Controllers
+
+The Management Service Core exposes operational endpoints that are typically invoked by internal services or cluster agents.
+
+---
+
+## DevicePinotResyncController
+
+**Endpoint:** `POST /v1/devices/pinot-resync`
+
+Purpose:
+
+- Reads all machines from MongoDB  
+- Triggers `MachineTagEventService.processMachineSaveAll(...)`  
+- Forces re-indexing into analytical storage (e.g., Pinot)
+
+```mermaid
+flowchart TD
+    Controller["DevicePinotResyncController"] --> Repo["MachineRepository"]
+    Controller --> EventService["MachineTagEventService"]
+    Repo --> Mongo["MongoDB"]
+    EventService --> Stream["Event Processing"]
+```
+
+This is primarily used for recovery and consistency repair.
+
+---
+
+## IntegratedToolController
+
+**Base path:** `/v1/tools`
+
+Responsibilities:
+
+- Retrieve all integrated tools  
+- Retrieve tool by ID  
+- Create or update tool configuration  
+
+### Save Flow
+
+```mermaid
+flowchart TD
+    Request["Save Tool Request"] --> Service["IntegratedToolService"]
+    Service --> Mongo["MongoDB"]
+    Service --> Debezium["DebeziumService"]
+    Service --> Hooks["Post Save Hooks"]
+```
+
+Important behavior:
+
+- Preserves existing UUID if tool exists  
+- Ensures tenant scoping  
+- Enables tool automatically  
+- Conditionally applies Debezium connectors only after tenant registration  
+- Invokes all `IntegratedToolPostSaveHook` implementations  
+
+### Extension Point
+
+`IntegratedToolPostSaveHook` allows lightweight side effects after persistence without using Spring events.
+
+---
+
+## ReleaseVersionController
+
+**Endpoint:** `POST /v1/cluster-registrations`
+
+Accepts a `ReleaseVersionRequest` containing:
+
+```text
+imageTagVersion: string
+```
+
+Delegates to `ReleaseVersionService` to process cluster version updates.
+
+This supports:
+
+- Cluster self-registration  
+- Rolling upgrade awareness  
+- Version-based feature control  
+
+---
+
+# Application Initializers
+
+Initializers run at application startup using `ApplicationRunner`.
+
+```mermaid
+flowchart TD
+    Startup["Application Startup"] --> SecretInit["Agent Registration Secret"]
+    Startup --> ToolAgentInit["Integrated Tool Agent Config"]
+    Startup --> NatsInit["NATS Stream Config"]
+    Startup --> ClientInit["Client Configuration"]
+    Startup --> TacticalInit["Tactical RMM Scripts"]
+```
+
+---
+
+## AgentRegistrationSecretInitializer
+
+- Ensures an initial agent registration secret exists  
+- Delegates to `AgentRegistrationSecretManagementService`  
+- Uses optional processor hook for post-processing  
+
+Default behavior is implemented by `DefaultAgentRegistrationSecretManagementProcessor`.
+
+---
+
+## IntegratedToolAgentInitializer
+
+- Loads agent configurations from classpath JSON files  
+- Parses via Jackson  
+- Applies configuration updates through `IntegratedToolAgentService`  
+
+Fails fast if no configuration paths are provided.
+
+---
+
+## NatsStreamConfigurationInitializer
+
+Bootstraps NATS streams:
+
+- TOOL_INSTALLATION  
+- CLIENT_UPDATE  
+- TOOL_UPDATE  
+- TOOL_CONNECTIONS  
+- INSTALLED_AGENTS  
+
+```mermaid
+flowchart LR
+    Init["NATS Stream Initializer"] --> Stream1["TOOL_INSTALLATION"]
+    Init --> Stream2["CLIENT_UPDATE"]
+    Init --> Stream3["TOOL_UPDATE"]
+    Init --> Stream4["TOOL_CONNECTIONS"]
+    Init --> Stream5["INSTALLED_AGENTS"]
+```
+
+Allows additional providers to contribute extra stream definitions.
+
+---
+
+## OpenFrameClientConfigurationInitializer
+
+- Loads `client-configuration.json`  
+- Applies configuration through `OpenFrameClientConfigurationService`  
+
+Ensures clients receive consistent update metadata.
+
+---
+
+## TacticalRmmScriptsInitializer
+
+Automates Tactical RMM script lifecycle:
+
+- Reads PowerShell scripts from resources  
+- Checks existing scripts via TacticalRmmClient  
+- Creates or updates scripts  
+
+This ensures remote management automation remains consistent across deployments.
+
+---
+
+# Database Migrations (Mongock)
+
+The module uses Mongock `@ChangeUnit` migrations for safe schema evolution.
+
+```mermaid
+flowchart TD
+    Migration["Mongock Migration"] --> BackfillVersion["Backfill Document Version"]
+    Migration --> BackfillOrder["Backfill Ticket Order"]
+    Migration --> StatusMigration["Migrate Ticket Status Model"]
+```
+
+## BackfillDocumentVersionChangeUnit
+
+Adds `documentVersion = 0` where missing in:
+
+- integrated_tool_agents  
+- openframe_client_configuration  
+- release_versions  
+
+Tenant-scoped execution.
+
+---
+
+## BackfillTicketOrdersChangeUnit
+
+- Assigns LexoRank ordering to tickets missing order  
+- Processes per `TicketStatus`  
+- Sorts by `createdAt` descending  
+
+Ensures stable column ordering in ticket boards.
+
+---
+
+## MigrateTicketStatusesChangeUnit
+
+Feature-flagged migration that:
+
+- Seeds system status definitions  
+- Converts legacy `status` field  
+- Writes `statusId` and `statusKind`  
+- Removes legacy field  
+
+Supports lifecycle model rollout safely.
+
+---
+
+# Scheduled Background Jobs
+
+Schedulers provide continuous system maintenance.
+
+```mermaid
+flowchart TD
+    Scheduler["Schedulers"] --> AgentVersion["Agent Version Fallback"]
+    Scheduler --> ApiKeySync["API Key Stats Sync"]
+    Scheduler --> Heartbeat["Device Offline Detection"]
+    Scheduler --> FleetMdm["Fleet MDM Setup"]
+```
+
+---
+
+## AgentVersionUpdatePublishFallbackScheduler
+
+- Publishes OpenFrame client updates  
+- Publishes tool agent updates  
+- Retries until `maxPublishAttempts`  
+- Uses distributed ShedLock  
+
+Ensures reliable version propagation via NATS.
+
+---
+
+## ApiKeyStatsSyncScheduler
+
+- Synchronizes API key usage statistics  
+- Syncs from Redis to MongoDB  
+- Protected by distributed lock  
+
+Provides consistent billing/analytics state.
+
+---
+
+## DeviceHeartbeatOfflineDetectionScheduler
+
+- Periodically marks stale devices offline  
+- Delegates to `DeviceHeartbeatOfflineDetectionService`  
+
+Maintains accurate fleet health state.
+
+---
+
+## FleetMdmSetupScheduler
+
+- Detects Fleet MDM tool presence  
+- Executes setup and token provisioning  
+- Retries automatically on failure  
+
+Enables automated MDM provisioning.
+
+---
+
+# Services
+
+## OpenFrameClientVersionUpdateService
+
+Designed to coordinate version update processing for OpenFrame clients.  
+Currently acts as a structural extension point for publishing version updates.
+
+---
+
+## DefaultAgentRegistrationSecretManagementProcessor
+
+Fallback processor for agent registration secrets.
+
+- Executes after initial secret creation  
+- Intended for logging or minimal side effects  
+- Replaceable via custom bean implementation  
+
+---
+
+# Operational Characteristics
+
+## Multi-Tenancy
+
+- All migrations and schedulers operate with `TenantIdProvider`  
+- Redis locks are tenant-scoped  
+- Tool and configuration updates preserve tenant boundaries  
+
+## Distributed Safety
+
+- ShedLock prevents duplicate execution  
+- Retry mechanisms handle transient failures  
+- Feature flags gate risky migrations  
+
+## Extensibility
+
+- Post-save hooks for tools  
+- Additional NATS stream providers  
+- Replaceable secret processors  
+
+---
+
+# Summary
+
+The **Management Service Core** module ensures that OpenFrame environments:
+
+- Start in a consistent state  
+- Remain synchronized across distributed instances  
+- Safely evolve database schemas  
+- Maintain external tool integrations  
+- Execute reliable background operations  
+
+It is the operational control plane of the platform — coordinating lifecycle, infrastructure, and system integrity across all services.
\ No newline at end of file
diff --git a/docs/reference/architecture/stream-processing-kafka/stream-processing-kafka.md b/docs/reference/architecture/stream-processing-kafka/stream-processing-kafka.md
new file mode 100644
index 000000000..1eaf09fe5
--- /dev/null
+++ b/docs/reference/architecture/stream-processing-kafka/stream-processing-kafka.md
@@ -0,0 +1,353 @@
+# Stream Processing Kafka
+
+The **Stream Processing Kafka** module is the event ingestion and stream-processing backbone of OpenFrame.  
+It consumes Change Data Capture (CDC) events from integrated tools (MeshCentral, Tactical RMM, Fleet MDM), enriches and normalizes them, maps them to a unified event model, and forwards them to downstream systems such as Cassandra and Kafka topics.
+
+This module enables:
+
+- Multi-tenant event ingestion via Kafka
+- Debezium-based CDC processing
+- Tool-specific event deserialization
+- Unified event type mapping
+- Machine, organization, and tenant enrichment
+- Optional Kafka Streams–based enrichment pipelines
+- Cassandra persistence for long-term log storage
+
+---
+
+## 1. Architectural Overview
+
+The Stream Processing Kafka module sits between integrated tools and the unified data layer.
+
+```mermaid
+flowchart LR
+    ToolA["Integrated Tools\nMeshCentral / Tactical / Fleet"] --> Debezium["Debezium CDC"]
+    Debezium --> KafkaIn["Kafka Inbound Topics"]
+    KafkaIn --> Listener["JsonKafkaListener"]
+    Listener --> Processor["GenericJsonMessageProcessor"]
+    Processor --> Deserializer["Tool-Specific Deserializers"]
+    Deserializer --> Enrichment["IntegratedToolDataEnrichmentService"]
+    Enrichment --> Mapper["EventTypeMapper"]
+    Mapper --> Handler["DebeziumMessageHandler"]
+    Handler --> Cassandra["Cassandra (UnifiedLogEvent)"]
+    Handler --> KafkaOut["Outbound Kafka Topics"]
+```
+
+### Core Responsibilities
+
+| Layer | Responsibility |
+|--------|---------------|
+| Kafka Listener | Consumes multi-topic CDC events |
+| Deserializers | Convert tool-specific payloads into normalized structures |
+| Enrichment | Resolve tenant, machine, organization metadata |
+| Mapping | Convert source event types to `UnifiedEventType` |
+| Handlers | Persist to Cassandra or republish to Kafka |
+| Kafka Streams | Perform real-time stream joins (Fleet activity enrichment) |
+
+---
+
+## 2. Kafka Configuration Layer
+
+### 2.1 `KafkaConfig`
+
+Provides a `Converter<byte[], MessageType>` to convert Kafka headers into strongly typed `MessageType` enums.
+
+This allows the listener to route events correctly based on header metadata.
+
+### 2.2 `KafkaStreamsConfig`
+
+Enables and configures Kafka Streams processing.
+
+Key configuration aspects:
+
+- Application ID namespaced by cluster ID
+- At-least-once processing guarantee
+- Explicit key/value Serdes
+- Controlled stream threads (1)
+- State directory configuration
+- Windowing tolerance via `MAX_TASK_IDLE_MS`
+
+```mermaid
+flowchart TD
+    Config["KafkaStreamsConfig"] --> AppId["Application ID"]
+    Config --> Serdes["Custom JSON Serdes"]
+    Config --> ConsumerCfg["Consumer Config"]
+    Config --> ProducerCfg["Producer Config"]
+    Config --> StateDir["State Store Directory"]
+```
+
+---
+
+## 3. Event Ingestion Pipeline
+
+### 3.1 JsonKafkaListener
+
+`JsonKafkaListener` consumes multiple inbound integrated-tool topics:
+
+- MeshCentral events
+- Tactical RMM events
+- Fleet MDM events
+- Fleet query result events
+- Fleet policy membership events
+
+It forwards:
+
+- `CommonDebeziumMessage`
+- `MessageType` (from header)
+
+To:
+
+- `GenericJsonMessageProcessor`
+
+```mermaid
+flowchart LR
+    Topics["Inbound Kafka Topics"] --> Listener["JsonKafkaListener"]
+    Listener --> Processor["GenericJsonMessageProcessor"]
+```
+
+Activation is conditional on cluster mode (`tenant`), ensuring proper multi-tenant isolation.
+
+---
+
+## 4. Deserialization Layer
+
+All tool-specific deserializers extend a shared base (via `IntegratedToolEventDeserializer`).
+
+They extract:
+
+- Agent ID
+- Tool event ID
+- Source event type
+- Message summary
+- Timestamp
+- Result / Error payloads
+
+### Supported Tool Deserializers
+
+| Tool | Deserializer |
+|------|-------------|
+| MeshCentral | `MeshCentralEventDeserializer` |
+| Tactical RMM (audit) | `TrmmAuditEventDeserializer` |
+| Tactical RMM (history) | `TrmmAgentHistoryEventDeserializer` |
+| Tactical RMM (task result) | `TrmmTaskResultEventDeserializer` |
+| Fleet MDM (activity) | `FleetEventDeserializer` |
+| Fleet MDM (policy activity) | `FleetPolicyActivityDeserializer` |
+| Fleet MDM (policy membership) | `FleetPolicyMembershipEventDeserializer` |
+| Fleet MDM (query result) | `FleetQueryResultEventDeserializer` |
+
+Each deserializer:
+
+- Extracts structured fields from CDC payload
+- Uses `TimestampParser` for ISO-8601 normalization
+- Optionally consults cache services
+- Produces a unified intermediate event model
+
+---
+
+## 5. Unified Event Type Mapping
+
+### EventTypeMapper
+
+Maps:
+
+- `(IntegratedToolType, sourceEventType)`  
+To:
+- `UnifiedEventType`
+
+If no mapping exists → defaults to `UNKNOWN`.
+
+```mermaid
+flowchart TD
+    Source["Tool Event"] --> ToolType["IntegratedToolType"]
+    Source --> SourceType["Source Event Type"]
+    ToolType --> Mapper["EventTypeMapper"]
+    SourceType --> Mapper
+    Mapper --> Unified["UnifiedEventType"]
+```
+
+This creates a single normalized event vocabulary across all tools.
+
+---
+
+## 6. Data Enrichment Layer
+
+### 6.1 IntegratedToolDataEnrichmentService
+
+Enriches events with:
+
+- Machine ID
+- Hostname
+- Organization ID
+- Organization Name
+- Tenant ID
+
+Sources:
+
+- Redis machine cache
+- Organization cache
+- `TenantIdProvider`
+- Optional `ClusterTenantIdResolver`
+
+```mermaid
+flowchart LR
+    Event["DeserializedDebeziumMessage"] --> Enrichment
+    Enrichment --> MachineCache["MachineIdCacheService"]
+    Enrichment --> TenantResolver["Tenant Resolver"]
+    Enrichment --> Enriched["IntegratedToolEnrichedData"]
+```
+
+If machine or tenant cannot be resolved, warnings are logged but processing continues.
+
+---
+
+## 7. Message Handling Layer
+
+### 7.1 GenericMessageHandler
+
+Provides:
+
+- Validation hook
+- OperationType routing (CREATE / UPDATE / DELETE / READ)
+- Lifecycle dispatch (`handleCreate`, `handleUpdate`, etc.)
+
+### 7.2 DebeziumMessageHandler
+
+Adds Debezium operation extraction logic (`c`, `u`, `d`, `r`).
+
+### 7.3 DebeziumCassandraMessageHandler
+
+Transforms enriched events into `UnifiedLogEvent` and persists them to Cassandra.
+
+```mermaid
+flowchart TD
+    DebeziumMsg["DeserializedDebeziumMessage"] --> Transform
+    Transform --> Unified["UnifiedLogEvent"]
+    Unified --> Cassandra["Cassandra Repository"]
+```
+
+Key fields set:
+
+- Tenant ID
+- Tool Type
+- Unified Event Type
+- Event Timestamp
+- Severity
+- Message
+- Details
+
+### 7.4 TenantDebeziumKafkaMessageHandler
+
+Republishes enriched Debezium events to outbound Kafka topics using `OssTenantRetryingKafkaProducer`.
+
+Includes `TenantIdRequiredDebeziumEventValidator` which drops events without tenant context.
+
+---
+
+## 8. Kafka Streams: Fleet Activity Enrichment
+
+`ActivityEnrichmentService` performs stream joins between:
+
+- `fleet-mdm-activities`
+- `fleet-mdm-host-activities`
+
+It:
+
+1. Re-keys streams by activity ID
+2. Performs a left join (5-second window)
+3. Injects `hostId` and `agentId`
+4. Adds appropriate `MessageType` headers
+5. Publishes enriched events
+
+```mermaid
+flowchart LR
+    Activity["Activity Topic"] --> Join
+    HostActivity["HostActivity Topic"] --> Join
+    Join --> Enriched["Enriched Activity"]
+    Enriched --> Output["Fleet MDM Events Topic"]
+```
+
+Window configuration:
+
+- Duration: 5 seconds
+- No grace period
+- At-least-once semantics
+
+---
+
+## 9. Timestamp Handling
+
+`TimestampParser` standardizes timestamps using:
+
+- `Instant.parse()`
+- ISO-8601 format
+- Returns epoch milliseconds
+
+Ensures consistent temporal ordering across heterogeneous tools.
+
+---
+
+## 10. Multi-Tenancy Model
+
+Tenant resolution follows two modes:
+
+| Mode | Tenant Resolution |
+|------|-------------------|
+| Tenant Cluster | `TenantIdProvider` (single tenant per cluster) |
+| Shared Cluster | `ClusterTenantIdResolver` maps tool-scoped ID to canonical tenant ID |
+
+Events without tenant ID are rejected by `TenantIdRequiredDebeziumEventValidator`.
+
+---
+
+## 11. End-to-End Event Flow
+
+```mermaid
+flowchart TD
+    A["Integrated Tool"] --> B["Debezium CDC"]
+    B --> C["Kafka Topic"]
+    C --> D["JsonKafkaListener"]
+    D --> E["Deserializer"]
+    E --> F["Data Enrichment"]
+    F --> G["EventTypeMapper"]
+    G --> H["Message Handler"]
+    H --> I["Cassandra"]
+    H --> J["Outbound Kafka"]
+```
+
+---
+
+## 12. Design Principles
+
+- **Tool-Agnostic Normalization** – Unified event model across MSP tools
+- **Strong Multi-Tenancy Isolation** – Tenant-aware routing and validation
+- **Extensibility** – Add new deserializer + mapping without modifying core flow
+- **Observability** – Extensive logging on missing mappings or enrichment failures
+- **Backpressure Safe** – Kafka-based buffering and retry logic
+- **Separation of Concerns** – Listener → Deserializer → Enrichment → Mapping → Handler
+
+---
+
+## 13. How It Fits into OpenFrame
+
+The Stream Processing Kafka module:
+
+- Feeds unified events into Cassandra for analytics and dashboards
+- Supplies enriched events to downstream automation services
+- Enables audit history for devices, users, scripts, and policies
+- Bridges integrated tools into a single normalized event pipeline
+
+It is a foundational infrastructure module powering:
+
+- Device timeline views
+- Automation history
+- Compliance tracking
+- Security monitoring
+- Tenant-isolated event analytics
+
+---
+
+# Summary
+
+The **Stream Processing Kafka** module transforms raw integrated-tool CDC events into normalized, enriched, tenant-aware unified events.
+
+Through Kafka, Debezium, enrichment services, mapping logic, and optional Kafka Streams processing, it provides a scalable, extensible, and multi-tenant event ingestion backbone for OpenFrame.
\ No newline at end of file

From 8461ab61dc7fe2923c028ce7eb036aba3d5cb514 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 19:31:03 +0000
Subject: [PATCH 6/7] docs: Stage 3 - Tutorial generation (11 files) [skip ci]

---
 docs/development/.gitignore                 |   7 +
 docs/development/README.md                  | 112 ++++++++
 docs/development/architecture/README.md     | 179 ++++++++++++
 docs/development/contributing/guidelines.md | 247 ++++++++++++++++
 docs/development/security/README.md         | 283 ++++++++++++++++++
 docs/development/setup/environment.md       | 224 +++++++++++++++
 docs/development/setup/local-development.md | 242 ++++++++++++++++
 docs/development/testing/README.md          | 303 ++++++++++++++++++++
 docs/getting-started/.gitignore             |   7 +
 docs/getting-started/first-steps.md         | 142 +++++++++
 docs/getting-started/introduction.md        | 131 +++++++++
 docs/getting-started/prerequisites.md       | 141 +++++++++
 docs/getting-started/quick-start.md         | 190 ++++++++++++
 13 files changed, 2208 insertions(+)
 create mode 100644 docs/development/.gitignore
 create mode 100644 docs/development/README.md
 create mode 100644 docs/development/architecture/README.md
 create mode 100644 docs/development/contributing/guidelines.md
 create mode 100644 docs/development/security/README.md
 create mode 100644 docs/development/setup/environment.md
 create mode 100644 docs/development/setup/local-development.md
 create mode 100644 docs/development/testing/README.md
 create mode 100644 docs/getting-started/.gitignore
 create mode 100644 docs/getting-started/first-steps.md
 create mode 100644 docs/getting-started/introduction.md
 create mode 100644 docs/getting-started/prerequisites.md
 create mode 100644 docs/getting-started/quick-start.md

diff --git a/docs/development/.gitignore b/docs/development/.gitignore
new file mode 100644
index 000000000..a5d01be52
--- /dev/null
+++ b/docs/development/.gitignore
@@ -0,0 +1,7 @@
+# VoltAgent temp files
+temp/
+
+# JSON intermediate files (except schema/config)
+*.json
+!*-schema.json
+!*-config.json
diff --git a/docs/development/README.md b/docs/development/README.md
new file mode 100644
index 000000000..dcc95c0b7
--- /dev/null
+++ b/docs/development/README.md
@@ -0,0 +1,112 @@
+# Development Documentation
+
+Welcome to the `openframe-oss-lib` development documentation. This section covers everything you need to contribute to and work with the OpenFrame OSS library modules.
+
+[![OpenFrame v0.3.7 - Enhanced Developer Experience](https://img.youtube.com/vi/O8hbBO5Mym8/maxresdefault.jpg)](https://www.youtube.com/watch?v=O8hbBO5Mym8)
+
+---
+
+## Quick Navigation
+
+| Document | Description |
+|----------|-------------|
+| [Environment Setup](./setup/environment.md) | IDE, tools, and editor configuration |
+| [Local Development](./setup/local-development.md) | Clone, build, run, and debug locally |
+| [Architecture Overview](./architecture/README.md) | System design, module relationships, and data flows |
+| [Security Guidelines](./security/README.md) | Authentication, authorization, and secrets management |
+| [Testing Guide](./testing/README.md) | Test structure, running tests, and writing new tests |
+| [Contributing Guidelines](./contributing/guidelines.md) | Code style, branching, commit messages, and PR process |
+
+---
+
+## Technology Stack
+
+`openframe-oss-lib` is built on the following technology stack:
+
+### Backend
+| Technology | Version | Role |
+|-----------|---------|------|
+| **Java** | 21 | Primary language |
+| **Spring Boot** | 3.3.0 | Application framework |
+| **Spring Cloud** | 2023.0.3 | Cloud-native patterns |
+| **Netflix DGS** | 9.0.3 | GraphQL framework |
+| **MongoDB** | Reactive + Sync | Primary data store |
+| **Apache Kafka** | 3.x | Event streaming |
+| **NATS** | 0.6.2+3.5 | Lightweight messaging |
+| **Redis** | Spring Data Redis | Caching + distributed locks |
+| **Apache Cassandra** | – | Event log storage |
+| **Apache Pinot** | 1.2.0 | Analytics |
+| **gRPC** | 1.58.0 | Internal service communication |
+| **Lombok** | 1.18.30 | Boilerplate reduction |
+| **JWT (jjwt)** | 0.11.5 | Token handling |
+| **Testcontainers** | 1.21.4 | Integration testing |
+
+### Frontend (openframe-frontend-core)
+| Technology | Role |
+|-----------|------|
+| **React** | UI component library |
+| **TypeScript** | Type-safe UI development |
+| **Tailwind CSS** | Utility-first styling |
+| **NATS WebSocket** | Real-time chat transport |
+| **SSE** | Guide mode AI chat transport |
+| **Storybook** | Component development and documentation |
+| **Vitest** | Unit testing |
+
+---
+
+## Module Organization
+
+The repository follows a layered module structure:
+
+```mermaid
+graph TD
+    subgraph foundation["Foundation"]
+        exception["openframe-exception"]
+        core["openframe-core"]
+        crypto["openframe-core-crypto"]
+    end
+
+    subgraph data["Data Layer"]
+        common["openframe-data-mongo-common"]
+        sync["openframe-data-mongo-sync"]
+        reactive["openframe-data-mongo-reactive"]
+        redis["openframe-data-redis"]
+        kafka["openframe-data-kafka"]
+        nats["openframe-data-nats"]
+        cassandra["openframe-data-cassandra"]
+        pinot["openframe-data-pinot"]
+    end
+
+    subgraph services["Service Cores"]
+        api["openframe-api-service-core"]
+        apilib["openframe-api-lib"]
+        auth["openframe-authorization-service-core"]
+        gateway["openframe-gateway-service-core"]
+        management["openframe-management-service-core"]
+        stream["openframe-stream-service-core"]
+        client["openframe-client-core"]
+        security["openframe-security-core"]
+    end
+
+    subgraph tools["Tool SDKs"]
+        fleet["sdk/fleetmdm"]
+        tactical["sdk/tacticalrmm"]
+        tacticalSdk["openframe-tactical-sdk"]
+    end
+
+    foundation --> data
+    data --> services
+    services --> tools
+```
+
+---
+
+## Development Community
+
+All development discussions happen on [OpenMSP Slack](https://www.openmsp.ai/).
+
+- **Questions**: `#dev-questions` channel
+- **Feature Requests**: `#roadmap` channel
+- **Bug Reports**: `#bugs` channel
+
+Join at: [OpenMSP Slack Invite](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
diff --git a/docs/development/architecture/README.md b/docs/development/architecture/README.md
new file mode 100644
index 000000000..3b9f4a713
--- /dev/null
+++ b/docs/development/architecture/README.md
@@ -0,0 +1,179 @@
+# Architecture Overview
+
+`openframe-oss-lib` is the modular backbone of the OpenFrame platform. This document provides a high-level architectural overview, core component relationships, data flow patterns, and key design decisions.
+
+For detailed per-module documentation, see the [Reference Architecture docs](./reference/architecture/README.md).
+
+---
+
+## High-Level Architecture
+
+The system is organized as a layered, event-driven microservice platform:
+
+```mermaid
+flowchart TD
+    Frontend["Frontend Core UI and Chat"]
+    Gateway["Gateway Service Core"]
+    Auth["Authorization Service Core"]
+    API["API Service Core (HTTP + GraphQL)"]
+    Management["Management Service Core"]
+    Data["Data Models and Repositories (MongoDB)"]
+    Stream["Stream Processing (Kafka)"]
+    Cassandra["Cassandra (Unified Event Log)"]
+    Tools["Integrated Tools\n(MeshCentral / Tactical RMM / Fleet MDM)"]
+    Redis["Redis\n(Cache + Distributed Locks)"]
+    NATS["NATS\n(Agent Messaging)"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    Gateway --> Tools
+    API --> Data
+    API --> Stream
+    Stream --> Cassandra
+    Stream --> Data
+    Management --> Data
+    Management --> Redis
+    Management --> NATS
+    Tools --> Stream
+```
+
+---
+
+## Core Components Table
+
+| Module | Type | Key Responsibility |
+|--------|------|--------------------|
+| `openframe-gateway-service-core` | Edge | JWT validation, rate limiting, WebSocket proxying, tool routing |
+| `openframe-authorization-service-core` | Auth | Multi-tenant OAuth2/OIDC, JWT issuance, SSO (Google/Microsoft) |
+| `openframe-api-service-core` | API | REST + GraphQL (Netflix DGS), DataLoader batching, Relay pagination |
+| `openframe-api-lib` | Contracts | Shared DTOs, filter criteria, pagination primitives |
+| `openframe-data-mongo-common` | Data Models | Document definitions, base repositories |
+| `openframe-data-mongo-sync` | Persistence | Synchronous MongoDB repositories with custom queries |
+| `openframe-data-mongo-reactive` | Persistence | Reactive MongoDB repositories for auth flows |
+| `openframe-data-redis` | Cache | API key stats, rate limiting, ShedLock distributed locking |
+| `openframe-data-kafka` | Messaging | Kafka producers with retry and recovery |
+| `openframe-data-nats` | Messaging | NATS pub/sub, agent notifications, command dispatch |
+| `openframe-stream-service-core` | Events | Debezium CDC ingestion, event normalization, Kafka Streams |
+| `openframe-management-service-core` | Ops | Cluster coordination, tool lifecycle, schedulers, migrations |
+| `openframe-client-core` | Agents | Device registration, authentication, tool installation |
+| `openframe-security-core` | Security | JWT primitives, `AuthPrincipal`, cookie service |
+| `openframe-frontend-core` | UI | React component library, AI chat engine (Guide + Mingo modes) |
+
+---
+
+## Request Flow: Frontend to Data
+
+```mermaid
+sequenceDiagram
+    participant Browser as "Browser / Client"
+    participant Gateway as "Gateway Service"
+    participant Auth as "Auth Service"
+    participant API as "API Service"
+    participant Mongo as "MongoDB"
+
+    Browser->>Gateway: HTTP Request (with JWT cookie)
+    Gateway->>Gateway: Extract JWT from cookie
+    Gateway->>Auth: Validate JWT (issuer check)
+    Auth-->>Gateway: Token valid
+    Gateway->>API: Forward request + Authorization header
+    API->>API: Resolve AuthPrincipal
+    API->>Mongo: Query with tenantId filter
+    Mongo-->>API: Result documents
+    API-->>Browser: JSON / GraphQL response
+```
+
+---
+
+## Event Ingestion Flow (Kafka / Debezium)
+
+```mermaid
+flowchart LR
+    ToolA["MeshCentral / Tactical / Fleet"] --> Debezium["Debezium CDC"]
+    Debezium --> KafkaIn["Kafka Inbound Topics"]
+    KafkaIn --> Listener["JsonKafkaListener"]
+    Listener --> Processor["GenericJsonMessageProcessor"]
+    Processor --> Deserializer["Tool-Specific Deserializer"]
+    Deserializer --> Enrichment["IntegratedToolDataEnrichmentService"]
+    Enrichment --> Mapper["EventTypeMapper (UnifiedEventType)"]
+    Mapper --> Handler["DebeziumMessageHandler"]
+    Handler --> Cassandra["Cassandra (UnifiedLogEvent)"]
+    Handler --> KafkaOut["Outbound Kafka Topics"]
+```
+
+---
+
+## Multi-Tenancy Model
+
+Multi-tenancy is enforced at the data layer through `TenantScoped`:
+
+```mermaid
+flowchart TD
+    Request["Incoming Request"] --> TenantCtx["TenantContextFilter"]
+    TenantCtx --> TenantId["TenantContext (ThreadLocal)"]
+    TenantId --> Repo["Tenant-Scoped Repository"]
+    Repo --> Query["MongoDB Query with tenantId filter"]
+    Query --> MongoDB[("MongoDB")]
+```
+
+**Key principles:**
+- Every domain document implements `TenantScoped` (has `tenantId` field)
+- OSS deployments default `TENANT_ID` to `oss`
+- SaaS deployments use per-request tenant resolution
+- Each tenant has independent RSA key pairs for JWT signing
+
+---
+
+## Security Architecture
+
+```mermaid
+flowchart TD
+    User["User"] -->|"Login"| AuthServer["Authorization Service Core"]
+    AuthServer -->|"Per-tenant RSA signing"| JWT["Tenant-Scoped JWT"]
+    JWT --> Gateway["Gateway Service Core"]
+    Gateway -->|"JWT validation + role check"| API["API Service Core"]
+    API -->|"AuthPrincipal injection"| Handler["Controller / DataFetcher"]
+```
+
+**Authentication layers:**
+1. **Gateway**: validates JWT, extracts from cookie/header/query param
+2. **Authorization Service**: issues tenant-scoped JWTs with custom claims (`tenant_id`, `userId`, `roles`)
+3. **API Service**: OAuth2 Resource Server — verifies signatures, resolves `AuthPrincipal`
+4. **External API**: API key authentication with per-minute/hour/day rate limiting
+
+---
+
+## Key Design Decisions
+
+### 1. Module Composability
+Each module is independently buildable and testable. Services consume only the modules they need rather than a monolithic dependency.
+
+### 2. Relay-Style Pagination
+The API layer uses cursor-based pagination (`ConnectionArgs`, `CursorCodec`, `GenericEdge`) following the Relay GraphQL specification for consistent, stable pagination across all list endpoints.
+
+### 3. DataLoader Pattern (N+1 Prevention)
+All GraphQL resolvers that load related entities use DataLoaders (`OrganizationDataLoader`, `MachineDataLoader`, etc.) to batch database calls and prevent N+1 query problems.
+
+### 4. Repository Abstraction
+Base repository interfaces (`BaseUserRepository`, `BaseTenantRepository`) provide technology-agnostic contracts, with separate reactive (`openframe-data-mongo-reactive`) and synchronous (`openframe-data-mongo-sync`) implementations.
+
+### 5. Tool-Agnostic Event Model
+All tool events (MeshCentral, Tactical RMM, Fleet MDM) are normalized to `UnifiedEventType` through the stream processing pipeline, giving a consistent event vocabulary across all integrations.
+
+### 6. Extensibility via Processor Hooks
+Key lifecycle operations (agent registration, SSO configuration, user processing) expose processor interfaces (`AgentRegistrationProcessor`, `UserProcessor`) that can be replaced without modifying core logic.
+
+---
+
+## Reference Documentation
+
+For deeper dives into each module, see the generated reference documentation:
+
+- [API Service Core (HTTP + GraphQL)](./reference/architecture/api-service-core-http-and-graphql/api-service-core-http-and-graphql.md)
+- [Authorization Service Core](./reference/architecture/authorization-service-core/authorization-service-core.md)
+- [Gateway Service Core](./reference/architecture/gateway-service-core/gateway-service-core.md)
+- [Data Models and Repositories (Mongo)](./reference/architecture/data-models-and-repositories-mongo/data-models-and-repositories-mongo.md)
+- [Stream Processing (Kafka)](./reference/architecture/stream-processing-kafka/stream-processing-kafka.md)
+- [Management Service Core](./reference/architecture/management-service-core/management-service-core.md)
+- [Frontend Core (UI and Chat)](./reference/architecture/frontend-core-ui-and-chat/frontend-core-ui-and-chat.md)
+- [API Lib Contracts](./reference/architecture/api-lib-contracts/api-lib-contracts.md)
diff --git a/docs/development/contributing/guidelines.md b/docs/development/contributing/guidelines.md
new file mode 100644
index 000000000..fc9086305
--- /dev/null
+++ b/docs/development/contributing/guidelines.md
@@ -0,0 +1,247 @@
+# Contributing Guidelines
+
+Thank you for contributing to `openframe-oss-lib`! This document covers code style, branching strategy, commit conventions, and the pull request process.
+
+---
+
+## Getting Started
+
+Before contributing:
+
+1. Set up your [development environment](../setup/environment.md)
+2. Follow the [local development guide](../setup/local-development.md) to build and test locally
+3. Join the [OpenMSP Slack community](https://www.openmsp.ai/) for discussion and guidance
+
+> **All discussions, questions, and feature requests** are managed on [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA). There are no GitHub Issues or Discussions on this repository.
+
+---
+
+## Code Style and Conventions
+
+### Java Style
+
+The project follows standard Java conventions with some OpenFrame-specific patterns:
+
+| Convention | Rule |
+|-----------|------|
+| **Lombok** | Use `@Data`, `@Builder`, `@Slf4j`, `@RequiredArgsConstructor` freely |
+| **Immutability** | Prefer `final` fields; use Lombok `@Value` for pure DTOs |
+| **Package structure** | Follow existing `com.openframe.*` package hierarchy |
+| **Naming** | `*Service` for business logic, `*Repository` for data access, `*Controller` for REST, `*DataFetcher` for GraphQL |
+| **Exception handling** | Throw from the `openframe-exception` hierarchy (`NotFoundException`, `BadRequestException`, etc.) |
+| **Logging** | Use `@Slf4j` (Lombok); log at `DEBUG` for operations, `WARN`/`ERROR` for unexpected states |
+
+### Lombok Usage
+
+```java
+// Preferred patterns
+@Data                        // Getters, setters, equals, hashCode, toString
+@Builder                     // Builder pattern for DTOs
+@Value                       // Immutable value objects
+@Slf4j                       // Logger injection
+@RequiredArgsConstructor     // Constructor injection
+@NoArgsConstructor           // For JPA/MongoDB entities
+
+// Example service class
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class DeviceService {
+    private final MachineRepository machineRepository;
+    private final TenantIdProvider tenantIdProvider;
+
+    public Optional<Machine> findDevice(String machineId) {
+        log.debug("Looking up device: {}", machineId);
+        return machineRepository.findByMachineId(
+            machineId, tenantIdProvider.getTenantId()
+        );
+    }
+}
+```
+
+### GraphQL DataFetcher Conventions
+
+```java
+// Use @DgsComponent, @DgsQuery, @DgsMutation annotations
+// Follow existing DataFetcher naming patterns
+@DgsComponent
+public class DeviceDataFetcher {
+
+    @DgsQuery
+    public GenericConnection<DeviceNode> devices(
+            @InputArgument DeviceFilterInput filter,
+            @InputArgument ConnectionArgs connectionArgs) {
+        // ...
+    }
+}
+```
+
+### Multi-Tenancy Requirements
+
+**Every new domain document must:**
+
+```java
+// 1. Implement TenantScoped
+@Document(collection = "my_collection")
+public class MyDocument implements TenantScoped {
+    @Id
+    private String id;
+
+    private String tenantId;   // ← Required
+    // ...
+}
+
+// 2. Have a compound index including tenantId
+// (defined in MongoIndexConfig)
+```
+
+---
+
+## Branch Naming
+
+Use descriptive, hyphen-separated branch names with a type prefix:
+
+| Prefix | Use Case | Example |
+|--------|---------|---------|
+| `feat/` | New features | `feat/add-webhook-support` |
+| `fix/` | Bug fixes | `fix/notification-pagination-cursor` |
+| `chore/` | Maintenance tasks | `chore/upgrade-spring-boot-3.4` |
+| `refactor/` | Code refactoring | `refactor/device-service-split` |
+| `docs/` | Documentation changes | `docs/update-auth-flow-diagram` |
+| `test/` | Test additions/fixes | `test/add-ticket-repository-it` |
+
+```bash
+# Example: Create a feature branch
+git checkout -b feat/add-device-tagging-bulk-update
+
+# Example: Create a fix branch
+git checkout -b fix/cassandra-tenant-scope-query
+```
+
+---
+
+## Commit Message Format
+
+Follow the **Conventional Commits** specification:
+
+```text
+<type>(<scope>): <short description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | When to Use |
+|------|------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `chore` | Build, dependency, or tooling changes |
+| `refactor` | Code restructure without behavior change |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only changes |
+| `perf` | Performance improvements |
+| `ci` | CI/CD pipeline changes |
+
+### Scope Examples
+
+| Scope | Module |
+|-------|--------|
+| `core` | `openframe-core` |
+| `gateway` | `openframe-gateway-service-core` |
+| `auth` | `openframe-authorization-service-core` |
+| `api` | `openframe-api-service-core` |
+| `data` | `openframe-data-mongo-*` |
+| `stream` | `openframe-stream-service-core` |
+| `management` | `openframe-management-service-core` |
+| `frontend` | `openframe-frontend-core` |
+| `security` | `openframe-security-core` |
+
+### Examples
+
+```text
+feat(api): add bulk device tag assignment endpoint
+
+Adds GraphQL mutation for bulk assignment of tags to multiple
+devices in a single operation. Includes DataLoader optimization
+to prevent N+1 on tag resolution.
+
+fix(data): correct cursor encoding for notification pagination
+
+The cursor codec was using unstable field order causing
+inconsistent pagination results. Now uses deterministic
+JSON serialization.
+
+chore(deps): upgrade Spring Boot to 3.3.1
+
+Addresses CVE-2024-XXXX in spring-web.
+```
+
+---
+
+## Pull Request Process
+
+### Before Opening a PR
+
+- [ ] Branch is up to date with `main`
+- [ ] All unit tests pass: `mvn test`
+- [ ] Relevant integration tests pass: `mvn verify -pl <module>`
+- [ ] New code follows project conventions (Lombok, tenant scoping, etc.)
+- [ ] New domain documents implement `TenantScoped`
+- [ ] No secrets or hardcoded credentials in code
+- [ ] Javadoc added for new public APIs
+
+### PR Description Template
+
+```text
+## Summary
+Brief description of what this PR does and why.
+
+## Changes
+- List key changes
+- Affected modules: openframe-xxx, openframe-yyy
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] Manually tested against local stack
+
+## Related
+Link to Slack discussion or related PR (if any).
+```
+
+### Review Checklist
+
+Reviewers should verify:
+
+- [ ] Code follows OpenFrame conventions (naming, Lombok, tenant scoping)
+- [ ] New endpoints have appropriate `@PreAuthorize` or security config
+- [ ] No N+1 query problems (DataLoaders used for related entity loading)
+- [ ] Integration tests cover the happy path
+- [ ] Error cases return appropriate exceptions from `openframe-exception`
+- [ ] Multi-tenant isolation maintained (tenantId filters present)
+
+---
+
+## Module Addition Guidelines
+
+When adding a new module to `openframe-oss-lib`:
+
+1. **Add to parent `pom.xml`** in the `<modules>` section
+2. **Inherit from parent**: `<parent>openframe-oss-lib</parent>`
+3. **Add to `<dependencyManagement>`** in parent POM with `${revision}` version
+4. **Follow naming convention**: `openframe-<domain>-<layer>`
+5. **Include a `README.md`** describing the module's purpose
+6. **Write at least one unit test** before the first PR
+
+---
+
+## Getting Help
+
+- **Questions**: Ask in [OpenMSP Slack](https://www.openmsp.ai/) `#dev-questions`
+- **Feature Ideas**: Share in `#roadmap` channel
+- **Bug Reports**: Report in `#bugs` channel
+
+We review contributions regularly. Thank you for helping build the open-source MSP platform of the future!
diff --git a/docs/development/security/README.md b/docs/development/security/README.md
new file mode 100644
index 000000000..7a04b1ede
--- /dev/null
+++ b/docs/development/security/README.md
@@ -0,0 +1,283 @@
+# Security Best Practices
+
+This guide covers security architecture, authentication and authorization patterns, secrets management, and secure development guidelines for `openframe-oss-lib`.
+
+[![OpenFrame v0.3.0 - Remote File Manager & Unified Authentication Architecture](https://img.youtube.com/vi/mibUHvcVIHs/maxresdefault.jpg)](https://www.youtube.com/watch?v=mibUHvcVIHs)
+
+---
+
+## Authentication and Authorization Architecture
+
+### Overview
+
+OpenFrame implements a **multi-layered security model** across three service tiers:
+
+```mermaid
+flowchart TD
+    Client["Client (Browser / Agent)"]
+    Gateway["Gateway Service Core\n(JWT Validation + Role Enforcement)"]
+    Auth["Authorization Service Core\n(OAuth2 / OIDC Token Issuance)"]
+    API["API Service Core\n(OAuth2 Resource Server)"]
+    ExternalAPI["External API\n(API Key + Rate Limiting)"]
+
+    Client -->|"JWT"| Gateway
+    Client -->|"API Key"| ExternalAPI
+    Gateway -->|"Validated Request"| API
+    Gateway --> Auth
+    ExternalAPI -->|"Rate-limited Request"| API
+    Auth -->|"Tenant-scoped JWT"| Client
+```
+
+### Layer 1: Authorization Service (Token Issuance)
+
+The `openframe-authorization-service-core` module handles:
+- **OAuth2/OIDC Authorization Server** (Spring Authorization Server 1.3.1)
+- **Per-tenant RSA key pair generation** for JWT signing
+- **SSO integration** (Google, Microsoft) via dynamic client registration
+- **Password reset** and invitation flows
+- **Tenant isolation** via `TenantContextFilter` (ThreadLocal)
+
+**Custom JWT Claims:**
+```text
+tenant_id  – Tenant identifier
+userId     – Platform user ID
+roles      – User roles (OWNER implies ADMIN)
+```
+
+### Layer 2: Gateway (Token Validation)
+
+The `openframe-gateway-service-core` module:
+- Validates JWTs using **per-tenant RSA public keys** (Caffeine cached)
+- Enforces **role-based access** (`ROLE_ADMIN`, `ROLE_AGENT`, `SCOPE_*`)
+- Supports **multi-source token extraction**: cookie → header → query param
+- Applies **CORS policies**
+- Enforces **rate limits** on external API access
+
+### Layer 3: API Service (Resource Protection)
+
+The `openframe-api-service-core` module:
+- Acts as an **OAuth2 Resource Server**
+- Injects `AuthPrincipal` via `@AuthenticationPrincipal`
+- Caches JWT decoders by issuer (Caffeine)
+- Does **not** re-validate tokens — relies on Gateway enforcement
+
+---
+
+## API Key Security
+
+External API access uses API keys with rate limiting:
+
+```mermaid
+flowchart TD
+    Req["External Request to /external-api/**"]
+    Check{"X-API-Key header present?"}
+    Validate["Validate API Key in DB"]
+    Rate{"Rate limit check"}
+    Forward["Forward to API service"]
+
+    Req --> Check
+    Check -->|"No"| Reject401["401 Unauthorized"]
+    Check -->|"Yes"| Validate
+    Validate -->|"Invalid"| Reject401
+    Validate -->|"Valid"| Rate
+    Rate -->|"Exceeded"| Reject429["429 Too Many Requests"]
+    Rate -->|"OK"| Forward
+```
+
+**Rate limit headers returned:**
+- `X-RateLimit-Limit-Minute`
+- `X-RateLimit-Remaining-Minute`
+- `X-RateLimit-Limit-Hour`
+- `X-RateLimit-Remaining-Hour`
+
+**Best Practices for API Keys:**
+- Rotate API keys regularly using the `ApiKeyController`
+- Store API keys encrypted — the `openframe-core-crypto` module provides `EncryptionService` for AES encryption
+- Never log API key values — only log key IDs
+- Use `APIKeyType` to scope keys appropriately
+
+---
+
+## Secrets Management
+
+### Environment Variables vs. Configuration
+
+Never hardcode secrets in source code or configuration files. Always use environment variables:
+
+```bash
+# ✅ CORRECT: Use environment variables
+export SPRING_DATA_MONGODB_URI=mongodb://user:secret@host/db
+
+# ❌ WRONG: Hardcoded in application.yml
+# spring.data.mongodb.uri: mongodb://user:hardcoded@host/db
+```
+
+### Encryption at Rest
+
+The `openframe-core-crypto` module provides `EncryptionService` for encrypting sensitive data before storing in MongoDB:
+
+```java
+// Use EncryptionService to encrypt sensitive values before storage
+// Example pattern used for tool credentials and RSA private keys
+@Autowired
+private EncryptionService encryptionService;
+
+String encrypted = encryptionService.encrypt(sensitiveValue);
+String decrypted = encryptionService.decrypt(encrypted);
+```
+
+**Fields encrypted in MongoDB:**
+- RSA private keys in `TenantKey` documents
+- Tool credentials in `ToolCredentials`
+- OAuth client secrets
+
+### Key Management
+
+Per-tenant RSA keys are managed by `TenantKeyService`:
+- Private keys are **encrypted before storage** using `EncryptionService`
+- Public keys are served via the JWKS endpoint for JWT validation
+- Keys can be independently rotated per tenant without affecting other tenants
+
+---
+
+## Input Validation and Sanitization
+
+### Jakarta Validation
+
+All API inputs use Jakarta Bean Validation constraints:
+
+```java
+// Example from RunCommandInput
+@NotNull
+private String machineId;
+
+@NotNull
+private String command;
+
+@Positive
+private Integer timeoutSeconds;
+```
+
+### Tenant Domain Validation
+
+The `openframe-core` module provides custom validators:
+
+```java
+// @TenantDomain validates slug format for tenant identifiers
+// @ValidEmail validates email addresses consistently
+```
+
+### GraphQL Input Validation
+
+GraphQL mutations validate inputs using the same Jakarta constraints through Spring's validation integration. Invalid inputs return structured `MutationError` responses rather than exceptions.
+
+---
+
+## Multi-Tenant Isolation
+
+**Critical principle:** All data access must be scoped to the current tenant.
+
+```java
+// TenantScoped documents always include tenantId
+@Document(collection = "devices")
+public class Machine implements TenantScoped {
+    private String tenantId;
+    // ...
+}
+
+// Repositories automatically filter by tenantId
+// DefaultTenantIdProvider reads from TENANT_ID env var
+// or falls back to "oss" for OSS single-tenant mode
+```
+
+**Security checklist for new repositories:**
+- ✅ Document implements `TenantScoped`
+- ✅ Repository queries include `tenantId` filter
+- ✅ Custom repository implementations use `TenantIdProvider`
+- ✅ Compound index includes `{ tenantId: 1, ... }`
+
+---
+
+## SSO Security
+
+SSO flows (Google, Microsoft) use secure cookie-based state passing:
+
+- `SsoCookieCodec` encrypts SSO state cookies
+- `SsoAuthorizationRequestResolver` validates OIDC state parameters
+- Dynamic client registration uses `DynamicClientRegistrationRepository` to prevent cross-tenant SSO contamination
+
+**SSO Security Checklist:**
+- ✅ Validate `state` parameter on all OAuth2 callbacks
+- ✅ Use HTTP-only, Secure cookies for session state
+- ✅ Scope SSO client registrations to specific tenants
+- ✅ Never expose client secrets in frontend code
+
+---
+
+## Common Vulnerability Mitigations
+
+| Vulnerability | Mitigation in OpenFrame |
+|--------------|------------------------|
+| **JWT Forgery** | Per-tenant RSA signing; issuer validated; strict decoder caching |
+| **Cross-Tenant Data Leakage** | `tenantId` filter on all queries; `TenantContextFilter` on all requests |
+| **API Key Brute Force** | Rate limiting per minute/hour/day at gateway level |
+| **CSRF** | Stateless JWT-based auth; `OriginSanitizerFilter` in gateway |
+| **Injection** | MongoDB query uses Spring Data criteria, not raw queries; strict input validation |
+| **Secret Exposure** | Encryption at rest for private keys and credentials; env var management |
+| **Unauthorized Tool Access** | Agent auth (`ROLE_AGENT`) separate from admin auth (`ROLE_ADMIN`) |
+
+---
+
+## Security Testing Guidelines
+
+### Unit Testing Security Logic
+
+```java
+// Use TestAuthenticationManager for mocking auth in tests
+// Located in: openframe-client-core/src/test/...
+@Autowired
+private TestAuthenticationManager testAuthenticationManager;
+```
+
+### Integration Testing Auth Flows
+
+The `openframe-test-service-core` module provides full auth flow helpers:
+
+```java
+// AuthFlow, AuthFlowOSS, AuthFlowSAAS provide test auth flows
+// Use AuthHelper for test authentication setup
+AuthParts auth = authFlow.loginAsAdmin();
+```
+
+### Security Code Review Checklist
+
+Before merging any security-related code:
+
+- [ ] No secrets or credentials in source code
+- [ ] All API inputs validated with Jakarta constraints
+- [ ] New endpoints have appropriate role restrictions
+- [ ] New MongoDB documents implement `TenantScoped`
+- [ ] Sensitive fields encrypted before storage
+- [ ] New API keys scoped to minimum required permissions
+- [ ] SSO state parameters validated in callbacks
+- [ ] Rate limiting applied to public-facing endpoints
+
+---
+
+## Environment Variables and Secrets Management
+
+> **Never commit secrets to version control.** Use environment variables, secret management systems (Vault, AWS Secrets Manager, Kubernetes Secrets), or `.env` files that are excluded from Git.
+
+```bash
+# Add to .gitignore
+.env
+.env.local
+*.secrets
+
+# Use descriptive names for secret environment variables
+JWT_SIGNING_KEY_SECRET=...
+MONGODB_PASSWORD=...
+REDIS_AUTH_PASSWORD=...
+```
+
+For questions or to report security issues, contact the team via [OpenMSP Slack](https://www.openmsp.ai/).
diff --git a/docs/development/setup/environment.md b/docs/development/setup/environment.md
new file mode 100644
index 000000000..e104430ff
--- /dev/null
+++ b/docs/development/setup/environment.md
@@ -0,0 +1,224 @@
+# Development Environment Setup
+
+This guide covers setting up a complete development environment for working with `openframe-oss-lib`.
+
+---
+
+## Required Tools
+
+Install the following tools before beginning:
+
+| Tool | Version | Installation |
+|------|---------|-------------|
+| **JDK 21** | 21 (LTS) | [Adoptium](https://adoptium.net/) / [SDKMAN](https://sdkman.io/) |
+| **Apache Maven** | 3.8+ | [maven.apache.org](https://maven.apache.org/download.cgi) |
+| **Git** | 2.x+ | [git-scm.com](https://git-scm.com/) |
+| **Docker Desktop** | 24+ | [docker.com](https://www.docker.com/products/docker-desktop/) |
+| **Node.js** | 18+ | [nodejs.org](https://nodejs.org/) (for frontend-core) |
+
+---
+
+## Java Environment Setup
+
+### Using SDKMAN (Recommended)
+
+[SDKMAN](https://sdkman.io/) makes managing multiple JDK versions easy:
+
+```bash
+# Install SDKMAN
+curl -s "https://get.sdkman.io" | bash
+source "$HOME/.sdkman/bin/sdkman-init.sh"
+
+# Install Java 21 (Temurin)
+sdk install java 21.0.4-tem
+
+# Set as default
+sdk default java 21.0.4-tem
+
+# Verify
+java -version
+```
+
+### Using System Package Manager
+
+```bash
+# macOS with Homebrew
+brew install openjdk@21
+
+# Ubuntu / Debian
+sudo apt-get install openjdk-21-jdk
+
+# Fedora / RHEL
+sudo dnf install java-21-openjdk-devel
+```
+
+---
+
+## Maven Setup
+
+```bash
+# macOS
+brew install maven
+
+# Ubuntu / Debian
+sudo apt-get install maven
+
+# Verify
+mvn -version
+```
+
+### Configure GitHub Packages Access
+
+Edit `~/.m2/settings.xml` (create it if it doesn't exist):
+
+```xml
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+          http://maven.apache.org/xsd/settings-1.0.0.xsd">
+    <servers>
+        <server>
+            <id>github</id>
+            <username>YOUR_GITHUB_USERNAME</username>
+            <password>YOUR_GITHUB_PERSONAL_ACCESS_TOKEN</password>
+        </server>
+    </servers>
+</settings>
+```
+
+> Create a GitHub PAT with `read:packages` and `write:packages` scopes at [github.com/settings/tokens](https://github.com/settings/tokens).
+
+---
+
+## IDE Setup
+
+### IntelliJ IDEA (Recommended)
+
+1. **Open the project**: File → Open → select the root `pom.xml`
+2. **Enable annotation processing**: Settings → Build → Compiler → Annotation Processors → ✅ Enable annotation processing
+3. **Install recommended plugins**:
+
+| Plugin | Purpose |
+|--------|---------|
+| **Lombok** | Required for `@Data`, `@Builder`, `@Slf4j` annotations |
+| **Spring Boot** | Run configurations and property completion |
+| **GraphQL** | Schema syntax highlighting |
+| **Docker** | Container management |
+
+**Recommended Settings for IntelliJ:**
+
+```text
+Settings → Build, Execution, Deployment → Build Tools → Maven
+    ✓ Use plugin registry
+    Maven home path: [your Maven installation]
+    User settings file: ~/.m2/settings.xml
+
+Settings → Editor → Code Style → Java
+    Use project code style (if .editorconfig is present)
+```
+
+### VS Code
+
+Install the **Extension Pack for Java**:
+
+```bash
+code --install-extension vscjava.vscode-java-pack
+code --install-extension pivotal.vscode-spring-boot
+```
+
+Add to your workspace `settings.json`:
+
+```json
+{
+    "java.configuration.updateBuildConfiguration": "automatic",
+    "java.compile.nullAnalysis.mode": "automatic",
+    "java.jdt.ls.java.home": "/path/to/java21"
+}
+```
+
+---
+
+## Docker Setup
+
+Docker is required for integration tests (Testcontainers) and local infrastructure:
+
+```bash
+# Verify Docker is running
+docker info
+
+# Verify Docker Compose
+docker compose version
+
+# Test Testcontainers connectivity
+docker pull mongo:6
+docker pull redis:7
+```
+
+> On **Linux**, add your user to the `docker` group to avoid `sudo`:
+> ```bash
+> sudo usermod -aG docker $USER
+> newgrp docker
+> ```
+
+---
+
+## Node.js Setup (Frontend Development)
+
+If working on the `openframe-frontend-core` module:
+
+```bash
+# Install Node.js via nvm (recommended)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 18
+nvm use 18
+
+# Verify
+node --version
+npm --version
+```
+
+---
+
+## Environment Variables Reference
+
+For local development, set these shell environment variables. Add them to your `~/.zshrc`, `~/.bashrc`, or equivalent:
+
+```bash
+# OpenFrame OSS - Single tenant mode
+export TENANT_ID=oss
+
+# MongoDB
+export SPRING_DATA_MONGODB_URI=mongodb://localhost:27017/openframe
+
+# Redis
+export SPRING_REDIS_HOST=localhost
+export SPRING_REDIS_PORT=6379
+
+# Kafka
+export SPRING_KAFKA_BOOTSTRAP_SERVERS=localhost:9092
+
+# NATS
+export NATS_SERVER_URL=nats://localhost:4222
+```
+
+> These are only needed when running full service instances locally. Unit tests and most module tests use Testcontainers and do **not** require these.
+
+---
+
+## Verification Checklist
+
+Run these commands to confirm your environment is ready:
+
+```bash
+# Java 21
+java -version 2>&1 | grep "21"
+
+# Maven 3.8+
+mvn -version | grep "Apache Maven 3"
+
+# Docker running
+docker ps
+
+# GitHub Packages accessible
+mvn dependency:resolve -pl openframe-core -q && echo "Maven packages OK"
+```
diff --git a/docs/development/setup/local-development.md b/docs/development/setup/local-development.md
new file mode 100644
index 000000000..df5f1d27e
--- /dev/null
+++ b/docs/development/setup/local-development.md
@@ -0,0 +1,242 @@
+# Local Development Guide
+
+This guide walks you through setting up the `openframe-oss-lib` project for local development, including building modules, running tests, and debugging.
+
+---
+
+## Clone and Initial Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/flamingo-stack/openframe-oss-lib.git
+cd openframe-oss-lib
+
+# Verify Java version
+java -version
+# Should show: openjdk version "21.x.x"
+```
+
+---
+
+## Building the Project
+
+### Full Build (All Modules, Skip Tests)
+
+```bash
+mvn install -DskipTests
+```
+
+This installs all modules to your local Maven cache (`~/.m2/repository`), making them available as dependencies for other local projects.
+
+### Build a Specific Module
+
+```bash
+# Build only the core module
+mvn install -pl openframe-core -DskipTests
+
+# Build a module and its dependencies
+mvn install -pl openframe-api-lib -am -DskipTests
+
+# Build multiple modules at once
+mvn install -pl openframe-core,openframe-exception,openframe-data-mongo-common -DskipTests
+```
+
+### Clean Build
+
+```bash
+# Clean all build outputs and rebuild
+mvn clean install -DskipTests
+```
+
+---
+
+## Running Tests
+
+### Unit Tests
+
+Unit tests run without Docker and execute quickly:
+
+```bash
+# Run tests for a specific module
+mvn test -pl openframe-core
+mvn test -pl openframe-exception
+mvn test -pl openframe-data-pinot
+
+# Run all unit tests across all modules
+mvn test
+```
+
+### Integration Tests
+
+Integration tests use **Testcontainers** and require Docker:
+
+```bash
+# Run integration tests for MongoDB sync module
+mvn verify -pl openframe-data-mongo-sync
+
+# Run integration tests for NATS module
+mvn verify -pl openframe-data-nats
+
+# Run integration tests for API service core
+mvn verify -pl openframe-api-service-core
+
+# Run all integration tests (slow - runs all module verifications)
+mvn verify
+```
+
+> **Testcontainers** automatically pulls and starts Docker containers for MongoDB, Redis, NATS, and other dependencies. No manual Docker Compose setup is needed for tests.
+
+### Run a Specific Test Class
+
+```bash
+# Run a specific test class
+mvn test -pl openframe-data-pinot -Dtest=PinotQueryBuilderTest
+
+# Run a specific test method
+mvn test -pl openframe-api-service-core -Dtest=CommandDispatchServiceTest#testDispatch
+```
+
+---
+
+## Module Development Workflow
+
+### Working on a Data Module
+
+```bash
+cd openframe-data-mongo-sync
+
+# Run all tests for this module
+mvn test
+
+# Run only integration tests
+mvn verify -Dsurefire.skip=true
+
+# Run only unit tests (skip integration)
+mvn test -Dfailsafe.skip=true
+```
+
+### Working on the API Service Core
+
+```bash
+cd openframe-api-service-core
+
+# Build dependencies first
+mvn install -pl openframe-core,openframe-exception,openframe-data-mongo-common,\
+openframe-data-mongo-sync,openframe-api-lib,openframe-security-core \
+-am -DskipTests
+
+# Then run API service core tests
+mvn test -pl openframe-api-service-core
+```
+
+### Working on Frontend Core
+
+```bash
+cd openframe-frontend-core
+
+# Install Node.js dependencies
+npm install
+
+# Start Storybook for component development
+npm run storybook
+
+# Run unit tests
+npm run test
+
+# Build the library
+npm run build
+```
+
+---
+
+## Debug Configuration
+
+### IntelliJ IDEA Debug
+
+1. Open **Run/Debug Configurations**
+2. Add a new **JUnit** configuration
+3. Set:
+   - **Test kind**: Class
+   - **Class**: `com.openframe.data.mongo.sync.SomeTest`
+   - **Working directory**: `$MODULE_WORKING_DIR$`
+4. Add **JVM options** for Testcontainers if needed:
+   ```text
+   -Dtestcontainers.reuse.enable=true
+   ```
+
+### Enable Testcontainers Container Reuse
+
+To speed up repeated integration test runs by reusing Docker containers:
+
+```bash
+# Create or edit ~/.testcontainers.properties
+echo "testcontainers.reuse.enable=true" >> ~/.testcontainers.properties
+```
+
+---
+
+## CI-Friendly Versioning
+
+The project uses Maven's CI-friendly `${revision}` property. The version is defined in the parent POM:
+
+```xml
+<properties>
+    <revision>6.0.10</revision>
+</properties>
+```
+
+The `flatten-maven-plugin` resolves this during the `process-resources` phase. When building:
+
+```bash
+# Override version for a specific build
+mvn install -Drevision=6.0.11-SNAPSHOT -DskipTests
+```
+
+---
+
+## Useful Maven Commands Reference
+
+```bash
+# Show effective POM for a module
+mvn help:effective-pom -pl openframe-core
+
+# Show dependency tree for a module
+mvn dependency:tree -pl openframe-api-service-core
+
+# Check for dependency updates
+mvn versions:display-dependency-updates -pl openframe-core
+
+# Validate the POM files
+mvn validate
+
+# Show all modules in reactor
+mvn help:evaluate -Dexpression=project.modules
+```
+
+---
+
+## Local Publishing
+
+To publish artifacts to the GitHub Maven Package Registry (for maintainers with write access):
+
+```bash
+# Publish all modules
+mvn deploy -DskipTests
+
+# Publish a specific module
+mvn deploy -pl openframe-core -DskipTests
+```
+
+> This requires GitHub token configuration in `~/.m2/settings.xml` with `write:packages` scope.
+
+---
+
+## Common Issues
+
+| Problem | Solution |
+|---------|---------|
+| `Compilation failure: cannot find symbol` | Ensure annotation processing is enabled in your IDE; run `mvn generate-sources` |
+| `Docker not available` in tests | Ensure Docker daemon is running: `docker info` |
+| `Unable to connect to GitHub Packages` | Check `~/.m2/settings.xml` for correct `id=github` server entry |
+| `revision` placeholder in deployed POM | The `flatten-maven-plugin` must run — use `mvn install` not `mvn package` |
+| Out of memory during build | Increase Maven heap: `export MAVEN_OPTS="-Xmx2g"` |
diff --git a/docs/development/testing/README.md b/docs/development/testing/README.md
new file mode 100644
index 000000000..a51b5f72e
--- /dev/null
+++ b/docs/development/testing/README.md
@@ -0,0 +1,303 @@
+# Testing Overview
+
+`openframe-oss-lib` has a comprehensive testing strategy covering unit tests, integration tests with Testcontainers, and end-to-end test infrastructure. This guide explains the test structure, how to run tests, and how to write new tests.
+
+---
+
+## Test Structure
+
+Tests are organized into two main categories across all modules:
+
+```mermaid
+graph LR
+    Tests["Tests in openframe-oss-lib"]
+    Unit["Unit Tests\n(src/test/java)"]
+    Integration["Integration Tests\n(src/test/java - *IT.java)"]
+    Infra["Test Infrastructure\nopenframe-test-service-core"]
+
+    Tests --> Unit
+    Tests --> Integration
+    Tests --> Infra
+```
+
+### Unit Tests
+
+- Located in `src/test/java/` following the pattern `*Test.java`
+- No infrastructure dependencies (no Docker, no database)
+- Fast execution (milliseconds)
+- Configured via Maven Surefire plugin
+
+### Integration Tests
+
+- Located in `src/test/java/` following the pattern `*IT.java`
+- Use **Testcontainers** for real infrastructure (MongoDB, Redis, NATS)
+- Slower execution (seconds to minutes)
+- Configured via Maven Failsafe plugin
+- Run with `mvn verify`
+
+### Test Infrastructure Module
+
+The `openframe-test-service-core` module provides a shared test harness for end-to-end API testing:
+
+| Component | Purpose |
+|-----------|---------|
+| `AuthFlow`, `AuthFlowOSS`, `AuthFlowSAAS` | Complete auth flow helpers |
+| `AuthHelper`, `RequestSpecHelper` | Authentication and REST test setup |
+| `*Api` classes (`DeviceApi`, `TicketApi`, etc.) | Typed API client helpers |
+| `*Generator` classes | Test data factories |
+| `*Page` classes | Page Object Model for UI tests |
+| `MongoDB`, `Redis` | Test infrastructure containers |
+
+---
+
+## Running Tests
+
+### Run Unit Tests Only
+
+```bash
+# Run all unit tests across all modules
+mvn test
+
+# Run unit tests for a specific module
+mvn test -pl openframe-core
+mvn test -pl openframe-exception
+mvn test -pl openframe-data-pinot
+mvn test -pl openframe-api-service-core
+```
+
+### Run Integration Tests
+
+```bash
+# Run integration tests for a specific module (requires Docker)
+mvn verify -pl openframe-data-mongo-sync
+mvn verify -pl openframe-data-nats
+mvn verify -pl openframe-api-service-core
+
+# Run all integration tests
+mvn verify
+```
+
+### Run a Specific Test
+
+```bash
+# Run a single test class
+mvn test -pl openframe-data-pinot -Dtest=PinotQueryBuilderTest
+
+# Run a specific test method
+mvn test -pl openframe-api-service-core \
+  -Dtest=CommandDispatchServiceTest#testDispatch
+
+# Run tests matching a pattern
+mvn test -pl openframe-data-mongo-sync -Dtest="Notification*"
+```
+
+### Skip Tests
+
+```bash
+# Skip all tests during build
+mvn install -DskipTests
+
+# Skip only integration tests
+mvn install -Dfailsafe.skip=true
+
+# Skip only unit tests
+mvn install -Dsurefire.skip=true
+```
+
+---
+
+## Test Configuration
+
+### Maven Surefire (Unit Tests)
+
+The parent POM configures Surefire to include:
+
+```xml
+<includes>
+    <include>**/Test*.java</include>
+    <include>**/*Test.java</include>
+    <include>**/*Tests.java</include>
+    <include>**/*TestCase.java</include>
+    <include>**/*IT.java</include>
+</includes>
+```
+
+### Testcontainers
+
+Integration tests use Testcontainers to start real infrastructure automatically. Base classes handle container lifecycle:
+
+```java
+// Example: BaseMongoIntegrationTest (openframe-data-mongo-sync)
+// Provides: @Testcontainers, MongoDB container, Spring context
+public abstract class BaseMongoIntegrationTest {
+    // MongoDB container started once per test class
+    // Spring Boot test context shared for speed
+}
+```
+
+**Speed Up Integration Tests:**
+
+```bash
+# Enable container reuse across test runs
+echo "testcontainers.reuse.enable=true" >> ~/.testcontainers.properties
+```
+
+---
+
+## Writing New Tests
+
+### Unit Test Example
+
+```java
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+class SlugUtilTest {
+
+    @Test
+    void shouldConvertNameToSlug() {
+        // Given
+        String name = "My MSP Organization";
+
+        // When
+        String slug = SlugUtil.toSlug(name);
+
+        // Then
+        assertThat(slug).isEqualTo("my-msp-organization");
+    }
+}
+```
+
+### Integration Test Example (MongoDB)
+
+```java
+import org.springframework.boot.test.context.SpringBootTest;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+@SpringBootTest
+@Testcontainers
+class OrganizationRepositoryIT extends BaseMongoIntegrationTest {
+
+    @Autowired
+    private OrganizationRepository organizationRepository;
+
+    @Test
+    void shouldSaveAndRetrieveOrganization() {
+        // Given
+        Organization org = new Organization();
+        org.setTenantId("oss");
+        org.setName("Test MSP");
+
+        // When
+        Organization saved = organizationRepository.save(org);
+
+        // Then
+        assertThat(saved.getId()).isNotNull();
+        assertThat(organizationRepository.findById(saved.getId()))
+            .isPresent()
+            .hasValueSatisfying(o -> assertThat(o.getName()).isEqualTo("Test MSP"));
+    }
+}
+```
+
+### GraphQL Integration Test Example
+
+```java
+// From openframe-api-service-core integration tests
+// Uses NotificationDataFetcherIT pattern:
+@SpringBootTest
+class MyDataFetcherIT extends BaseMongoIntegrationTest {
+
+    @Autowired
+    private DgsQueryExecutor dgsQueryExecutor;
+
+    @Test
+    void shouldFetchDevices() {
+        String query = """
+            query {
+              devices(first: 10) {
+                edges {
+                  node { id hostname }
+                }
+              }
+            }
+            """;
+
+        // Execute with mock authentication context
+        var result = dgsQueryExecutor.executeAndExtractJsonPath(
+            query, "$.data.devices.edges[*].node.hostname"
+        );
+
+        assertThat(result).isNotNull();
+    }
+}
+```
+
+---
+
+## Test Data Generators
+
+The `openframe-test-service-core` module provides ready-to-use data generators:
+
+```java
+// Generate test data for API tests
+OrganizationGenerator.createRequest()  // → CreateOrganizationRequest
+TicketGenerator.createInput()          // → CreateTicketInput
+DeviceGenerator.machine()              // → Machine document
+AuthGenerator.credentials()            // → test credentials
+```
+
+---
+
+## Notification Integration Tests
+
+The notification system has dedicated performance and integration tests:
+
+| Test | Purpose |
+|------|---------|
+| `NotificationLoadTestIT` | Load testing notification reads |
+| `NotificationReadStateIndexUsageIT` | Validates index usage |
+| `CustomNotificationRepositoryPaginationIT` | Cursor pagination correctness |
+| `NotificationReadStateServiceIT` | Read/unread state management |
+
+These tests also serve as **performance benchmarks** using `PerfResultRecorder` and `MeasurementStats`.
+
+---
+
+## Frontend Tests (openframe-frontend-core)
+
+```bash
+cd openframe-frontend-core
+
+# Run all unit tests
+npm run test
+
+# Run tests in watch mode
+npm run test -- --watch
+
+# Run with coverage
+npm run test -- --coverage
+```
+
+Frontend tests use **Vitest** with the configuration in `vitest.config.ts`.
+
+---
+
+## Coverage Requirements
+
+While formal coverage thresholds are not enforced by default, follow these guidelines:
+
+| Type | Target Coverage |
+|------|----------------|
+| Domain services | 80%+ unit test coverage |
+| Utility classes | 90%+ unit test coverage |
+| Repository custom implementations | Integration test coverage |
+| Controllers / DataFetchers | Integration test coverage |
+
+---
+
+## CI Test Execution
+
+Tests run automatically in CI. The Surefire configuration includes `*IT.java` in unit test scanning, but integration tests that require Testcontainers run in the `verify` phase via Failsafe.
+
+For questions about test failures or patterns, join the [OpenMSP Slack community](https://www.openmsp.ai/).
diff --git a/docs/getting-started/.gitignore b/docs/getting-started/.gitignore
new file mode 100644
index 000000000..a5d01be52
--- /dev/null
+++ b/docs/getting-started/.gitignore
@@ -0,0 +1,7 @@
+# VoltAgent temp files
+temp/
+
+# JSON intermediate files (except schema/config)
+*.json
+!*-schema.json
+!*-config.json
diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md
new file mode 100644
index 000000000..efe5f32f2
--- /dev/null
+++ b/docs/getting-started/first-steps.md
@@ -0,0 +1,142 @@
+# First Steps
+
+After cloning and building `openframe-oss-lib`, here are the 5 key things to do to start being productive with the codebase.
+
+---
+
+## 1. Explore the Module Structure
+
+The repository is a Maven multi-module project. Start by understanding which modules are available:
+
+```bash
+# List all modules from the parent POM
+mvn help:evaluate -Dexpression=project.modules -q -DforceStdout
+```
+
+Alternatively, review the top-level `pom.xml` — it lists all 29+ modules under the `<modules>` section. Key modules to know first:
+
+| Module | What to Explore |
+|--------|----------------|
+| `openframe-core` | Shared utilities, validation annotations, pagination |
+| `openframe-exception` | Exception hierarchy and `ErrorCode` enum |
+| `openframe-data-mongo-common` | Core domain document models (User, Device, Ticket, etc.) |
+| `openframe-api-lib` | Shared API contract DTOs and filters |
+| `openframe-security-core` | JWT configuration and `AuthPrincipal` |
+
+---
+
+## 2. Understand the Domain Models
+
+The `openframe-data-mongo-common` module defines all core MongoDB documents. Spend time reviewing these documents to understand the data model:
+
+```bash
+# Browse the document models
+ls openframe-data-mongo-common/src/main/java/com/openframe/data/document/
+```
+
+Key documents:
+- `device/Machine.java` – Physical device / endpoint representation
+- `ticket/Ticket.java` – Support ticket with lifecycle states
+- `organization/Organization.java` – Client organization record
+- `user/User.java` + `auth/AuthUser.java` – Platform user and auth data
+- `notification/Notification.java` – In-platform notification system
+- `tool/IntegratedTool.java` – MSP tool integration record
+
+> All domain documents implement `TenantScoped`, meaning every query includes a `tenantId` filter for multi-tenant isolation.
+
+---
+
+## 3. Run the Module Tests
+
+Integration tests use **Testcontainers** — they spin up real MongoDB, Redis, and NATS instances in Docker automatically. No manual setup required.
+
+```bash
+# Run unit tests for core modules (fast, no Docker needed)
+mvn test -pl openframe-core
+mvn test -pl openframe-exception
+mvn test -pl openframe-api-lib
+
+# Run integration tests for MongoDB sync (requires Docker)
+mvn verify -pl openframe-data-mongo-sync
+
+# Run integration tests for NATS module (requires Docker)
+mvn verify -pl openframe-data-nats
+```
+
+> **Tip:** Look at integration test base classes like `BaseMongoIntegrationTest` in `openframe-data-mongo-sync` to understand the test harness patterns used across the project.
+
+---
+
+## 4. Explore the API Contracts
+
+The `openframe-api-lib` module defines the contracts used by all API services. Understanding these DTOs is essential before building any service:
+
+```bash
+ls openframe-api-lib/src/main/java/com/openframe/api/dto/
+```
+
+Key contract categories:
+
+| Package | Contents |
+|---------|---------|
+| `dto/device/` | Device filter criteria and filter options |
+| `dto/organization/` | Organization CRUD request/response |
+| `dto/command/` | Remote command dispatch contracts |
+| `dto/script/` | Script management inputs and responses |
+| `dto/knowledgebase/` | Knowledge base article management |
+| `dto/shared/` | Relay pagination: `ConnectionArgs`, `CursorCodec` |
+| `service/` | Service interfaces: `DeviceService`, `ToolService`, etc. |
+
+---
+
+## 5. Join the Community and Get Help
+
+OpenFrame is developed in the open. The primary community channel is **Slack**:
+
+[![Join OpenMSP Slack](https://img.shields.io/badge/Slack-OpenMSP-blue?logo=slack)](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+
+All discussions, questions, and feature requests are managed on [OpenMSP Slack](https://www.openmsp.ai/).
+
+Also explore:
+- **GitHub Repository**: [flamingo-stack/openframe-oss-lib](https://github.com/flamingo-stack/openframe-oss-lib)
+- **Flamingo Platform**: [flamingo.run](https://flamingo.run)
+- **OpenFrame Platform**: [openframe.ai](https://openframe.ai)
+
+---
+
+## Common Initial Configuration
+
+### OSS Single-Tenant Mode
+
+For OSS deployments (single tenant), the minimum configuration is:
+
+```bash
+# Set environment variables for single-tenant OSS mode
+export TENANT_ID=oss
+export SPRING_DATA_MONGODB_URI=mongodb://localhost:27017/openframe
+export SPRING_REDIS_HOST=localhost
+```
+
+### Multi-Tenant SaaS Mode
+
+For multi-tenant SaaS deployments, the `TENANT_ID` environment variable is resolved per-request by the `DefaultTenantIdProvider`, and each tenant has isolated MongoDB data.
+
+---
+
+## Explore the Reference Documentation
+
+The reference documentation (generated by CodeWiki) provides detailed architectural information for each major module. Check these resources:
+
+- [Architecture Overview](../development/architecture/README.md) — high-level system diagram
+- [Reference Docs](./reference/architecture/README.md) — module-by-module deep dives
+
+---
+
+## Next Steps
+
+After completing your first steps:
+
+- Set up your [Development Environment](../development/setup/environment.md) for contributing
+- Read the [Local Development Guide](../development/setup/local-development.md)
+- Review the [Architecture README](../development/architecture/README.md) to understand data flows
+- Check [Contributing Guidelines](../development/contributing/guidelines.md) before submitting code
diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md
new file mode 100644
index 000000000..44c7d8c51
--- /dev/null
+++ b/docs/getting-started/introduction.md
@@ -0,0 +1,131 @@
+# Introduction to OpenFrame OSS Lib
+
+**OpenFrame OSS Lib** (`openframe-oss-lib`) is the modular backbone of [OpenFrame](https://openframe.ai) — Flamingo's AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation.
+
+This library provides the shared, composable building blocks that power the entire OpenFrame stack: from multi-tenant identity and OAuth2 authorization, to reactive APIs, event-driven stream processing, and an embeddable AI chat engine.
+
+[![OpenFrame: 5-Minute MSP Platform Walkthrough - Cut Vendor Costs & Automate Ops](https://img.youtube.com/vi/er-z6IUnAps/maxresdefault.jpg)](https://www.youtube.com/watch?v=er-z6IUnAps)
+
+---
+
+## What Is OpenFrame OSS Lib?
+
+`openframe-oss-lib` is a multi-module **Spring Boot 3 / Java 21** Maven project (version `6.0.10`) that provides reusable infrastructure libraries for building OpenFrame-compatible services. It is the foundational layer consumed by all services running inside the OpenFrame platform.
+
+> This repository does **not** ship a standalone application — it provides libraries and service-core modules that are embedded into deployable services.
+
+---
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Multi-Tenant Identity** | OAuth2 Authorization Server with per-tenant RSA key pairs and OIDC support |
+| **Reactive API Layer** | REST + GraphQL (Netflix DGS) with Relay-style pagination and DataLoader batching |
+| **Gateway & WebSocket Routing** | Spring Cloud Gateway with JWT validation, rate limiting, and tool proxying |
+| **MongoDB Data Layer** | Reactive + sync repositories, cursor pagination, multi-tenant scoping |
+| **Kafka Stream Processing** | Debezium CDC ingestion, event normalization, Kafka Streams enrichment |
+| **Management & Operations** | Distributed schedulers, migration support (Mongock), NATS initialization |
+| **Frontend UI & AI Chat** | Embeddable React AI assistant (Guide + Mingo modes), Kanban, Notifications |
+| **Integrated Tool SDKs** | Native SDKs for MeshCentral, Tactical RMM, and Fleet MDM |
+| **Shared API Contracts** | Centralized DTOs, filters, and pagination primitives for all services |
+
+---
+
+## Target Audience
+
+This library is intended for:
+
+- **MSP Platform Engineers** building services that integrate with OpenFrame
+- **Backend Developers** implementing new OpenFrame microservices
+- **Open-Source Contributors** extending the OpenFrame ecosystem
+- **System Architects** designing multi-tenant SaaS or OSS MSP platforms
+
+---
+
+## Platform Overview
+
+```mermaid
+flowchart TD
+    Frontend["Frontend Core UI and Chat"]
+    Gateway["Gateway Service Core"]
+    Auth["Authorization Service Core"]
+    API["API Service Core (HTTP + GraphQL)"]
+    Management["Management Service Core"]
+    Data["Data Models and Repositories Mongo"]
+    Stream["Stream Processing Kafka"]
+    Cassandra["Cassandra (Unified Events)"]
+    Tools["Integrated Tools (MeshCentral, Tactical, Fleet)"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    API --> Data
+    API --> Stream
+    Stream --> Cassandra
+    Stream --> Data
+    Management --> Data
+    Management --> Stream
+    Tools --> Stream
+```
+
+---
+
+## Module Ecosystem
+
+The library is organized into 29+ composable modules, grouped by domain:
+
+### Core Infrastructure
+- `openframe-core` – Shared utilities, constants, validation
+- `openframe-exception` – Unified exception hierarchy
+- `openframe-core-crypto` – Encryption services
+- `openframe-config-core` – Configuration server support
+
+### Data Layer
+- `openframe-data-mongo-common` – Document models and base repositories
+- `openframe-data-mongo-sync` – Synchronous MongoDB repositories
+- `openframe-data-mongo-reactive` – Reactive MongoDB repositories
+- `openframe-data-redis` – Redis caching and rate limiting
+- `openframe-data-kafka` – Kafka producer utilities
+- `openframe-data-cassandra` – Cassandra persistence for event logs
+- `openframe-data-pinot` – Apache Pinot analytics queries
+- `openframe-data-nats` – NATS messaging and pub/sub
+
+### Service Cores
+- `openframe-api-service-core` – REST + GraphQL application layer
+- `openframe-api-lib` – Shared API contracts and DTOs
+- `openframe-authorization-service-core` – OAuth2/OIDC Authorization Server
+- `openframe-gateway-service-core` – Reactive edge gateway
+- `openframe-management-service-core` – Operational control plane
+- `openframe-stream-service-core` – Kafka event ingestion pipeline
+- `openframe-client-core` – Agent registration and device management
+- `openframe-security-core` – JWT and security primitives
+- `openframe-security-oauth` – OAuth2 BFF (Backend For Frontend)
+
+### Tool Integrations
+- `openframe-tactical-sdk` – Tactical RMM integration
+- `sdk/fleetmdm` – Fleet MDM client SDK
+- `sdk/tacticalrmm` – Tactical RMM client SDK
+
+### Frontend
+- `openframe-frontend-core` – Reusable React UI components and AI Chat
+
+---
+
+## The Flamingo / OpenFrame Platform
+
+OpenFrame is part of the [Flamingo](https://flamingo.run) AI-powered MSP stack:
+
+- **Mingo AI** – AI assistant for technicians
+- **Fae** – AI assistant for clients
+- **OpenFrame** – Unified platform integrating MSP tools with intelligent automation
+
+Join the community: [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+
+---
+
+## Next Steps
+
+- Review the [Prerequisites](prerequisites.md) to set up your environment
+- Follow the [Quick Start Guide](quick-start.md) to get up and running in 5 minutes
+- Explore [First Steps](first-steps.md) after your initial setup
diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md
new file mode 100644
index 000000000..3d420e6e4
--- /dev/null
+++ b/docs/getting-started/prerequisites.md
@@ -0,0 +1,141 @@
+# Prerequisites
+
+Before working with `openframe-oss-lib`, ensure your development environment meets the following requirements.
+
+---
+
+## Required Software
+
+| Tool | Minimum Version | Notes |
+|------|----------------|-------|
+| **Java (JDK)** | 21 | Project uses Java 21 features; LTS recommended |
+| **Apache Maven** | 3.8+ | Used for building all modules |
+| **Git** | 2.x+ | For cloning the repository |
+| **Docker** | 24.x+ | Required for integration tests (Testcontainers) |
+| **Docker Compose** | 2.x+ | Available for local infrastructure setup |
+| **Node.js** | 18+ | Required for frontend-core module development |
+
+> **Note:** The project uses the `flatten-maven-plugin` with CI-friendly versioning. Maven Wrapper (`./mvnw`) is recommended if available.
+
+---
+
+## System Requirements
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| **RAM** | 8 GB | 16 GB+ |
+| **CPU Cores** | 4 | 8+ |
+| **Disk Space** | 10 GB free | 20 GB free |
+| **OS** | Linux / macOS / Windows (WSL2) | Linux / macOS |
+
+> Integration tests use **Testcontainers** to spin up MongoDB and other services in Docker. Docker must be accessible to the running JVM process.
+
+---
+
+## Infrastructure Dependencies
+
+When running services locally, the following infrastructure components are required:
+
+| Service | Version | Purpose |
+|---------|---------|---------|
+| **MongoDB** | 6.x+ | Primary data store for all domain documents |
+| **Redis** | 7.x+ | Caching, rate limiting, and distributed locks (ShedLock) |
+| **Apache Kafka** | 3.x+ | Event streaming and CDC processing |
+| **NATS** | 2.x+ | Agent messaging and real-time notifications |
+| **Apache Cassandra** | 4.x+ | Long-term unified event log storage |
+| **Apache Pinot** | 1.2.0 | Analytics query engine |
+
+> For unit and module-level tests, these are not required — Testcontainers handles in-process infrastructure.
+
+---
+
+## GitHub Package Registry Access
+
+The library publishes artifacts to **GitHub Maven Package Registry**. To consume modules as Maven dependencies, configure your `~/.m2/settings.xml`:
+
+```xml
+<settings>
+  <servers>
+    <server>
+      <id>github</id>
+      <username>YOUR_GITHUB_USERNAME</username>
+      <password>YOUR_GITHUB_TOKEN</password>
+    </server>
+  </servers>
+</settings>
+```
+
+Generate a GitHub Personal Access Token (PAT) with `read:packages` scope from [GitHub Settings → Developer Settings](https://github.com/settings/tokens).
+
+---
+
+## Key Environment Variables
+
+The following environment variables are used across modules:
+
+| Variable | Module | Description |
+|----------|--------|-------------|
+| `TENANT_ID` | `openframe-data-mongo-common` | Tenant ID for multi-tenant scoping (defaults to `oss`) |
+| `SPRING_DATA_MONGODB_URI` | All data modules | MongoDB connection string |
+| `SPRING_REDIS_HOST` | `openframe-data-redis` | Redis host |
+| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | `openframe-data-kafka` | Kafka broker addresses |
+| `NATS_SERVER_URL` | `openframe-data-nats` | NATS server URL |
+
+> In OSS single-tenant mode, `TENANT_ID` defaults to `oss` if not set.
+
+---
+
+## Verification Commands
+
+Run these commands to verify your environment is ready:
+
+```bash
+# Verify Java version (must be 21+)
+java -version
+
+# Verify Maven is available
+mvn -version
+
+# Verify Docker is running
+docker info
+
+# Verify Docker Compose
+docker compose version
+
+# Verify Git
+git --version
+
+# Verify Node.js (for frontend-core work)
+node --version
+npm --version
+```
+
+Expected Java output:
+```text
+openjdk version "21.x.x" ...
+```
+
+---
+
+## IDE Recommendations
+
+| IDE | Recommended Plugins |
+|-----|---------------------|
+| **IntelliJ IDEA** (recommended) | Lombok, Spring Boot, GraphQL |
+| **VS Code** | Extension Pack for Java, Spring Boot Tools |
+| **Eclipse** | Spring Tools Suite 4 |
+
+> Enable annotation processing in your IDE to support **Lombok** (`@Data`, `@Builder`, `@Slf4j`, etc.), which is used extensively across all modules.
+
+---
+
+## Maven Settings for Building
+
+To build the full project locally, ensure access to the GitHub Maven Package Registry as described above, then verify your local Maven cache:
+
+```bash
+# Verify Maven can resolve dependencies
+mvn dependency:resolve -pl openframe-core --quiet
+```
+
+If dependency resolution fails, check your GitHub token permissions and `settings.xml` configuration.
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
new file mode 100644
index 000000000..ba992e25e
--- /dev/null
+++ b/docs/getting-started/quick-start.md
@@ -0,0 +1,190 @@
+# Quick Start
+
+Get up and running with `openframe-oss-lib` in under 5 minutes.
+
+[![Getting Started with OpenFrame - Organization Setup Basics](https://img.youtube.com/vi/-_56_qYvMWk/maxresdefault.jpg)](https://www.youtube.com/watch?v=-_56_qYvMWk)
+
+---
+
+## TL;DR
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/flamingo-stack/openframe-oss-lib.git
+cd openframe-oss-lib
+
+# 2. Build all modules (skip tests for speed)
+mvn install -DskipTests
+
+# 3. Run tests for a specific module
+mvn test -pl openframe-core
+
+# 4. Run integration tests (requires Docker)
+mvn verify -pl openframe-data-mongo-sync
+```
+
+---
+
+## Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/flamingo-stack/openframe-oss-lib.git
+cd openframe-oss-lib
+```
+
+---
+
+## Step 2: Verify the Build
+
+The project uses a `revision` property for CI-friendly versioning. The current version is **6.0.10**.
+
+```bash
+# Build all modules, skipping tests
+mvn install -DskipTests
+
+# Expected output: BUILD SUCCESS
+```
+
+> **Note:** The first build may take several minutes as Maven downloads all dependencies.
+
+---
+
+## Step 3: Use a Module as a Maven Dependency
+
+After a successful local install, you can reference any module in your own project:
+
+```xml
+<!-- In your project's pom.xml -->
+<dependency>
+    <groupId>com.openframe.oss</groupId>
+    <artifactId>openframe-core</artifactId>
+    <version>6.0.10</version>
+</dependency>
+```
+
+For the API contracts module:
+
+```xml
+<dependency>
+    <groupId>com.openframe.oss</groupId>
+    <artifactId>openframe-api-lib</artifactId>
+    <version>6.0.10</version>
+</dependency>
+```
+
+---
+
+## Step 4: Add the Parent POM (Optional)
+
+If you are building an OpenFrame-compatible service, inherit from the parent POM to get aligned dependency management:
+
+```xml
+<parent>
+    <groupId>com.openframe.oss</groupId>
+    <artifactId>openframe-oss-lib</artifactId>
+    <version>6.0.10</version>
+</parent>
+```
+
+This gives you pre-configured:
+- Spring Boot 3.3.0
+- Java 21
+- Lombok 1.18.30
+- Spring Cloud 2023.0.3
+- NATS, Kafka, MongoDB, Pinot, gRPC versions
+
+---
+
+## Step 5: Run a Single Module Test
+
+```bash
+# Run unit tests for the exception module
+mvn test -pl openframe-exception
+
+# Run integration tests for MongoDB sync module (requires Docker)
+mvn verify -pl openframe-data-mongo-sync
+```
+
+---
+
+## Hello World: Using Core Utilities
+
+Here is a minimal example using the shared utilities from `openframe-core`:
+
+```java
+import com.openframe.core.util.SlugUtil;
+import com.openframe.core.service.AgentRegistrationSecretGenerator;
+
+// Generate a URL-safe slug
+String slug = SlugUtil.toSlug("My MSP Organization");
+// Result: "my-msp-organization"
+
+// The AgentRegistrationSecretGenerator produces secure tokens
+// for device registration flows
+```
+
+---
+
+## Expected Results
+
+After a successful build, you should see:
+
+```text
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary for OpenFrame OSS Libraries 6.0.10:
+[INFO]
+[INFO] OpenFrame OSS Libraries ........................ SUCCESS
+[INFO] openframe-exception ............................ SUCCESS
+[INFO] openframe-core ................................ SUCCESS
+[INFO] openframe-core-crypto ......................... SUCCESS
+[INFO] openframe-data-mongo-common ................... SUCCESS
+[INFO] openframe-data-mongo-sync ..................... SUCCESS
+[INFO] openframe-data-mongo-reactive ................. SUCCESS
+[INFO] ...
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+```
+
+---
+
+## Quick Module Reference
+
+| Module | Artifact ID | Use Case |
+|--------|------------|----------|
+| Core utilities | `openframe-core` | Slugs, pagination, validation |
+| Exception handling | `openframe-exception` | Unified error responses |
+| Encryption | `openframe-core-crypto` | AES encryption services |
+| MongoDB common | `openframe-data-mongo-common` | Document models |
+| MongoDB sync | `openframe-data-mongo-sync` | Synchronous repositories |
+| MongoDB reactive | `openframe-data-mongo-reactive` | Reactive repositories |
+| Redis | `openframe-data-redis` | Caching, rate limits |
+| Kafka | `openframe-data-kafka` | Event producers |
+| API contracts | `openframe-api-lib` | Shared DTOs and filters |
+| Security core | `openframe-security-core` | JWT, auth principals |
+
+---
+
+## Consuming from GitHub Packages
+
+If you prefer consuming published artifacts rather than building locally, add the GitHub Packages repository to your `pom.xml`:
+
+```xml
+<repositories>
+    <repository>
+        <id>github</id>
+        <url>https://maven.pkg.github.com/flamingo-stack/openframe-oss-lib</url>
+    </repository>
+</repositories>
+```
+
+Ensure your `~/.m2/settings.xml` has a `server` entry with `id=github` and a valid GitHub token as described in the [Prerequisites](prerequisites.md).
+
+---
+
+## Next Steps
+
+After your quick start:
+
+- Follow the [First Steps Guide](first-steps.md) to explore key features and modules
+- Review the [Prerequisites](prerequisites.md) for full environment configuration
+- Explore the [Architecture Overview](../development/architecture/README.md) to understand how modules fit together

From 1f571810f45aca633341aac7d2d55fd26023d643 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 19:33:56 +0000
Subject: [PATCH 7/7] docs: Stage 4 - Repository documentation (4 files) [skip
 ci]

---
 CONTRIBUTING.md | 460 +++++++++++++++++++++++++++---------------------
 README.md       | 268 ++++++++++++++++------------
 docs/README.md  |  96 ++++++++++
 3 files changed, 507 insertions(+), 317 deletions(-)
 create mode 100644 docs/README.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6a434c79a..90a5649b5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,147 +6,179 @@
   </picture>
 </div>
 
-# Contributing to openframe-oss-lib
+# Contributing to OpenFrame OSS Lib
 
-Thank you for contributing to **openframe-oss-lib**! This guide covers everything you need to know: code style, branching strategy, commit conventions, pull request process, and security requirements.
+Thank you for contributing to `openframe-oss-lib`! This document covers everything you need to get started: code style conventions, branching strategy, commit message format, pull request process, and security guidelines.
 
 ---
 
-## Community First
+## 📣 Community First
 
-All contribution discussions happen on the [OpenMSP Slack Community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA). We do **not** use GitHub Issues or GitHub Discussions.
+> **All discussions, questions, and feature requests** are managed on [OpenMSP Slack](https://www.openmsp.ai/).
+> We do **not** use GitHub Issues or GitHub Discussions on this repository.
 
-Before starting a large contribution:
+[![Join OpenMSP Slack](https://img.shields.io/badge/Slack-OpenMSP-blue?logo=slack)](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
 
-1. Join the [OpenMSP Slack](https://www.openmsp.ai/)
-2. Describe what you're planning in the `#openframe-dev` channel
-3. Get feedback from maintainers before investing significant effort
+| Channel | Purpose |
+|---------|---------|
+| `#dev-questions` | Technical questions and help |
+| `#roadmap` | Feature requests and ideas |
+| `#bugs` | Bug reports and triage |
 
 ---
 
-## Development Environment Setup
+## 🚀 Getting Started
+
+Before contributing:
+
+1. Set up your [development environment](./docs/development/setup/environment.md)
+2. Follow the [local development guide](./docs/development/setup/local-development.md) to build and test locally
+3. Join the [OpenMSP Slack community](https://www.openmsp.ai/) for discussion and guidance
+
+---
+
+## 🛠️ Development Environment
 
 ### Prerequisites
 
-| Tool | Minimum Version |
-|------|----------------|
-| Java (JDK) | 21 |
-| Apache Maven | 3.9+ |
-| Git | 2.x |
-| Docker | 24.x |
+| Tool | Version |
+|------|---------|
+| **Java (JDK)** | 21+ |
+| **Apache Maven** | 3.8+ |
+| **Git** | 2.x+ |
+| **Docker** | 24.x+ (for integration tests) |
+| **Node.js** | 18+ (for frontend-core only) |
 
-### Initial Setup
+### Setup
 
 ```bash
 # Clone the repository
 git clone https://github.com/flamingo-stack/openframe-oss-lib.git
 cd openframe-oss-lib
 
-# Configure GitHub Packages credentials
-# Add to ~/.m2/settings.xml (see Prerequisites guide)
-
 # Build all modules (skip tests for speed)
 mvn install -DskipTests
+
+# Run unit tests for a specific module
+mvn test -pl openframe-core
+
+# Run integration tests (requires Docker)
+mvn verify -pl openframe-data-mongo-sync
 ```
 
-### Recommended IDE
+### GitHub Packages Access
 
-**IntelliJ IDEA** (Community or Ultimate) is the recommended IDE. After importing the project:
+Add your credentials to `~/.m2/settings.xml`:
 
-1. Set **Project SDK** to Java 21
-2. Enable **Annotation Processors** for Lombok (`Settings → Compiler → Annotation Processors`)
-3. Enable Maven delegate: `Settings → Build Tools → Maven → Runner → Delegate IDE build/run actions to Maven`
-4. Increase heap: `Help → Change Memory Settings → Xmx: 4096 MB`
+```xml
+<settings>
+  <servers>
+    <server>
+      <id>github</id>
+      <username>YOUR_GITHUB_USERNAME</username>
+      <password>YOUR_GITHUB_TOKEN</password>
+    </server>
+  </servers>
+</settings>
+```
 
 ---
 
-## Code Style and Conventions
+## 🎨 Code Style and Conventions
 
 ### Java Style
 
 | Convention | Rule |
 |-----------|------|
-| Indentation | 4 spaces (no tabs) |
-| Line length | Max 120 characters |
-| Imports | No wildcard imports; organize by static → java → jakarta → spring → other |
-| Braces | Opening brace on same line |
-| Naming | `camelCase` methods/fields, `PascalCase` classes, `UPPER_SNAKE` constants |
-
-### Lombok Usage
+| **Lombok** | Use `@Data`, `@Builder`, `@Slf4j`, `@RequiredArgsConstructor` freely |
+| **Immutability** | Prefer `final` fields; use Lombok `@Value` for pure DTOs |
+| **Package structure** | Follow existing `com.openframe.*` package hierarchy |
+| **Naming** | `*Service` for business logic, `*Repository` for data access, `*Controller` for REST, `*DataFetcher` for GraphQL |
+| **Exception handling** | Throw from the `openframe-exception` hierarchy (`NotFoundException`, `BadRequestException`, etc.) |
+| **Logging** | Use `@Slf4j` (Lombok); log at `DEBUG` for operations, `WARN`/`ERROR` for unexpected states |
 
-Use Lombok to reduce boilerplate:
+### Service Class Pattern
 
 ```java
-// Prefer these annotations
-@Data          // getters, setters, equals, hashCode, toString
-@Value         // immutable value objects
-@Builder       // fluent builders
-@RequiredArgsConstructor  // constructor injection
-@Slf4j         // logging
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class DeviceService {
+    private final MachineRepository machineRepository;
+    private final TenantIdProvider tenantIdProvider;
+
+    public Optional<Machine> findDevice(String machineId) {
+        log.debug("Looking up device: {}", machineId);
+        return machineRepository.findByMachineId(
+            machineId, tenantIdProvider.getTenantId()
+        );
+    }
+}
 ```
 
-### Spring Boot Conventions
-
-Use constructor injection (via `@RequiredArgsConstructor`) over field injection:
+### GraphQL DataFetcher Pattern
 
 ```java
-// Correct: Constructor injection
-@Service
-@RequiredArgsConstructor
-public class MyService {
-    private final MyRepository repository;
-    private final AnotherService anotherService;
+@DgsComponent
+public class DeviceDataFetcher {
+
+    @DgsQuery
+    public GenericConnection<DeviceNode> devices(
+            @InputArgument DeviceFilterInput filter,
+            @InputArgument ConnectionArgs connectionArgs) {
+        // delegate to service layer
+    }
 }
 ```
 
-Prefer `@ConfigurationProperties` over `@Value` for configuration classes.
-
 ### Multi-Tenancy Requirements
 
-Every service and repository method that accesses tenant-scoped data **must** include `tenantId` in queries:
+**Every new domain document must:**
 
 ```java
-// Correct: Always scope to tenant
-Optional<Organization> findByIdAndTenantId(String id, String tenantId);
+// 1. Implement TenantScoped
+@Document(collection = "my_collection")
+public class MyDocument implements TenantScoped {
+    @Id
+    private String id;
 
-// Wrong: Missing tenant scope — never do this for tenant-scoped data
-Optional<Organization> findById(String id);
+    private String tenantId; // Required for all domain documents
+}
 ```
 
-### Exception Handling
+Also ensure a compound MongoDB index that includes `tenantId` is defined in the appropriate `MongoIndexConfig`.
 
-Use the standard exception hierarchy from `openframe-exception`:
+---
 
-```java
-throw new NotFoundException("Organization not found: " + id);
-throw new BadRequestException("Invalid email format");
-throw new ForbiddenException("Access denied for tenant: " + tenantId);
-throw new ConflictException("Email already exists");
-throw new ValidationException("Required field missing: name");
-```
+## 🌿 Branch Naming
 
-Never throw raw `RuntimeException` or `Exception` directly.
+Use descriptive, hyphen-separated branch names with a type prefix:
 
----
+| Prefix | Use Case | Example |
+|--------|---------|---------|
+| `feat/` | New features | `feat/add-webhook-support` |
+| `fix/` | Bug fixes | `fix/notification-pagination-cursor` |
+| `chore/` | Maintenance tasks | `chore/upgrade-spring-boot-3.4` |
+| `refactor/` | Code refactoring | `refactor/device-service-split` |
+| `docs/` | Documentation changes | `docs/update-auth-flow-diagram` |
+| `test/` | Test additions/fixes | `test/add-ticket-repository-it` |
 
-## Branch Naming
+```bash
+# Create a feature branch
+git checkout -b feat/add-device-tagging-bulk-update
 
-| Type | Pattern | Example |
-|------|---------|---------|
-| Feature | `feature/<description>` | `feature/add-nats-retry-logic` |
-| Bug fix | `fix/<description>` | `fix/tenant-context-not-cleared` |
-| Refactor | `refactor/<description>` | `refactor/notification-repository` |
-| Documentation | `docs/<description>` | `docs/update-kafka-readme` |
-| Dependency updates | `deps/<description>` | `deps/upgrade-spring-boot-3.4` |
+# Create a fix branch
+git checkout -b fix/cassandra-tenant-scope-query
+```
 
 ---
 
-## Commit Message Format
+## 💬 Commit Message Format
 
-Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+Follow the **Conventional Commits** specification:
 
 ```text
-<type>(<scope>): <description>
+<type>(<scope>): <short description>
 
 [optional body]
 
@@ -159,202 +191,220 @@ Follow the [Conventional Commits](https://www.conventionalcommits.org/) specific
 |------|------------|
 | `feat` | New feature or capability |
 | `fix` | Bug fix |
-| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `chore` | Build, dependency, or tooling changes |
+| `refactor` | Code restructure without behavior change |
 | `test` | Adding or updating tests |
 | `docs` | Documentation only changes |
-| `chore` | Build system, dependency updates, CI changes |
 | `perf` | Performance improvements |
+| `ci` | CI/CD pipeline changes |
 
-### Scope
+### Scope Examples
 
-Use the module name (without the `openframe-` prefix) as scope:
+| Scope | Module |
+|-------|--------|
+| `core` | `openframe-core` |
+| `gateway` | `openframe-gateway-service-core` |
+| `auth` | `openframe-authorization-service-core` |
+| `api` | `openframe-api-service-core` |
+| `data` | `openframe-data-mongo-*` |
+| `stream` | `openframe-stream-service-core` |
+| `management` | `openframe-management-service-core` |
+| `frontend` | `openframe-frontend-core` |
+| `security` | `openframe-security-core` |
+
+### Commit Examples
 
 ```text
-feat(security-core): add PKCE utility for code challenge generation
-fix(data-mongo-sync): resolve tenant context leak in batch operations
-refactor(gateway-service-core): extract rate limit logic into service
-test(data-nats): add integration test for notification broadcast
-chore(deps): upgrade spring-boot to 3.3.2
-```
+feat(api): add bulk device tag assignment endpoint
 
-### Example Commit
+Adds GraphQL mutation for bulk assignment of tags to multiple
+devices in a single operation. Includes DataLoader optimization
+to prevent N+1 on tag resolution.
+```
 
 ```text
-feat(authorization-service-core): add Microsoft SSO provider strategy
+fix(data): correct cursor encoding for notification pagination
 
-Implements MicrosoftClientRegistrationStrategy to support Microsoft
-Entra ID (Azure AD) authentication flows alongside existing Google SSO.
+The cursor codec was using unstable field order causing
+inconsistent pagination results. Now uses deterministic
+JSON serialization.
+```
 
-Closes: #discussion in #openframe-dev slack
+```text
+chore(deps): upgrade Spring Boot to 3.3.1
+
+Addresses CVE-2024-XXXX in spring-web.
 ```
 
 ---
 
-## Pull Request Process
+## 🔁 Pull Request Process
 
 ### Before Opening a PR
 
-- [ ] Build passes: `mvn install -DskipTests`
-- [ ] Tests pass: `mvn test -pl <affected-module>`
-- [ ] No secrets committed — review all changed files
-- [ ] Follows code style: Lombok, constructor injection, tenant scoping
-- [ ] Edge cases covered: unit tests added for new logic
+- [ ] Branch is up to date with `main`
+- [ ] All unit tests pass: `mvn test`
+- [ ] Relevant integration tests pass: `mvn verify -pl <module>`
+- [ ] New code follows project conventions (Lombok, tenant scoping, etc.)
+- [ ] New domain documents implement `TenantScoped`
+- [ ] No secrets or hardcoded credentials in code
+- [ ] Javadoc added for new public APIs
 
-### PR Title Format
+### PR Description Template
 
 ```text
-feat(security-core): add PKCE utility for authorization flows
-fix(data-mongo-sync): resolve tenant context leak
-```
+## Summary
+Brief description of what this PR does and why.
 
-### PR Description Template
+## Changes
+- List key changes
+- Affected modules: openframe-xxx, openframe-yyy
 
-```markdown
-## What does this PR do?
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] Manually tested against local stack
 
-Brief description of the change.
+## Related
+Link to Slack discussion or related PR (if any).
+```
 
-## Why?
+### Review Checklist
 
-Motivation for the change.
+Reviewers verify:
 
-## How was it tested?
+- [ ] Code follows OpenFrame conventions (naming, Lombok, tenant scoping)
+- [ ] New endpoints have appropriate `@PreAuthorize` or security config
+- [ ] No N+1 query problems (DataLoaders used for related entity loading)
+- [ ] Integration tests cover the happy path
+- [ ] Error cases return appropriate exceptions from `openframe-exception`
+- [ ] Multi-tenant isolation maintained (`tenantId` filters present)
 
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] Manual testing performed
+---
 
-## Checklist
+## 📦 Adding a New Module
 
-- [ ] No secrets in code or tests
-- [ ] All new endpoints have authorization rules
-- [ ] New DB queries are tenant-scoped
-- [ ] Input validation on all new DTOs
-- [ ] No breaking changes (or breaking changes are documented)
-```
+When adding a new module to `openframe-oss-lib`:
 
----
+1. Add to parent `pom.xml` in the `<modules>` section
+2. Inherit from parent: `<parent>openframe-oss-lib</parent>`
+3. Add to `<dependencyManagement>` in parent POM with `${revision}` version
+4. Follow naming convention: `openframe-<domain>-<layer>`
+5. Include a `README.md` describing the module's purpose
+6. Write at least one unit test before the first PR
 
-## Testing Guidelines
+---
 
-### Test Structure
+## 🔒 Security Guidelines
 
-```text
-openframe-<module>/
-└── src/
-    └── test/java/com/openframe/...
-        ├── FooTest.java     # Unit test (runs in mvn test)
-        └── FooIT.java       # Integration test (runs in mvn verify)
-```
+### Secrets Management
 
-### Running Tests
+Never hardcode secrets in source code or configuration files. Always use environment variables:
 
 ```bash
-# Unit tests for a specific module
-mvn test -pl openframe-core
-
-# Integration tests (requires Docker)
-mvn verify -pl openframe-data-mongo-sync
-
-# Skip all tests during build
-mvn install -DskipTests
+# Correct: use environment variables
+export SPRING_DATA_MONGODB_URI=mongodb://user:secret@host/db
 ```
 
-### Unit Test Template
+Never commit `.env` files or any file containing credentials to version control.
 
-```java
-@ExtendWith(MockitoExtension.class)
-class MyServiceTest {
+### Multi-Tenant Safety Checklist
 
-    @Mock
-    private MyRepository repository;
+For any new data-access code:
 
-    @InjectMocks
-    private MyService service;
+- [ ] Document implements `TenantScoped`
+- [ ] Repository queries include `tenantId` filter
+- [ ] Custom repository implementations use `TenantIdProvider`
+- [ ] Compound index includes `{ tenantId: 1, ... }`
 
-    @Test
-    void shouldReturnExpectedResult() {
-        // Given
-        when(repository.findById("id-1")).thenReturn(Optional.of(new MyEntity("id-1")));
+### Input Validation
 
-        // When
-        var result = service.getById("id-1");
+All API inputs must use Jakarta Bean Validation constraints:
 
-        // Then
-        assertThat(result).isPresent();
-        assertThat(result.get().getId()).isEqualTo("id-1");
-    }
-}
+```java
+@NotNull
+private String machineId;
+
+@Positive
+private Integer timeoutSeconds;
 ```
 
-### Test Conventions
+### API Key Best Practices
 
-- Use **Given / When / Then** structure in test methods
-- Test method names should describe behavior: `shouldReturnNotFoundWhenEntityDoesNotExist`
-- Always clean up test data in `@AfterEach` for integration tests
-- Integration tests use Testcontainers — Docker must be running
+- Rotate API keys regularly using `ApiKeyController`
+- Store keys encrypted using `EncryptionService` from `openframe-core-crypto`
+- Never log API key values — only log key IDs
+- Apply appropriate `APIKeyType` scope
 
 ---
 
-## Security Requirements
+## 🧪 Testing Guidelines
 
-Before opening a PR, verify:
+### Test Structure
 
-- [ ] No secrets, tokens, or keys in code or test fixtures
-- [ ] All new endpoints have explicit authorization rules
-- [ ] New database queries include `tenantId` scope
-- [ ] Input validation annotations on all request DTOs
-- [ ] Sensitive fields are encrypted at rest using `EncryptionService`
-- [ ] No raw SQL/NoSQL string interpolation
+| Pattern | Type | Requirement |
+|---------|------|-------------|
+| `*Test.java` | Unit test | No Docker; runs in `mvn test` |
+| `*IT.java` | Integration test | Requires Docker; runs in `mvn verify` |
 
-**For security vulnerabilities**, do **not** open a public GitHub issue. Contact the team via the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) in a direct message to the maintainers, or visit [flamingo.run](https://flamingo.run) for the security contact.
+### Unit Test Example
 
----
+```java
+class SlugUtilTest {
 
-## Adding a New Module
+    @Test
+    void shouldConvertNameToSlug() {
+        String name = "My MSP Organization";
+        String slug = SlugUtil.toSlug(name);
+        assertThat(slug).isEqualTo("my-msp-organization");
+    }
+}
+```
 
-When adding a new module to the library:
+### Integration Test Example
 
-1. Create the module directory following the naming convention: `openframe-<name>/`
-2. Add a `pom.xml` that inherits from the parent POM
-3. Add the module to the parent `pom.xml` `<modules>` section
-4. Add the module to `<dependencyManagement>` in the parent with `${revision}`
-5. Write unit tests before submitting
-6. Update the README and architecture documentation
+```java
+@SpringBootTest
+@Testcontainers
+class OrganizationRepositoryIT extends BaseMongoIntegrationTest {
 
-```xml
-<!-- Parent pom.xml: modules section -->
-<module>openframe-my-new-module</module>
-
-<!-- Parent pom.xml: dependencyManagement -->
-<dependency>
-    <groupId>com.openframe.oss</groupId>
-    <artifactId>openframe-my-new-module</artifactId>
-    <version>${revision}</version>
-</dependency>
-```
+    @Autowired
+    private OrganizationRepository organizationRepository;
 
----
+    @Test
+    void shouldSaveAndRetrieveOrganization() {
+        Organization org = new Organization();
+        org.setTenantId("oss");
+        org.setName("Test MSP");
+
+        Organization saved = organizationRepository.save(org);
+
+        assertThat(saved.getId()).isNotNull();
+    }
+}
+```
 
-## Versioning
+### Speed Up Integration Tests
 
-All modules are versioned together using `${revision}` in the parent POM. Version bumps are managed by the maintainers. Contributors do **not** need to update version numbers in PRs.
+```bash
+# Enable Testcontainers container reuse
+echo "testcontainers.reuse.enable=true" >> ~/.testcontainers.properties
+```
 
-Versioning follows [Semantic Versioning](https://semver.org/):
+### Coverage Guidelines
 
-- **Major:** Breaking API changes
-- **Minor:** New backward-compatible features
-- **Patch:** Backward-compatible bug fixes
+| Code Type | Coverage Target |
+|-----------|----------------|
+| Domain services | 80%+ unit test coverage |
+| Utility classes | 90%+ unit test coverage |
+| Repository custom implementations | Integration test coverage |
+| Controllers / DataFetchers | Integration test coverage |
 
 ---
 
-## Getting Help
-
-Stuck? Reach out on the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) in `#openframe-dev`.
+## 📖 Documentation
 
-- 🌐 **OpenFrame Platform:** [https://openframe.ai](https://openframe.ai)
-- 💬 **OpenMSP Community:** [https://www.openmsp.ai/](https://www.openmsp.ai/)
-- 🦩 **Flamingo:** [https://flamingo.run](https://flamingo.run)
+For deeper reference on development workflows, see the [Development Documentation](./docs/development/README.md).
 
 ---
 
diff --git a/README.md b/README.md
index 3ccf01ff2..487417f48 100644
--- a/README.md
+++ b/README.md
@@ -10,82 +10,105 @@
   <a href="LICENSE.md"><img alt="License" src="https://img.shields.io/badge/LICENSE-FLAMINGO%20AI%20Unified%20v1.0-%23FFC109?style=for-the-badge&labelColor=white"></a>
 </p>
 
-# openframe-oss-lib
+# OpenFrame OSS Lib
 
-**openframe-oss-lib** is the foundational backend library powering the [OpenFrame](https://openframe.ai) platform — the AI-driven, open-source MSP infrastructure stack built by [Flamingo](https://flamingo.run).
+**`openframe-oss-lib`** is the modular backbone of [OpenFrame](https://openframe.ai) — Flamingo's AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation.
 
-This repository provides the **shared Spring Boot libraries** that every OpenFrame service is built upon: multi-tenant authentication, API layers (REST + GraphQL), reactive gateway routing, event streaming, real-time messaging, polyglot persistence, and distributed management workflows.
+This library provides the shared, composable building blocks that power the entire OpenFrame stack: from multi-tenant identity and OAuth2 authorization, to reactive APIs, event-driven stream processing, and an embeddable AI chat engine.
 
-[![OpenFrame: 5-Minute MSP Platform Walkthrough - Cut Vendor Costs & Automate Ops](https://img.youtube.com/vi/er-z6IUnAps/maxresdefault.jpg)](https://www.youtube.com/watch?v=er-z6IUnAps)
+> This repository does **not** ship a standalone application — it provides libraries and service-core modules that are embedded into deployable OpenFrame-compatible services.
 
 ---
 
-## Features
-
-- **Multi-Tenant by Default** — Every module implements strict tenant isolation: per-tenant RSA key pairs, tenant-scoped cache keys, tenant-scoped scheduler locks, and tenant ID embedded in every JWT
-- **Multi-Tenant OAuth2 Authorization Server** — Per-tenant RSA key pairs, JWT issuance, PKCE support, dynamic client registration, SSO integration (Google, Microsoft), and invitation-based onboarding
-- **Relay-Compliant GraphQL + REST APIs** — Netflix DGS GraphQL with DataLoaders for N+1 prevention alongside versioned REST controllers; cursor-based pagination throughout
-- **Reactive Edge Gateway** — Spring Cloud Gateway + WebFlux + Netty; multi-issuer JWT validation, API key rate limiting, WebSocket proxying, and tool upstream resolution
-- **Event Ingestion & Streaming** — Kafka / Debezium CDC processing pipeline with tool-specific deserialization, event enrichment, unified event type normalization, and Kafka Streams enrichment
-- **Real-Time Messaging** — NATS JetStream publish/subscribe for device and tool notifications; persist-first notification strategy with read-state tracking
-- **Polyglot Persistence** — MongoDB (sync + reactive), Redis (tenant-aware caching), Apache Pinot (analytics), Apache Cassandra (log storage)
-- **Distributed Schedulers** — ShedLock + Redis for cluster-safe distributed job scheduling; offline device detection, API key stats sync, MDM fleet setup
-- **External REST API** — API key–authenticated integration surface for third-party tools with OpenAPI documentation
-- **Tool SDKs** — First-class Java clients for Tactical RMM, Fleet MDM, and MeshCentral
-- **Modular Maven Structure** — 30+ independent modules; include only what your service needs
-- **Spring Boot 3.3 / Java 21** — Modern LTS Java with Spring Security OAuth2 and virtual thread readiness
+[![Watch What's New in OpenFrame 0.7.8](https://img.youtube.com/vi/BQAjDB4ED2Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=BQAjDB4ED2Y)
 
 ---
 
-## Architecture
+[![OpenFrame: 5-Minute MSP Platform Walkthrough - Cut Vendor Costs & Automate Ops](https://img.youtube.com/vi/er-z6IUnAps/hqdefault.jpg)](https://www.youtube.com/watch?v=er-z6IUnAps)
+
+---
+
+## ✨ Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Multi-Tenant Identity** | OAuth2 Authorization Server with per-tenant RSA key pairs and OIDC support |
+| **Reactive API Layer** | REST + GraphQL (Netflix DGS) with Relay-style pagination and DataLoader batching |
+| **Gateway & WebSocket Routing** | Spring Cloud Gateway with JWT validation, rate limiting, and tool proxying |
+| **MongoDB Data Layer** | Reactive + sync repositories, cursor pagination, multi-tenant scoping |
+| **Kafka Stream Processing** | Debezium CDC ingestion, event normalization, and Kafka Streams enrichment |
+| **Management & Operations** | Distributed schedulers, migration support (Mongock), NATS initialization |
+| **Frontend UI & AI Chat** | Embeddable React AI assistant (Guide + Mingo modes), Kanban, Notifications |
+| **Integrated Tool SDKs** | Native SDKs for MeshCentral, Tactical RMM, and Fleet MDM |
+| **Shared API Contracts** | Centralized DTOs, filters, and pagination primitives for all services |
+
+---
+
+## 🏗️ Architecture
+
+The platform is structured as an event-driven, reactive microservice stack with strict multi-tenant isolation:
 
 ```mermaid
 flowchart TD
-    Client["Client / Browser / Agent"] --> Gateway["Gateway Service Core"]
-    Gateway --> ExternalAPI["External API Service Core"]
-    Gateway --> ApiCore["API Service Core (GraphQL + REST)"]
-
-    ApiCore --> Authz["Authorization Service Core (OAuth2 / JWT)"]
-    ApiCore --> Stream["Stream Service Core (Kafka / Debezium)"]
-    ApiCore --> Management["Management Service Core (Schedulers)"]
-
-    Authz --> Mongo["MongoDB"]
-    ApiCore --> Mongo
-    ApiCore --> Redis["Redis"]
-    ApiCore --> Pinot["Apache Pinot"]
-    Stream --> Kafka["Apache Kafka"]
-    Stream --> Cassandra["Apache Cassandra"]
-    Management --> NATS["NATS JetStream"]
+    Frontend["Frontend Core UI and Chat"]
+    Gateway["Gateway Service Core"]
+    Auth["Authorization Service Core"]
+    API["API Service Core (HTTP + GraphQL)"]
+    Management["Management Service Core"]
+    Data["Data Models and Repositories (MongoDB)"]
+    Stream["Stream Processing (Kafka)"]
+    Cassandra["Cassandra (Unified Event Log)"]
+    Tools["Integrated Tools (MeshCentral / Tactical RMM / Fleet MDM)"]
+    Redis["Redis (Cache + Distributed Locks)"]
+    NATS["NATS (Agent Messaging)"]
+
+    Frontend --> Gateway
+    Gateway --> Auth
+    Gateway --> API
+    Gateway --> Tools
+    API --> Data
+    API --> Stream
+    Stream --> Cassandra
+    Stream --> Data
+    Management --> Data
+    Management --> Redis
+    Management --> NATS
+    Tools --> Stream
 ```
 
----
-
-## Technology Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Language | Java 21 |
-| Framework | Spring Boot 3.3 |
-| Build Tool | Apache Maven 3.9+ |
-| Auth | Spring Authorization Server, Spring Security OAuth2 |
-| API | Netflix DGS (GraphQL), Spring MVC (REST) |
-| Gateway | Spring Cloud Gateway + WebFlux + Netty |
-| Persistence | MongoDB (sync + reactive), Redis, Cassandra, Apache Pinot |
-| Messaging | Apache Kafka / Debezium CDC, NATS JetStream |
-| Testing | JUnit 5, Testcontainers, RestAssured |
-| Distributed Locking | ShedLock + Redis |
-| Multi-tenancy | ThreadLocal tenant context, per-tenant RSA keys |
+### Service Modules
+
+| Module | Role |
+|--------|------|
+| `openframe-gateway-service-core` | Reactive edge — JWT validation, rate limiting, WebSocket proxying, tool routing |
+| `openframe-authorization-service-core` | Multi-tenant OAuth2/OIDC — JWT issuance, SSO (Google/Microsoft) |
+| `openframe-api-service-core` | REST + GraphQL (Netflix DGS) — DataLoader batching, Relay pagination |
+| `openframe-api-lib` | Shared DTOs, filter criteria, pagination primitives |
+| `openframe-data-mongo-common` | MongoDB document models and base repositories |
+| `openframe-data-mongo-sync` | Synchronous MongoDB repositories with custom cursor pagination |
+| `openframe-data-mongo-reactive` | Reactive MongoDB repositories for auth flows |
+| `openframe-data-redis` | API key stats, rate limiting, ShedLock distributed locking |
+| `openframe-data-kafka` | Kafka producers with retry and recovery |
+| `openframe-data-nats` | NATS pub/sub, agent notifications, command dispatch |
+| `openframe-stream-service-core` | Debezium CDC ingestion, event normalization, Kafka Streams |
+| `openframe-management-service-core` | Cluster coordination, tool lifecycle, schedulers, migrations |
+| `openframe-client-core` | Device registration, authentication, tool installation |
+| `openframe-security-core` | JWT primitives, `AuthPrincipal`, cookie service |
+| `openframe-frontend-core` | React component library, AI chat engine (Guide + Mingo modes) |
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ### Prerequisites
 
-- Java 21 JDK ([Eclipse Temurin 21](https://adoptium.net/) recommended)
-- Apache Maven 3.9+
-- Docker 24.x (for integration tests)
-- GitHub Personal Access Token (PAT) with `read:packages` scope
+| Tool | Version |
+|------|---------|
+| **Java (JDK)** | 21+ |
+| **Apache Maven** | 3.8+ |
+| **Git** | 2.x+ |
+| **Docker** | 24.x+ |
+| **Node.js** | 18+ (for frontend-core only) |
 
 ### 1. Clone the Repository
 
@@ -94,7 +117,7 @@ git clone https://github.com/flamingo-stack/openframe-oss-lib.git
 cd openframe-oss-lib
 ```
 
-### 2. Configure GitHub Packages
+### 2. Configure GitHub Packages Access
 
 Add your GitHub credentials to `~/.m2/settings.xml`:
 
@@ -104,45 +127,45 @@ Add your GitHub credentials to `~/.m2/settings.xml`:
     <server>
       <id>github</id>
       <username>YOUR_GITHUB_USERNAME</username>
-      <password>YOUR_GITHUB_PAT</password>
+      <password>YOUR_GITHUB_TOKEN</password>
     </server>
   </servers>
 </settings>
 ```
 
-### 3. Build the Library
+Generate a GitHub Personal Access Token (PAT) with `read:packages` scope from [GitHub Settings → Developer Settings](https://github.com/settings/tokens).
+
+### 3. Build All Modules
 
 ```bash
+# Build all modules (skip tests for speed)
 mvn install -DskipTests
 ```
 
-### 4. Add a Module as a Dependency
+### 4. Use a Module as a Dependency
 
 ```xml
-<dependencyManagement>
-  <dependencies>
-    <dependency>
-      <groupId>com.openframe.oss</groupId>
-      <artifactId>openframe-oss-lib</artifactId>
-      <version>5.79.3</version>
-      <type>pom</type>
-      <scope>import</scope>
-    </dependency>
-  </dependencies>
-</dependencyManagement>
-
-<dependencies>
-  <dependency>
+<dependency>
     <groupId>com.openframe.oss</groupId>
-    <artifactId>openframe-api-service-core</artifactId>
-  </dependency>
-</dependencies>
+    <artifactId>openframe-core</artifactId>
+    <version>6.0.10</version>
+</dependency>
+```
+
+Or inherit the parent POM for aligned dependency management:
+
+```xml
+<parent>
+    <groupId>com.openframe.oss</groupId>
+    <artifactId>openframe-oss-lib</artifactId>
+    <version>6.0.10</version>
+</parent>
 ```
 
 ### 5. Run Tests
 
 ```bash
-# Unit tests for a specific module
+# Unit tests (no Docker required)
 mvn test -pl openframe-core
 
 # Integration tests (requires Docker)
@@ -151,50 +174,71 @@ mvn verify -pl openframe-data-mongo-sync
 
 ---
 
-## Module Overview
-
-| Module | Description |
-|--------|-------------|
-| `openframe-core` | Core utilities, pagination, validation |
-| `openframe-exception` | Standard exception hierarchy |
-| `openframe-core-crypto` | Encryption utilities |
-| `openframe-security-core` | JWT, PKCE, cookie service |
-| `openframe-security-oauth` | OAuth2 BFF layer |
-| `openframe-authorization-service-core` | Multi-tenant OAuth2 authorization server |
-| `openframe-api-lib` | API contracts, filter DTOs, cursor pagination |
-| `openframe-api-service-core` | REST + GraphQL API service layer |
-| `openframe-gateway-service-core` | Reactive gateway, routing, security |
-| `openframe-data-mongo-common` | MongoDB domain documents |
-| `openframe-data-mongo-sync` | Synchronous MongoDB repositories |
-| `openframe-data-mongo-reactive` | Reactive MongoDB repositories |
-| `openframe-data-redis` | Redis tenant-aware cache |
-| `openframe-data-kafka` | Kafka multi-tenant configuration |
-| `openframe-data-nats` | NATS real-time messaging |
-| `openframe-data-cassandra` | Cassandra log storage |
-| `openframe-data-pinot` | Apache Pinot analytics queries |
-| `openframe-management-service-core` | Distributed schedulers, startup initializers |
-| `openframe-stream-service-core` | Kafka streams, Debezium event enrichment |
-| `openframe-external-api-service-core` | External REST API for integrations |
-| `sdk/fleetmdm` | Fleet MDM Java SDK |
-| `sdk/tacticalrmm` | Tactical RMM Java SDK |
+## 🧰 Technology Stack
+
+### Backend
+
+| Technology | Version | Role |
+|-----------|---------|------|
+| **Java** | 21 | Primary language |
+| **Spring Boot** | 3.3.0 | Application framework |
+| **Spring Cloud** | 2023.0.3 | Cloud-native patterns |
+| **Netflix DGS** | 9.0.3 | GraphQL framework |
+| **MongoDB** | Reactive + Sync | Primary data store |
+| **Apache Kafka** | 3.x | Event streaming |
+| **NATS** | 0.6.2+3.5 | Lightweight messaging |
+| **Redis** | Spring Data Redis | Caching + distributed locks |
+| **Apache Cassandra** | – | Event log storage |
+| **Apache Pinot** | 1.2.0 | Analytics |
+| **Lombok** | 1.18.30 | Boilerplate reduction |
+| **Testcontainers** | 1.21.4 | Integration testing |
+
+### Frontend (`openframe-frontend-core`)
+
+| Technology | Role |
+|-----------|------|
+| **React** | UI component library |
+| **TypeScript** | Type-safe UI development |
+| **Tailwind CSS** | Utility-first styling |
+| **NATS WebSocket** | Real-time chat transport |
+| **SSE** | Guide mode AI chat transport |
+| **Storybook** | Component development and documentation |
+| **Vitest** | Unit testing |
 
 ---
 
-## Documentation
+## 📚 Documentation
+
+📖 See the [Documentation](./docs/README.md) for comprehensive guides including:
 
-📚 See the [Documentation](./docs/README.md) for comprehensive guides covering architecture, setup, development workflows, and reference documentation.
+- [Getting Started](./docs/getting-started/introduction.md) — Introduction and platform overview
+- [Prerequisites](./docs/getting-started/prerequisites.md) — Environment setup
+- [Quick Start](./docs/getting-started/quick-start.md) — Up and running in 5 minutes
+- [First Steps](./docs/getting-started/first-steps.md) — Key things to explore
+- [Architecture Overview](./docs/development/architecture/README.md) — System design and data flows
+- [Contributing Guidelines](./docs/development/contributing/guidelines.md) — How to contribute
 
 ---
 
-## Community
+## 🤝 Community
 
-All discussions, questions, and support happen on the **[OpenMSP Slack Community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)**. We do not use GitHub Issues or GitHub Discussions.
+All discussions, questions, and feature requests are managed on the **OpenMSP Slack** community.
+
+[![Join OpenMSP Slack](https://img.shields.io/badge/Slack-OpenMSP-blue?logo=slack)](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+
+- **Questions**: `#dev-questions` channel
+- **Feature Requests**: `#roadmap` channel
+- **Bug Reports**: `#bugs` channel
+
+> We do **not** use GitHub Issues or GitHub Discussions. Everything is managed on [OpenMSP Slack](https://www.openmsp.ai/).
+
+---
 
-- 🌐 **OpenFrame Platform:** [https://openframe.ai](https://openframe.ai)
-- 💬 **OpenMSP Slack:** [https://www.openmsp.ai/](https://www.openmsp.ai/)
-- 🦩 **Flamingo:** [https://flamingo.run](https://flamingo.run)
+## 🔗 Links
 
-[![OpenFrame v0.5.2: Autonomous AI Agent Architecture for MSPs](https://img.youtube.com/vi/PexpoNdZtUk/maxresdefault.jpg)](https://www.youtube.com/watch?v=PexpoNdZtUk)
+- [OpenFrame Platform](https://openframe.ai)
+- [Flamingo](https://flamingo.run)
+- [OpenMSP Community](https://www.openmsp.ai/)
 
 ---
 
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..548152565
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,96 @@
+# OpenFrame OSS Lib — Documentation
+
+Welcome to the `openframe-oss-lib` documentation. This is the modular backbone of [OpenFrame](https://openframe.ai) — Flamingo's AI-powered MSP platform.
+
+> 📣 All discussions, questions, and feature requests are managed on [OpenMSP Slack](https://www.openmsp.ai/). We do **not** use GitHub Issues or GitHub Discussions.
+
+---
+
+## 📚 Table of Contents
+
+- [Getting Started](#-getting-started)
+- [Development](#-development)
+- [Reference Architecture](#-reference-architecture)
+- [Architecture Diagrams](#-architecture-diagrams)
+- [Quick Links](#-quick-links)
+
+---
+
+## 🚀 Getting Started
+
+New to `openframe-oss-lib`? Start here:
+
+| Document | Description |
+|----------|-------------|
+| [Introduction](./getting-started/introduction.md) | What OpenFrame OSS Lib is, key features, and the platform overview |
+| [Prerequisites](./getting-started/prerequisites.md) | Required tools, system requirements, and infrastructure dependencies |
+| [Quick Start](./getting-started/quick-start.md) | Clone, build, and use a module as a dependency in 5 minutes |
+| [First Steps](./getting-started/first-steps.md) | Explore module structure, domain models, tests, and the community |
+
+---
+
+## 🛠️ Development
+
+Guides for working with and contributing to the codebase:
+
+| Document | Description |
+|----------|-------------|
+| [Development Overview](./development/README.md) | Technology stack, module organization, and community links |
+| [Environment Setup](./development/setup/environment.md) | IDE setup, Java 21, Maven, Docker, and Node.js installation |
+| [Local Development](./development/setup/local-development.md) | Build commands, running tests, debugging, and Maven workflows |
+| [Architecture Overview](./development/architecture/README.md) | High-level system design, request flows, and design decisions |
+| [Security Guidelines](./development/security/README.md) | Auth architecture, secrets management, and secure coding practices |
+| [Testing Guide](./development/testing/README.md) | Test structure, Testcontainers, writing unit and integration tests |
+| [Contributing Guidelines](./development/contributing/guidelines.md) | Code style, branch naming, commit messages, and PR process |
+
+---
+
+## 📐 Reference Architecture
+
+Deep-dive documentation for each major module, generated from source code analysis:
+
+| Module | Description |
+|--------|-------------|
+| [API Lib Contracts](./reference/architecture/api-lib-contracts/api-lib-contracts.md) | Shared DTOs, filter criteria, Relay pagination primitives, and mappers |
+| [API Service Core (HTTP + GraphQL)](./reference/architecture/api-service-core-http-and-graphql/api-service-core-http-and-graphql.md) | REST controllers, GraphQL DGS DataFetchers, DataLoaders, and security |
+| [Authorization Service Core](./reference/architecture/authorization-service-core/authorization-service-core.md) | Multi-tenant OAuth2/OIDC, JWT issuance, SSO (Google/Microsoft), Mongo persistence |
+| [Gateway Service Core](./reference/architecture/gateway-service-core/gateway-service-core.md) | Reactive edge layer — JWT validation, API key auth, rate limiting, WebSocket proxying |
+| [Data Models and Repositories (Mongo)](./reference/architecture/data-models-and-repositories-mongo/data-models-and-repositories-mongo.md) | MongoDB documents, reactive + sync repositories, cursor pagination, tenant isolation |
+| [Management Service Core](./reference/architecture/management-service-core/management-service-core.md) | Operational control plane — schedulers, migrations (Mongock), NATS initialization |
+| [Stream Processing (Kafka)](./reference/architecture/stream-processing-kafka/stream-processing-kafka.md) | Debezium CDC ingestion, event normalization, Kafka Streams enrichment, Cassandra persistence |
+| [Frontend Core UI and Chat](./reference/architecture/frontend-core-ui-and-chat/frontend-core-ui-and-chat.md) | Embeddable AI assistant, Kanban board, Ticket Center, Notifications, DataTable system |
+
+---
+
+## 🗺️ Architecture Diagrams
+
+Visual Mermaid diagrams are available in the `docs/diagrams/architecture/` directory. Each module has multiple diagrams covering data flows, component relationships, and sequence interactions:
+
+| Diagram Set | Module |
+|------------|--------|
+| `docs/diagrams/architecture/README*.mmd` | Overall platform architecture |
+| `docs/diagrams/architecture/api-service-core-http-and-graphql*.mmd` | API layer flows |
+| `docs/diagrams/architecture/authorization-service-core*.mmd` | Auth and token flows |
+| `docs/diagrams/architecture/gateway-service-core*.mmd` | Gateway routing and security |
+| `docs/diagrams/architecture/data-models-and-repositories-mongo*.mmd` | Data layer architecture |
+| `docs/diagrams/architecture/management-service-core*.mmd` | Management and scheduling flows |
+| `docs/diagrams/architecture/stream-processing-kafka*.mmd` | Event ingestion pipeline |
+| `docs/diagrams/architecture/frontend-core-ui-and-chat*.mmd` | UI and chat architecture |
+| `docs/diagrams/architecture/api-lib-contracts*.mmd` | Contract layer relationships |
+
+---
+
+## 🔗 Quick Links
+
+| Resource | Link |
+|----------|------|
+| **Project README** | [../README.md](../README.md) |
+| **Contributing Guide** | [../CONTRIBUTING.md](../CONTRIBUTING.md) |
+| **OpenFrame Platform** | [https://openframe.ai](https://openframe.ai) |
+| **Flamingo** | [https://flamingo.run](https://flamingo.run) |
+| **OpenMSP Community** | [https://www.openmsp.ai/](https://www.openmsp.ai/) |
+| **Join Slack** | [OpenMSP Slack Invite](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) |
+
+---
+
+*Documentation generated by [OpenFrame Doc Orchestrator](https://github.com/flamingo-stack/openframe-oss-tenant)*