fix(web): QA fixes on users settings page (MS21-UI-001-QA)

Reviewed-on: #597

.mosaic/orchestrator/mission.json

@@ -1,14 +1,90 @@
 {
   "schema_version": 1,
-  "mission_id": "prd-implementation-20260222",
-  "name": "PRD implementation",
-  "description": "",
+  "mission_id": "ms21-multi-tenant-rbac-data-migration-20260228",
+  "name": "MS21 Multi-Tenant RBAC Data Migration",
+  "description": "Build multi-tenant user/workspace/team management, break-glass auth, RBAC UI enforcement, and migrate jarvis-brain data into Mosaic Stack",
   "project_path": "/home/jwoltje/src/mosaic-stack",
-  "created_at": "2026-02-23T03:20:55Z",
+  "created_at": "2026-02-28T17:10:22Z",
   "status": "active",
-  "task_prefix": "",
-  "quality_gates": "",
-  "milestone_version": "0.0.20",
-  "milestones": [],
-  "sessions": []
+  "task_prefix": "MS21",
+  "quality_gates": "pnpm lint && pnpm build && pnpm test",
+  "milestone_version": "0.0.21",
+  "milestones": [
+    {
+      "id": "phase-1",
+      "name": "Schema and Admin API",
+      "status": "pending",
+      "branch": "schema-and-admin-api",
+      "issue_ref": "",
+      "started_at": "",
+      "completed_at": ""
+    },
+    {
+      "id": "phase-2",
+      "name": "Break-Glass Authentication",
+      "status": "pending",
+      "branch": "break-glass-authentication",
+      "issue_ref": "",
+      "started_at": "",
+      "completed_at": ""
+    },
+    {
+      "id": "phase-3",
+      "name": "Data Migration",
+      "status": "pending",
+      "branch": "data-migration",
+      "issue_ref": "",
+      "started_at": "",
+      "completed_at": ""
+    },
+    {
+      "id": "phase-4",
+      "name": "Admin UI",
+      "status": "pending",
+      "branch": "admin-ui",
+      "issue_ref": "",
+      "started_at": "",
+      "completed_at": ""
+    },
+    {
+      "id": "phase-5",
+      "name": "RBAC UI Enforcement",
+      "status": "pending",
+      "branch": "rbac-ui-enforcement",
+      "issue_ref": "",
+      "started_at": "",
+      "completed_at": ""
+    },
+    {
+      "id": "phase-6",
+      "name": "Verification",
+      "status": "pending",
+      "branch": "verification",
+      "issue_ref": "",
+      "started_at": "",
+      "completed_at": ""
+    }
+  ],
+  "sessions": [
+    {
+      "session_id": "sess-001",
+      "runtime": "unknown",
+      "started_at": "2026-02-28T17:48:51Z",
+      "ended_at": "",
+      "ended_reason": "",
+      "milestone_at_end": "",
+      "tasks_completed": [],
+      "last_task_id": ""
+    },
+    {
+      "session_id": "sess-002",
+      "runtime": "unknown",
+      "started_at": "2026-02-28T20:30:13Z",
+      "ended_at": "",
+      "ended_reason": "",
+      "milestone_at_end": "",
+      "tasks_completed": [],
+      "last_task_id": ""
+    }
+  ]
 }

.mosaic/orchestrator/session.lock

@@ -0,0 +1,8 @@
+{
+  "session_id": "sess-002",
+  "runtime": "unknown",
+  "pid": 3178395,
+  "started_at": "2026-02-28T20:30:13Z",
+  "project_path": "/tmp/ms21-ui-001",
+  "milestone_id": ""
+}

.trivyignore

@@ -34,3 +34,9 @@ CVE-2026-26996  # HIGH: minimatch DoS via specially crafted glob patterns (needs
 # OpenBao 2.5.0 compiled with Go 1.25.6, fix needs Go >= 1.25.7.
 # Cannot build OpenBao from source (large project). Waiting for upstream release.
 CVE-2025-68121  # CRITICAL: crypto/tls session resumption
+
+# === multer CVEs (upstream via @nestjs/platform-express) ===
+# multer <2.1.0 — waiting on NestJS to update their dependency
+# These are DoS vulnerabilities in file upload handling
+GHSA-xf7r-hgr6-v32p  # HIGH: DoS via incomplete cleanup
+GHSA-v52c-386h-88mc  # HIGH: DoS via resource exhaustion

.woodpecker/api.yml

@@ -1,232 +0,0 @@
-# API Pipeline - Mosaic Stack
-# Quality gates, build, and Docker publish for @mosaic/api
-#
-# Triggers on: apps/api/**, packages/**, root configs
-# Security chain: source audit + Trivy container scan
-
-when:
-  - event: [push, pull_request, manual]
-    path:
-      include:
-        - "apps/api/**"
-        - "packages/**"
-        - "pnpm-lock.yaml"
-        - "pnpm-workspace.yaml"
-        - "turbo.json"
-        - "package.json"
-        - ".woodpecker/api.yml"
-        - ".trivyignore"
-
-variables:
-  - &node_image "node:24-alpine"
-  - &install_deps |
-    corepack enable
-    pnpm install --frozen-lockfile
-  - &use_deps |
-    corepack enable
-  - &turbo_env
-    TURBO_API:
-      from_secret: turbo_api
-    TURBO_TOKEN:
-      from_secret: turbo_token
-    TURBO_TEAM:
-      from_secret: turbo_team
-  - &kaniko_setup |
-    mkdir -p /kaniko/.docker
-    echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$GITEA_USER\",\"password\":\"$GITEA_TOKEN\"}}}" > /kaniko/.docker/config.json
-
-services:
-  postgres:
-    image: postgres:17.7-alpine3.22
-    environment:
-      POSTGRES_DB: test_db
-      POSTGRES_USER: test_user
-      POSTGRES_PASSWORD: test_password
-
-steps:
-  # === Quality Gates ===
-
-  install:
-    image: *node_image
-    commands:
-      - *install_deps
-
-  security-audit:
-    image: *node_image
-    commands:
-      - *use_deps
-      - pnpm audit --audit-level=high
-    depends_on:
-      - install
-
-  prisma-generate:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-    commands:
-      - *use_deps
-      - pnpm --filter "@mosaic/api" prisma:generate
-    depends_on:
-      - install
-
-  lint:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo lint --filter=@mosaic/api
-    depends_on:
-      - prisma-generate
-
-  typecheck:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo typecheck --filter=@mosaic/api
-    depends_on:
-      - prisma-generate
-
-  prisma-migrate:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      DATABASE_URL: "postgresql://test_user:test_password@postgres:5432/test_db?schema=public"
-    commands:
-      - *use_deps
-      - pnpm --filter "@mosaic/api" prisma migrate deploy
-    depends_on:
-      - prisma-generate
-
-  test:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      DATABASE_URL: "postgresql://test_user:test_password@postgres:5432/test_db?schema=public"
-      ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
-    commands:
-      - *use_deps
-      - pnpm --filter "@mosaic/api" exec vitest run --exclude 'src/auth/auth-rls.integration.spec.ts' --exclude 'src/credentials/user-credential.model.spec.ts' --exclude 'src/job-events/job-events.performance.spec.ts' --exclude 'src/knowledge/services/fulltext-search.spec.ts' --exclude 'src/mosaic-telemetry/mosaic-telemetry.module.spec.ts'
-    depends_on:
-      - prisma-migrate
-
-  # === Build ===
-
-  build:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      NODE_ENV: "production"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo build --filter=@mosaic/api
-    depends_on:
-      - lint
-      - typecheck
-      - test
-      - security-audit
-
-  # === Docker Build & Push ===
-
-  docker-build-api:
-    image: gcr.io/kaniko-project/executor:debug
-    environment:
-      GITEA_USER:
-        from_secret: gitea_username
-      GITEA_TOKEN:
-        from_secret: gitea_token
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-    commands:
-      - *kaniko_setup
-      - |
-        DESTINATIONS=""
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-api:$CI_COMMIT_TAG"
-        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-api:latest"
-        fi
-        /kaniko/executor --context . --dockerfile apps/api/Dockerfile --snapshot-mode=redo $DESTINATIONS
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - build
-
-  # === Container Security Scan ===
-
-  security-trivy-api:
-    image: aquasec/trivy:latest
-    environment:
-      GITEA_USER:
-        from_secret: gitea_username
-      GITEA_TOKEN:
-        from_secret: gitea_token
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-    commands:
-      - |
-        if [ -n "$$CI_COMMIT_TAG" ]; then
-          SCAN_TAG="$$CI_COMMIT_TAG"
-        elif [ "$$CI_COMMIT_BRANCH" = "main" ]; then
-          SCAN_TAG="latest"
-        else
-          SCAN_TAG="latest"
-        fi
-        mkdir -p ~/.docker
-        echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
-        trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed \
-          --ignorefile .trivyignore \
-          git.mosaicstack.dev/mosaic/stack-api:$$SCAN_TAG
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - docker-build-api
-
-  # === Package Linking ===
-
-  link-packages:
-    image: alpine:3
-    environment:
-      GITEA_TOKEN:
-        from_secret: gitea_token
-    commands:
-      - apk add --no-cache curl
-      - sleep 10
-      - |
-        set -e
-        link_package() {
-          PKG="$$1"
-          echo "Linking $$PKG..."
-          for attempt in 1 2 3; do
-            STATUS=$$(curl -s -o /tmp/link-response.txt -w "%{http_code}" -X POST \
-              -H "Authorization: token $$GITEA_TOKEN" \
-              "https://git.mosaicstack.dev/api/v1/packages/mosaic/container/$$PKG/-/link/stack")
-            if [ "$$STATUS" = "201" ] || [ "$$STATUS" = "204" ]; then
-              echo "  Linked $$PKG"
-              return 0
-            elif [ "$$STATUS" = "400" ]; then
-              echo "  $$PKG already linked"
-              return 0
-            elif [ "$$STATUS" = "404" ] && [ $$attempt -lt 3 ]; then
-              echo "  $$PKG not found yet, retrying in 5s (attempt $$attempt/3)..."
-              sleep 5
-            else
-              echo "  FAILED: $$PKG status $$STATUS"
-              cat /tmp/link-response.txt
-              return 1
-            fi
-          done
-        }
-        link_package "stack-api"
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - security-trivy-api

.woodpecker/ci.yml

@@ -0,0 +1,337 @@
+# Unified CI Pipeline - Mosaic Stack
+# Single install, parallel quality gates, sequential deploy
+#
+# Replaces: api.yml, orchestrator.yml, web.yml
+# Keeps: coordinator.yml (Python), infra.yml (separate concerns)
+#
+# Flow:
+#   install → security-audit
+#           → prisma-generate → lint + typecheck (parallel)
+#                              → prisma-migrate → test
+#           → build (after all gates pass)
+#           → docker builds (main only, parallel)
+#           → trivy scans (main only, parallel)
+#           → package linking (main only)
+
+when:
+  - event: [push, pull_request, manual]
+    path:
+      include:
+        - "apps/api/**"
+        - "apps/orchestrator/**"
+        - "apps/web/**"
+        - "packages/**"
+        - "pnpm-lock.yaml"
+        - "pnpm-workspace.yaml"
+        - "turbo.json"
+        - "package.json"
+        - ".woodpecker/ci.yml"
+        - ".trivyignore"
+
+variables:
+  - &node_image "node:24-alpine"
+  - &install_deps |
+    corepack enable
+    pnpm install --frozen-lockfile
+  - &use_deps |
+    corepack enable
+  - &turbo_env
+    TURBO_API:
+      from_secret: turbo_api
+    TURBO_TOKEN:
+      from_secret: turbo_token
+    TURBO_TEAM:
+      from_secret: turbo_team
+  - &kaniko_setup |
+    mkdir -p /kaniko/.docker
+    echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$GITEA_USER\",\"password\":\"$GITEA_TOKEN\"}}}" > /kaniko/.docker/config.json
+
+services:
+  postgres:
+    image: postgres:17.7-alpine3.22
+    environment:
+      POSTGRES_DB: test_db
+      POSTGRES_USER: test_user
+      POSTGRES_PASSWORD: test_password
+
+steps:
+  # ─── Install (once) ─────────────────────────────────────────
+  install:
+    image: *node_image
+    commands:
+      - *install_deps
+
+  # ─── Security Audit (once) ──────────────────────────────────
+  security-audit:
+    image: *node_image
+    commands:
+      - *use_deps
+      - pnpm audit --audit-level=high
+    depends_on:
+      - install
+
+  # ─── Prisma Generate ────────────────────────────────────────
+  prisma-generate:
+    image: *node_image
+    environment:
+      SKIP_ENV_VALIDATION: "true"
+    commands:
+      - *use_deps
+      - pnpm --filter "@mosaic/api" prisma:generate
+    depends_on:
+      - install
+
+  # ─── Lint (all packages) ────────────────────────────────────
+  lint:
+    image: *node_image
+    environment:
+      SKIP_ENV_VALIDATION: "true"
+      <<: *turbo_env
+    commands:
+      - *use_deps
+      - pnpm turbo lint
+    depends_on:
+      - prisma-generate
+
+  # ─── Typecheck (all packages, parallel with lint) ───────────
+  typecheck:
+    image: *node_image
+    environment:
+      SKIP_ENV_VALIDATION: "true"
+      <<: *turbo_env
+    commands:
+      - *use_deps
+      - pnpm turbo typecheck
+    depends_on:
+      - prisma-generate
+
+  # ─── Prisma Migrate (test DB) ──────────────────────────────
+  prisma-migrate:
+    image: *node_image
+    environment:
+      SKIP_ENV_VALIDATION: "true"
+      DATABASE_URL: "postgresql://test_user:test_password@postgres:5432/test_db?schema=public"
+    commands:
+      - *use_deps
+      - pnpm --filter "@mosaic/api" prisma migrate deploy
+    depends_on:
+      - prisma-generate
+
+  # ─── Test (all packages) ───────────────────────────────────
+  test:
+    image: *node_image
+    environment:
+      SKIP_ENV_VALIDATION: "true"
+      DATABASE_URL: "postgresql://test_user:test_password@postgres:5432/test_db?schema=public"
+      ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+      <<: *turbo_env
+    commands:
+      - *use_deps
+      - pnpm --filter "@mosaic/api" exec vitest run --exclude 'src/auth/auth-rls.integration.spec.ts' --exclude 'src/credentials/user-credential.model.spec.ts' --exclude 'src/job-events/job-events.performance.spec.ts' --exclude 'src/knowledge/services/fulltext-search.spec.ts' --exclude 'src/mosaic-telemetry/mosaic-telemetry.module.spec.ts'
+      - pnpm turbo test --filter=@mosaic/orchestrator --filter=@mosaic/web
+    depends_on:
+      - prisma-migrate
+
+  # ─── Build (all packages) ──────────────────────────────────
+  build:
+    image: *node_image
+    environment:
+      SKIP_ENV_VALIDATION: "true"
+      NODE_ENV: "production"
+      <<: *turbo_env
+    commands:
+      - *use_deps
+      - pnpm turbo build
+    depends_on:
+      - lint
+      - typecheck
+      - test
+      - security-audit
+
+  # ─── Docker Builds (main only, parallel) ───────────────────
+
+  docker-build-api:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+    commands:
+      - *kaniko_setup
+      - |
+        DESTINATIONS=""
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-api:$CI_COMMIT_TAG"
+        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-api:latest"
+        fi
+        /kaniko/executor --context . --dockerfile apps/api/Dockerfile --snapshot-mode=redo $DESTINATIONS
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - build
+
+  docker-build-orchestrator:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+    commands:
+      - *kaniko_setup
+      - |
+        DESTINATIONS=""
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-orchestrator:$CI_COMMIT_TAG"
+        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-orchestrator:latest"
+        fi
+        /kaniko/executor --context . --dockerfile apps/orchestrator/Dockerfile --snapshot-mode=redo $DESTINATIONS
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - build
+
+  docker-build-web:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+    commands:
+      - *kaniko_setup
+      - |
+        DESTINATIONS=""
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-web:$CI_COMMIT_TAG"
+        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-web:latest"
+        fi
+        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --snapshot-mode=redo --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - build
+
+  # ─── Container Security Scans (main only) ──────────────────
+
+  security-trivy-api:
+    image: aquasec/trivy:latest
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+    commands:
+      - |
+        if [ -n "$$CI_COMMIT_TAG" ]; then SCAN_TAG="$$CI_COMMIT_TAG"; else SCAN_TAG="latest"; fi
+        mkdir -p ~/.docker
+        echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
+        trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --ignorefile .trivyignore git.mosaicstack.dev/mosaic/stack-api:$$SCAN_TAG
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - docker-build-api
+
+  security-trivy-orchestrator:
+    image: aquasec/trivy:latest
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+    commands:
+      - |
+        if [ -n "$$CI_COMMIT_TAG" ]; then SCAN_TAG="$$CI_COMMIT_TAG"; else SCAN_TAG="latest"; fi
+        mkdir -p ~/.docker
+        echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
+        trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --ignorefile .trivyignore git.mosaicstack.dev/mosaic/stack-orchestrator:$$SCAN_TAG
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - docker-build-orchestrator
+
+  security-trivy-web:
+    image: aquasec/trivy:latest
+    environment:
+      GITEA_USER:
+        from_secret: gitea_username
+      GITEA_TOKEN:
+        from_secret: gitea_token
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+    commands:
+      - |
+        if [ -n "$$CI_COMMIT_TAG" ]; then SCAN_TAG="$$CI_COMMIT_TAG"; else SCAN_TAG="latest"; fi
+        mkdir -p ~/.docker
+        echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
+        trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --ignorefile .trivyignore git.mosaicstack.dev/mosaic/stack-web:$$SCAN_TAG
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - docker-build-web
+
+  # ─── Package Linking (main only, once) ─────────────────────
+
+  link-packages:
+    image: alpine:3
+    environment:
+      GITEA_TOKEN:
+        from_secret: gitea_token
+    commands:
+      - apk add --no-cache curl
+      - sleep 10
+      - |
+        set -e
+        link_package() {
+          PKG="$$1"
+          echo "Linking $$PKG..."
+          for attempt in 1 2 3; do
+            STATUS=$$(curl -s -o /tmp/link-response.txt -w "%{http_code}" -X POST \
+              -H "Authorization: token $$GITEA_TOKEN" \
+              "https://git.mosaicstack.dev/api/v1/packages/mosaic/container/$$PKG/-/link/stack")
+            if [ "$$STATUS" = "201" ] || [ "$$STATUS" = "204" ]; then
+              echo "  Linked $$PKG"
+              return 0
+            elif [ "$$STATUS" = "400" ]; then
+              echo "  $$PKG already linked"
+              return 0
+            elif [ "$$STATUS" = "404" ] && [ $$attempt -lt 3 ]; then
+              echo "  $$PKG not found yet, retrying in 5s (attempt $$attempt/3)..."
+              sleep 5
+            else
+              echo "  FAILED: $$PKG status $$STATUS"
+              cat /tmp/link-response.txt
+              return 1
+            fi
+          done
+        }
+        link_package "stack-api"
+        link_package "stack-orchestrator"
+        link_package "stack-web"
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - security-trivy-api
+      - security-trivy-orchestrator
+      - security-trivy-web

.woodpecker/orchestrator.yml

@@ -1,202 +0,0 @@
-# Orchestrator Pipeline - Mosaic Stack
-# Quality gates, build, and Docker publish for @mosaic/orchestrator
-#
-# Triggers on: apps/orchestrator/**, packages/**, root configs
-# Security chain: source audit + Trivy container scan
-
-when:
-  - event: [push, pull_request, manual]
-    path:
-      include:
-        - "apps/orchestrator/**"
-        - "packages/**"
-        - "pnpm-lock.yaml"
-        - "pnpm-workspace.yaml"
-        - "turbo.json"
-        - "package.json"
-        - ".woodpecker/orchestrator.yml"
-        - ".trivyignore"
-
-variables:
-  - &node_image "node:24-alpine"
-  - &install_deps |
-    corepack enable
-    pnpm install --frozen-lockfile
-  - &use_deps |
-    corepack enable
-  - &turbo_env
-    TURBO_API:
-      from_secret: turbo_api
-    TURBO_TOKEN:
-      from_secret: turbo_token
-    TURBO_TEAM:
-      from_secret: turbo_team
-  - &kaniko_setup |
-    mkdir -p /kaniko/.docker
-    echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$GITEA_USER\",\"password\":\"$GITEA_TOKEN\"}}}" > /kaniko/.docker/config.json
-
-steps:
-  # === Quality Gates ===
-
-  install:
-    image: *node_image
-    commands:
-      - *install_deps
-
-  security-audit:
-    image: *node_image
-    commands:
-      - *use_deps
-      - pnpm audit --audit-level=high
-    depends_on:
-      - install
-
-  lint:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo lint --filter=@mosaic/orchestrator
-    depends_on:
-      - install
-
-  typecheck:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo typecheck --filter=@mosaic/orchestrator
-    depends_on:
-      - install
-
-  test:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo test --filter=@mosaic/orchestrator
-    depends_on:
-      - install
-
-  # === Build ===
-
-  build:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      NODE_ENV: "production"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo build --filter=@mosaic/orchestrator
-    depends_on:
-      - lint
-      - typecheck
-      - test
-      - security-audit
-
-  # === Docker Build & Push ===
-
-  docker-build-orchestrator:
-    image: gcr.io/kaniko-project/executor:debug
-    environment:
-      GITEA_USER:
-        from_secret: gitea_username
-      GITEA_TOKEN:
-        from_secret: gitea_token
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-    commands:
-      - *kaniko_setup
-      - |
-        DESTINATIONS=""
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-orchestrator:$CI_COMMIT_TAG"
-        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-orchestrator:latest"
-        fi
-        /kaniko/executor --context . --dockerfile apps/orchestrator/Dockerfile --snapshot-mode=redo $DESTINATIONS
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - build
-
-  # === Container Security Scan ===
-
-  security-trivy-orchestrator:
-    image: aquasec/trivy:latest
-    environment:
-      GITEA_USER:
-        from_secret: gitea_username
-      GITEA_TOKEN:
-        from_secret: gitea_token
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-    commands:
-      - |
-        if [ -n "$$CI_COMMIT_TAG" ]; then
-          SCAN_TAG="$$CI_COMMIT_TAG"
-        elif [ "$$CI_COMMIT_BRANCH" = "main" ]; then
-          SCAN_TAG="latest"
-        else
-          SCAN_TAG="latest"
-        fi
-        mkdir -p ~/.docker
-        echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
-        trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed \
-          --ignorefile .trivyignore \
-          git.mosaicstack.dev/mosaic/stack-orchestrator:$$SCAN_TAG
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - docker-build-orchestrator
-
-  # === Package Linking ===
-
-  link-packages:
-    image: alpine:3
-    environment:
-      GITEA_TOKEN:
-        from_secret: gitea_token
-    commands:
-      - apk add --no-cache curl
-      - sleep 10
-      - |
-        set -e
-        link_package() {
-          PKG="$$1"
-          echo "Linking $$PKG..."
-          for attempt in 1 2 3; do
-            STATUS=$$(curl -s -o /tmp/link-response.txt -w "%{http_code}" -X POST \
-              -H "Authorization: token $$GITEA_TOKEN" \
-              "https://git.mosaicstack.dev/api/v1/packages/mosaic/container/$$PKG/-/link/stack")
-            if [ "$$STATUS" = "201" ] || [ "$$STATUS" = "204" ]; then
-              echo "  Linked $$PKG"
-              return 0
-            elif [ "$$STATUS" = "400" ]; then
-              echo "  $$PKG already linked"
-              return 0
-            elif [ "$$STATUS" = "404" ] && [ $$attempt -lt 3 ]; then
-              echo "  $$PKG not found yet, retrying in 5s (attempt $$attempt/3)..."
-              sleep 5
-            else
-              echo "  FAILED: $$PKG status $$STATUS"
-              cat /tmp/link-response.txt
-              return 1
-            fi
-          done
-        }
-        link_package "stack-orchestrator"
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - security-trivy-orchestrator

.woodpecker/web.yml

@@ -1,202 +0,0 @@
-# Web Pipeline - Mosaic Stack
-# Quality gates, build, and Docker publish for @mosaic/web
-#
-# Triggers on: apps/web/**, packages/**, root configs
-# Security chain: source audit + Trivy container scan
-
-when:
-  - event: [push, pull_request, manual]
-    path:
-      include:
-        - "apps/web/**"
-        - "packages/**"
-        - "pnpm-lock.yaml"
-        - "pnpm-workspace.yaml"
-        - "turbo.json"
-        - "package.json"
-        - ".woodpecker/web.yml"
-        - ".trivyignore"
-
-variables:
-  - &node_image "node:24-alpine"
-  - &install_deps |
-    corepack enable
-    pnpm install --frozen-lockfile
-  - &use_deps |
-    corepack enable
-  - &turbo_env
-    TURBO_API:
-      from_secret: turbo_api
-    TURBO_TOKEN:
-      from_secret: turbo_token
-    TURBO_TEAM:
-      from_secret: turbo_team
-  - &kaniko_setup |
-    mkdir -p /kaniko/.docker
-    echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$GITEA_USER\",\"password\":\"$GITEA_TOKEN\"}}}" > /kaniko/.docker/config.json
-
-steps:
-  # === Quality Gates ===
-
-  install:
-    image: *node_image
-    commands:
-      - *install_deps
-
-  security-audit:
-    image: *node_image
-    commands:
-      - *use_deps
-      - pnpm audit --audit-level=high
-    depends_on:
-      - install
-
-  lint:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo lint --filter=@mosaic/web
-    depends_on:
-      - install
-
-  typecheck:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo typecheck --filter=@mosaic/web
-    depends_on:
-      - install
-
-  test:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo test --filter=@mosaic/web
-    depends_on:
-      - install
-
-  # === Build ===
-
-  build:
-    image: *node_image
-    environment:
-      SKIP_ENV_VALIDATION: "true"
-      NODE_ENV: "production"
-      <<: *turbo_env
-    commands:
-      - *use_deps
-      - pnpm turbo build --filter=@mosaic/web
-    depends_on:
-      - lint
-      - typecheck
-      - test
-      - security-audit
-
-  # === Docker Build & Push ===
-
-  docker-build-web:
-    image: gcr.io/kaniko-project/executor:debug
-    environment:
-      GITEA_USER:
-        from_secret: gitea_username
-      GITEA_TOKEN:
-        from_secret: gitea_token
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-    commands:
-      - *kaniko_setup
-      - |
-        DESTINATIONS=""
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-web:$CI_COMMIT_TAG"
-        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-web:latest"
-        fi
-        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --snapshot-mode=redo --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - build
-
-  # === Container Security Scan ===
-
-  security-trivy-web:
-    image: aquasec/trivy:latest
-    environment:
-      GITEA_USER:
-        from_secret: gitea_username
-      GITEA_TOKEN:
-        from_secret: gitea_token
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-    commands:
-      - |
-        if [ -n "$$CI_COMMIT_TAG" ]; then
-          SCAN_TAG="$$CI_COMMIT_TAG"
-        elif [ "$$CI_COMMIT_BRANCH" = "main" ]; then
-          SCAN_TAG="latest"
-        else
-          SCAN_TAG="latest"
-        fi
-        mkdir -p ~/.docker
-        echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
-        trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed \
-          --ignorefile .trivyignore \
-          git.mosaicstack.dev/mosaic/stack-web:$$SCAN_TAG
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - docker-build-web
-
-  # === Package Linking ===
-
-  link-packages:
-    image: alpine:3
-    environment:
-      GITEA_TOKEN:
-        from_secret: gitea_token
-    commands:
-      - apk add --no-cache curl
-      - sleep 10
-      - |
-        set -e
-        link_package() {
-          PKG="$$1"
-          echo "Linking $$PKG..."
-          for attempt in 1 2 3; do
-            STATUS=$$(curl -s -o /tmp/link-response.txt -w "%{http_code}" -X POST \
-              -H "Authorization: token $$GITEA_TOKEN" \
-              "https://git.mosaicstack.dev/api/v1/packages/mosaic/container/$$PKG/-/link/stack")
-            if [ "$$STATUS" = "201" ] || [ "$$STATUS" = "204" ]; then
-              echo "  Linked $$PKG"
-              return 0
-            elif [ "$$STATUS" = "400" ]; then
-              echo "  $$PKG already linked"
-              return 0
-            elif [ "$$STATUS" = "404" ] && [ $$attempt -lt 3 ]; then
-              echo "  $$PKG not found yet, retrying in 5s (attempt $$attempt/3)..."
-              sleep 5
-            else
-              echo "  FAILED: $$PKG status $$STATUS"
-              cat /tmp/link-response.txt
-              return 1
-            fi
-          done
-        }
-        link_package "stack-web"
-    when:
-      - branch: [main]
-        event: [push, manual, tag]
-    depends_on:
-      - security-trivy-web

apps/api/package.json

@@ -52,6 +52,7 @@
     "adm-zip": "^0.5.16",
     "archiver": "^7.0.1",
     "axios": "^1.13.5",
+    "bcryptjs": "^3.0.3",
     "better-auth": "^1.4.17",
     "bullmq": "^5.67.2",
     "class-transformer": "^0.5.1",
@@ -85,6 +86,7 @@
     "@swc/core": "^1.10.18",
     "@types/adm-zip": "^0.5.7",
     "@types/archiver": "^7.0.0",
+    "@types/bcryptjs": "^3.0.0",
     "@types/cookie-parser": "^1.4.10",
     "@types/express": "^5.0.1",
     "@types/highlight.js": "^10.1.0",

apps/api/prisma/migrations/20260228000000_ms22_agent_memory/migration.sql

@@ -0,0 +1,24 @@
+-- CreateTable
+CREATE TABLE "agent_memories" (
+    "id" UUID NOT NULL,
+    "workspace_id" UUID NOT NULL,
+    "agent_id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "value" JSONB NOT NULL,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "agent_memories_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "agent_memories_workspace_id_agent_id_key_key" ON "agent_memories"("workspace_id", "agent_id", "key");
+
+-- CreateIndex
+CREATE INDEX "agent_memories_workspace_id_idx" ON "agent_memories"("workspace_id");
+
+-- CreateIndex
+CREATE INDEX "agent_memories_agent_id_idx" ON "agent_memories"("agent_id");
+
+-- AddForeignKey
+ALTER TABLE "agent_memories" ADD CONSTRAINT "agent_memories_workspace_id_fkey" FOREIGN KEY ("workspace_id") REFERENCES "workspaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;

apps/api/prisma/migrations/20260228000000_ms22_conversation_archive/migration.sql

@@ -0,0 +1,33 @@
+-- CreateTable
+CREATE TABLE "conversation_archives" (
+    "id" UUID NOT NULL,
+    "workspace_id" UUID NOT NULL,
+    "session_id" TEXT NOT NULL,
+    "agent_id" TEXT NOT NULL,
+    "messages" JSONB NOT NULL,
+    "message_count" INTEGER NOT NULL,
+    "summary" TEXT NOT NULL,
+    "embedding" vector(1536),
+    "started_at" TIMESTAMPTZ NOT NULL,
+    "ended_at" TIMESTAMPTZ,
+    "metadata" JSONB NOT NULL DEFAULT '{}',
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "conversation_archives_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "conversation_archives_workspace_id_session_id_key" ON "conversation_archives"("workspace_id", "session_id");
+
+-- CreateIndex
+CREATE INDEX "conversation_archives_workspace_id_idx" ON "conversation_archives"("workspace_id");
+
+-- CreateIndex
+CREATE INDEX "conversation_archives_agent_id_idx" ON "conversation_archives"("agent_id");
+
+-- CreateIndex
+CREATE INDEX "conversation_archives_started_at_idx" ON "conversation_archives"("started_at");
+
+-- AddForeignKey
+ALTER TABLE "conversation_archives" ADD CONSTRAINT "conversation_archives_workspace_id_fkey" FOREIGN KEY ("workspace_id") REFERENCES "workspaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;

apps/api/prisma/migrations/20260301194500_add_findings/migration.sql

@@ -0,0 +1,37 @@
+-- CreateTable
+CREATE TABLE "findings" (
+    "id" UUID NOT NULL,
+    "workspace_id" UUID NOT NULL,
+    "task_id" UUID,
+    "agent_id" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "data" JSONB NOT NULL,
+    "summary" TEXT NOT NULL,
+    "embedding" vector(1536),
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "findings_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "findings_id_workspace_id_key" ON "findings"("id", "workspace_id");
+
+-- CreateIndex
+CREATE INDEX "findings_workspace_id_idx" ON "findings"("workspace_id");
+
+-- CreateIndex
+CREATE INDEX "findings_agent_id_idx" ON "findings"("agent_id");
+
+-- CreateIndex
+CREATE INDEX "findings_type_idx" ON "findings"("type");
+
+-- CreateIndex
+CREATE INDEX "findings_task_id_idx" ON "findings"("task_id");
+
+-- AddForeignKey
+ALTER TABLE "findings" ADD CONSTRAINT "findings_workspace_id_fkey" FOREIGN KEY ("workspace_id") REFERENCES "workspaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "findings" ADD CONSTRAINT "findings_task_id_fkey" FOREIGN KEY ("task_id") REFERENCES "agent_tasks"("id") ON DELETE SET NULL ON UPDATE CASCADE;

apps/api/prisma/migrations/20260301211000_ms22_task_assigned_agent/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "tasks" ADD COLUMN "assigned_agent" TEXT;

apps/api/prisma/schema.prisma

@@ -227,6 +227,14 @@ model User {
   createdAt      DateTime @default(now()) @map("created_at") @db.Timestamptz
   updatedAt      DateTime @updatedAt @map("updated_at") @db.Timestamptz
 
+  // MS21: Admin, local auth, and invitation fields
+  deactivatedAt   DateTime?  @map("deactivated_at") @db.Timestamptz
+  isLocalAuth     Boolean    @default(false) @map("is_local_auth")
+  passwordHash    String?    @map("password_hash")
+  invitedBy       String?    @map("invited_by") @db.Uuid
+  invitationToken String?    @unique @map("invitation_token")
+  invitedAt       DateTime?  @map("invited_at") @db.Timestamptz
+
   // Relations
   ownedWorkspaces        Workspace[]             @relation("WorkspaceOwner")
   workspaceMemberships   WorkspaceMember[]
@@ -290,6 +298,8 @@ model Workspace {
   agents                       Agent[]
   agentSessions                AgentSession[]
   agentTasks                   AgentTask[]
+  findings                     Finding[]
+  agentMemories                AgentMemory[]
   userLayouts                  UserLayout[]
   knowledgeEntries             KnowledgeEntry[]
   knowledgeTags                KnowledgeTag[]
@@ -304,6 +314,7 @@ model Workspace {
   llmUsageLogs                 LlmUsageLog[]
   userCredentials              UserCredential[]
   terminalSessions             TerminalSession[]
+  conversationArchives         ConversationArchive[]
 
   @@index([ownerId])
   @@map("workspaces")
@@ -368,6 +379,7 @@ model Task {
   creatorId   String       @map("creator_id") @db.Uuid
   projectId   String?      @map("project_id") @db.Uuid
   parentId    String?      @map("parent_id") @db.Uuid
+  assignedAgent String?    @map("assigned_agent")
   domainId    String?      @map("domain_id") @db.Uuid
   sortOrder   Int          @default(0) @map("sort_order")
   metadata    Json         @default("{}")
@@ -681,6 +693,7 @@ model AgentTask {
   createdBy   User        @relation("AgentTaskCreator", fields: [createdById], references: [id], onDelete: Cascade)
   createdById String      @map("created_by_id") @db.Uuid
   runnerJobs  RunnerJob[]
+  findings    Finding[]
 
   @@unique([id, workspaceId])
   @@index([workspaceId])
@@ -690,6 +703,33 @@ model AgentTask {
   @@map("agent_tasks")
 }
 
+model Finding {
+  id          String  @id @default(uuid()) @db.Uuid
+  workspaceId String  @map("workspace_id") @db.Uuid
+  taskId      String? @map("task_id") @db.Uuid
+
+  agentId String @map("agent_id")
+  type    String
+  title   String
+  data    Json
+  summary String @db.Text
+  // Note: vector dimension (1536) must match EMBEDDING_DIMENSION constant in @mosaic/shared
+  embedding Unsupported("vector(1536)")?
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  workspace Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+  task      AgentTask? @relation(fields: [taskId], references: [id], onDelete: SetNull)
+
+  @@unique([id, workspaceId])
+  @@index([workspaceId])
+  @@index([agentId])
+  @@index([type])
+  @@index([taskId])
+  @@map("findings")
+}
+
 model AgentSession {
   id          String  @id @default(uuid()) @db.Uuid
   workspaceId String  @map("workspace_id") @db.Uuid
@@ -727,6 +767,23 @@ model AgentSession {
   @@map("agent_sessions")
 }
 
+model AgentMemory {
+  id          String   @id @default(uuid()) @db.Uuid
+  workspaceId String   @map("workspace_id") @db.Uuid
+  agentId     String   @map("agent_id")
+  key         String
+  value       Json
+  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  workspace Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+
+  @@unique([workspaceId, agentId, key])
+  @@index([workspaceId])
+  @@index([agentId])
+  @@map("agent_memories")
+}
+
 model WidgetDefinition {
   id String @id @default(uuid()) @db.Uuid
 
@@ -1538,3 +1595,33 @@ model TerminalSession {
   @@index([workspaceId, status])
   @@map("terminal_sessions")
 }
+
+// ============================================
+// CONVERSATION ARCHIVE MODULE
+// ============================================
+
+model ConversationArchive {
+  id           String                       @id @default(uuid()) @db.Uuid
+  workspaceId  String                       @map("workspace_id") @db.Uuid
+  sessionId    String                       @map("session_id")
+  agentId      String                       @map("agent_id")
+  messages     Json
+  messageCount Int                          @map("message_count")
+  summary      String                       @db.Text
+  // Note: vector dimension (1536) must match EMBEDDING_DIMENSION constant in @mosaic/shared
+  embedding    Unsupported("vector(1536)")?
+  startedAt    DateTime                     @map("started_at") @db.Timestamptz
+  endedAt      DateTime?                    @map("ended_at") @db.Timestamptz
+  metadata     Json                         @default("{}")
+  createdAt    DateTime                     @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt    DateTime                     @updatedAt @map("updated_at") @db.Timestamptz
+
+  // Relations
+  workspace Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+
+  @@unique([workspaceId, sessionId])
+  @@index([workspaceId])
+  @@index([agentId])
+  @@index([startedAt])
+  @@map("conversation_archives")
+}

apps/api/src/admin/admin.controller.spec.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { AdminController } from "./admin.controller";
+import { AdminService } from "./admin.service";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { AdminGuard } from "../auth/guards/admin.guard";
+import { WorkspaceMemberRole } from "@prisma/client";
+import type { ExecutionContext } from "@nestjs/common";
+
+describe("AdminController", () => {
+  let controller: AdminController;
+  let service: AdminService;
+
+  const mockAdminService = {
+    listUsers: vi.fn(),
+    inviteUser: vi.fn(),
+    updateUser: vi.fn(),
+    deactivateUser: vi.fn(),
+    createWorkspace: vi.fn(),
+    updateWorkspace: vi.fn(),
+  };
+
+  const mockAuthGuard = {
+    canActivate: vi.fn((context: ExecutionContext) => {
+      const request = context.switchToHttp().getRequest();
+      request.user = {
+        id: "550e8400-e29b-41d4-a716-446655440001",
+        email: "admin@example.com",
+        name: "Admin User",
+      };
+      return true;
+    }),
+  };
+
+  const mockAdminGuard = {
+    canActivate: vi.fn(() => true),
+  };
+
+  const mockAdminId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockUserId = "550e8400-e29b-41d4-a716-446655440002";
+  const mockWorkspaceId = "550e8400-e29b-41d4-a716-446655440003";
+
+  const mockAdminUser = {
+    id: mockAdminId,
+    email: "admin@example.com",
+    name: "Admin User",
+  };
+
+  const mockUserResponse = {
+    id: mockUserId,
+    name: "Test User",
+    email: "test@example.com",
+    emailVerified: false,
+    image: null,
+    createdAt: new Date("2026-01-01"),
+    deactivatedAt: null,
+    isLocalAuth: false,
+    invitedAt: null,
+    invitedBy: null,
+    workspaceMemberships: [],
+  };
+
+  const mockWorkspaceResponse = {
+    id: mockWorkspaceId,
+    name: "Test Workspace",
+    ownerId: mockAdminId,
+    settings: {},
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-01-01"),
+    memberCount: 1,
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [AdminController],
+      providers: [
+        {
+          provide: AdminService,
+          useValue: mockAdminService,
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(mockAuthGuard)
+      .overrideGuard(AdminGuard)
+      .useValue(mockAdminGuard)
+      .compile();
+
+    controller = module.get<AdminController>(AdminController);
+    service = module.get<AdminService>(AdminService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(controller).toBeDefined();
+  });
+
+  describe("listUsers", () => {
+    it("should return paginated users", async () => {
+      const paginatedResult = {
+        data: [mockUserResponse],
+        meta: { total: 1, page: 1, limit: 50, totalPages: 1 },
+      };
+      mockAdminService.listUsers.mockResolvedValue(paginatedResult);
+
+      const result = await controller.listUsers({ page: 1, limit: 50 });
+
+      expect(result).toEqual(paginatedResult);
+      expect(service.listUsers).toHaveBeenCalledWith(1, 50);
+    });
+
+    it("should use default pagination", async () => {
+      const paginatedResult = {
+        data: [],
+        meta: { total: 0, page: 1, limit: 50, totalPages: 0 },
+      };
+      mockAdminService.listUsers.mockResolvedValue(paginatedResult);
+
+      await controller.listUsers({});
+
+      expect(service.listUsers).toHaveBeenCalledWith(undefined, undefined);
+    });
+  });
+
+  describe("inviteUser", () => {
+    it("should invite a user", async () => {
+      const inviteDto = { email: "new@example.com" };
+      const invitationResponse = {
+        userId: "new-id",
+        invitationToken: "token",
+        email: "new@example.com",
+        invitedAt: new Date(),
+      };
+      mockAdminService.inviteUser.mockResolvedValue(invitationResponse);
+
+      const result = await controller.inviteUser(inviteDto, mockAdminUser);
+
+      expect(result).toEqual(invitationResponse);
+      expect(service.inviteUser).toHaveBeenCalledWith(inviteDto, mockAdminId);
+    });
+
+    it("should invite a user with workspace and role", async () => {
+      const inviteDto = {
+        email: "new@example.com",
+        workspaceId: mockWorkspaceId,
+        role: WorkspaceMemberRole.ADMIN,
+      };
+      mockAdminService.inviteUser.mockResolvedValue({
+        userId: "new-id",
+        invitationToken: "token",
+        email: "new@example.com",
+        invitedAt: new Date(),
+      });
+
+      await controller.inviteUser(inviteDto, mockAdminUser);
+
+      expect(service.inviteUser).toHaveBeenCalledWith(inviteDto, mockAdminId);
+    });
+  });
+
+  describe("updateUser", () => {
+    it("should update a user", async () => {
+      const updateDto = { name: "Updated Name" };
+      mockAdminService.updateUser.mockResolvedValue({
+        ...mockUserResponse,
+        name: "Updated Name",
+      });
+
+      const result = await controller.updateUser(mockUserId, updateDto);
+
+      expect(result.name).toBe("Updated Name");
+      expect(service.updateUser).toHaveBeenCalledWith(mockUserId, updateDto);
+    });
+
+    it("should deactivate a user via update", async () => {
+      const deactivatedAt = "2026-02-28T00:00:00.000Z";
+      const updateDto = { deactivatedAt };
+      mockAdminService.updateUser.mockResolvedValue({
+        ...mockUserResponse,
+        deactivatedAt: new Date(deactivatedAt),
+      });
+
+      const result = await controller.updateUser(mockUserId, updateDto);
+
+      expect(result.deactivatedAt).toEqual(new Date(deactivatedAt));
+    });
+  });
+
+  describe("deactivateUser", () => {
+    it("should soft-delete a user", async () => {
+      mockAdminService.deactivateUser.mockResolvedValue({
+        ...mockUserResponse,
+        deactivatedAt: new Date(),
+      });
+
+      const result = await controller.deactivateUser(mockUserId);
+
+      expect(result.deactivatedAt).toBeDefined();
+      expect(service.deactivateUser).toHaveBeenCalledWith(mockUserId);
+    });
+  });
+
+  describe("createWorkspace", () => {
+    it("should create a workspace", async () => {
+      const createDto = { name: "New Workspace", ownerId: mockAdminId };
+      mockAdminService.createWorkspace.mockResolvedValue(mockWorkspaceResponse);
+
+      const result = await controller.createWorkspace(createDto);
+
+      expect(result).toEqual(mockWorkspaceResponse);
+      expect(service.createWorkspace).toHaveBeenCalledWith(createDto);
+    });
+
+    it("should create workspace with settings", async () => {
+      const createDto = {
+        name: "New Workspace",
+        ownerId: mockAdminId,
+        settings: { feature: true },
+      };
+      mockAdminService.createWorkspace.mockResolvedValue({
+        ...mockWorkspaceResponse,
+        settings: { feature: true },
+      });
+
+      const result = await controller.createWorkspace(createDto);
+
+      expect(result.settings).toEqual({ feature: true });
+    });
+  });
+
+  describe("updateWorkspace", () => {
+    it("should update a workspace", async () => {
+      const updateDto = { name: "Updated Workspace" };
+      mockAdminService.updateWorkspace.mockResolvedValue({
+        ...mockWorkspaceResponse,
+        name: "Updated Workspace",
+      });
+
+      const result = await controller.updateWorkspace(mockWorkspaceId, updateDto);
+
+      expect(result.name).toBe("Updated Workspace");
+      expect(service.updateWorkspace).toHaveBeenCalledWith(mockWorkspaceId, updateDto);
+    });
+
+    it("should update workspace settings", async () => {
+      const updateDto = { settings: { notifications: false } };
+      mockAdminService.updateWorkspace.mockResolvedValue({
+        ...mockWorkspaceResponse,
+        settings: { notifications: false },
+      });
+
+      const result = await controller.updateWorkspace(mockWorkspaceId, updateDto);
+
+      expect(result.settings).toEqual({ notifications: false });
+    });
+  });
+});

apps/api/src/admin/admin.controller.ts

@@ -0,0 +1,64 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  Delete,
+  Body,
+  Param,
+  Query,
+  UseGuards,
+  ParseUUIDPipe,
+} from "@nestjs/common";
+import { AdminService } from "./admin.service";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { AdminGuard } from "../auth/guards/admin.guard";
+import { CurrentUser } from "../auth/decorators/current-user.decorator";
+import type { AuthUser } from "@mosaic/shared";
+import { InviteUserDto } from "./dto/invite-user.dto";
+import { UpdateUserDto } from "./dto/update-user.dto";
+import { CreateWorkspaceDto } from "./dto/create-workspace.dto";
+import { UpdateWorkspaceDto } from "./dto/update-workspace.dto";
+import { QueryUsersDto } from "./dto/query-users.dto";
+
+@Controller("admin")
+@UseGuards(AuthGuard, AdminGuard)
+export class AdminController {
+  constructor(private readonly adminService: AdminService) {}
+
+  @Get("users")
+  async listUsers(@Query() query: QueryUsersDto) {
+    return this.adminService.listUsers(query.page, query.limit);
+  }
+
+  @Post("users/invite")
+  async inviteUser(@Body() dto: InviteUserDto, @CurrentUser() user: AuthUser) {
+    return this.adminService.inviteUser(dto, user.id);
+  }
+
+  @Patch("users/:id")
+  async updateUser(
+    @Param("id", new ParseUUIDPipe({ version: "4" })) id: string,
+    @Body() dto: UpdateUserDto
+  ) {
+    return this.adminService.updateUser(id, dto);
+  }
+
+  @Delete("users/:id")
+  async deactivateUser(@Param("id", new ParseUUIDPipe({ version: "4" })) id: string) {
+    return this.adminService.deactivateUser(id);
+  }
+
+  @Post("workspaces")
+  async createWorkspace(@Body() dto: CreateWorkspaceDto) {
+    return this.adminService.createWorkspace(dto);
+  }
+
+  @Patch("workspaces/:id")
+  async updateWorkspace(
+    @Param("id", new ParseUUIDPipe({ version: "4" })) id: string,
+    @Body() dto: UpdateWorkspaceDto
+  ) {
+    return this.adminService.updateWorkspace(id, dto);
+  }
+}

apps/api/src/admin/admin.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { AdminController } from "./admin.controller";
+import { AdminService } from "./admin.service";
+import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
+
+@Module({
+  imports: [PrismaModule, AuthModule],
+  controllers: [AdminController],
+  providers: [AdminService],
+  exports: [AdminService],
+})
+export class AdminModule {}

apps/api/src/admin/admin.service.spec.ts

@@ -0,0 +1,477 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { AdminService } from "./admin.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { BadRequestException, ConflictException, NotFoundException } from "@nestjs/common";
+import { WorkspaceMemberRole } from "@prisma/client";
+
+describe("AdminService", () => {
+  let service: AdminService;
+
+  const mockPrismaService = {
+    user: {
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      count: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+    },
+    workspace: {
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+    },
+    workspaceMember: {
+      create: vi.fn(),
+    },
+    session: {
+      deleteMany: vi.fn(),
+    },
+    $transaction: vi.fn(async (ops) => {
+      if (typeof ops === "function") {
+        return ops(mockPrismaService);
+      }
+      return Promise.all(ops);
+    }),
+  };
+
+  const mockAdminId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockUserId = "550e8400-e29b-41d4-a716-446655440002";
+  const mockWorkspaceId = "550e8400-e29b-41d4-a716-446655440003";
+
+  const mockUser = {
+    id: mockUserId,
+    name: "Test User",
+    email: "test@example.com",
+    emailVerified: false,
+    image: null,
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-01-01"),
+    deactivatedAt: null,
+    isLocalAuth: false,
+    passwordHash: null,
+    invitedBy: null,
+    invitationToken: null,
+    invitedAt: null,
+    authProviderId: null,
+    preferences: {},
+    workspaceMemberships: [
+      {
+        workspaceId: mockWorkspaceId,
+        userId: mockUserId,
+        role: WorkspaceMemberRole.MEMBER,
+        joinedAt: new Date("2026-01-01"),
+        workspace: { id: mockWorkspaceId, name: "Test Workspace" },
+      },
+    ],
+  };
+
+  const mockWorkspace = {
+    id: mockWorkspaceId,
+    name: "Test Workspace",
+    ownerId: mockAdminId,
+    settings: {},
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-01-01"),
+    matrixRoomId: null,
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        AdminService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<AdminService>(AdminService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(service).toBeDefined();
+  });
+
+  describe("listUsers", () => {
+    it("should return paginated users with memberships", async () => {
+      mockPrismaService.user.findMany.mockResolvedValue([mockUser]);
+      mockPrismaService.user.count.mockResolvedValue(1);
+
+      const result = await service.listUsers(1, 50);
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0]?.id).toBe(mockUserId);
+      expect(result.data[0]?.workspaceMemberships).toHaveLength(1);
+      expect(result.meta).toEqual({
+        total: 1,
+        page: 1,
+        limit: 50,
+        totalPages: 1,
+      });
+    });
+
+    it("should use default pagination when not provided", async () => {
+      mockPrismaService.user.findMany.mockResolvedValue([]);
+      mockPrismaService.user.count.mockResolvedValue(0);
+
+      await service.listUsers();
+
+      expect(mockPrismaService.user.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({
+          skip: 0,
+          take: 50,
+        })
+      );
+    });
+
+    it("should calculate pagination correctly", async () => {
+      mockPrismaService.user.findMany.mockResolvedValue([]);
+      mockPrismaService.user.count.mockResolvedValue(150);
+
+      const result = await service.listUsers(3, 25);
+
+      expect(mockPrismaService.user.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({
+          skip: 50,
+          take: 25,
+        })
+      );
+      expect(result.meta.totalPages).toBe(6);
+    });
+  });
+
+  describe("inviteUser", () => {
+    it("should create a user with invitation token", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+      const createdUser = {
+        id: "new-user-id",
+        email: "new@example.com",
+        name: "new",
+        invitationToken: "some-token",
+      };
+      mockPrismaService.user.create.mockResolvedValue(createdUser);
+
+      const result = await service.inviteUser({ email: "new@example.com" }, mockAdminId);
+
+      expect(result.email).toBe("new@example.com");
+      expect(result.invitationToken).toBeDefined();
+      expect(result.userId).toBe("new-user-id");
+      expect(mockPrismaService.user.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            email: "new@example.com",
+            invitedBy: mockAdminId,
+            invitationToken: expect.any(String),
+          }),
+        })
+      );
+    });
+
+    it("should add user to workspace when workspaceId provided", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+      mockPrismaService.workspace.findUnique.mockResolvedValue(mockWorkspace);
+      const createdUser = { id: "new-user-id", email: "new@example.com", name: "new" };
+      mockPrismaService.user.create.mockResolvedValue(createdUser);
+
+      await service.inviteUser(
+        {
+          email: "new@example.com",
+          workspaceId: mockWorkspaceId,
+          role: WorkspaceMemberRole.ADMIN,
+        },
+        mockAdminId
+      );
+
+      expect(mockPrismaService.workspaceMember.create).toHaveBeenCalledWith({
+        data: {
+          workspaceId: mockWorkspaceId,
+          userId: "new-user-id",
+          role: WorkspaceMemberRole.ADMIN,
+        },
+      });
+    });
+
+    it("should throw ConflictException if email already exists", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+
+      await expect(service.inviteUser({ email: "test@example.com" }, mockAdminId)).rejects.toThrow(
+        ConflictException
+      );
+    });
+
+    it("should throw NotFoundException if workspace does not exist", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+      mockPrismaService.workspace.findUnique.mockResolvedValue(null);
+
+      await expect(
+        service.inviteUser({ email: "new@example.com", workspaceId: "non-existent" }, mockAdminId)
+      ).rejects.toThrow(NotFoundException);
+    });
+
+    it("should use email prefix as default name", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+      const createdUser = { id: "new-user-id", email: "jane.doe@example.com", name: "jane.doe" };
+      mockPrismaService.user.create.mockResolvedValue(createdUser);
+
+      await service.inviteUser({ email: "jane.doe@example.com" }, mockAdminId);
+
+      expect(mockPrismaService.user.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            name: "jane.doe",
+          }),
+        })
+      );
+    });
+
+    it("should use provided name when given", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+      const createdUser = { id: "new-user-id", email: "j@example.com", name: "Jane Doe" };
+      mockPrismaService.user.create.mockResolvedValue(createdUser);
+
+      await service.inviteUser({ email: "j@example.com", name: "Jane Doe" }, mockAdminId);
+
+      expect(mockPrismaService.user.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            name: "Jane Doe",
+          }),
+        })
+      );
+    });
+  });
+
+  describe("updateUser", () => {
+    it("should update user fields", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.user.update.mockResolvedValue({
+        ...mockUser,
+        name: "Updated Name",
+      });
+
+      const result = await service.updateUser(mockUserId, { name: "Updated Name" });
+
+      expect(result.name).toBe("Updated Name");
+      expect(mockPrismaService.user.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { id: mockUserId },
+          data: { name: "Updated Name" },
+        })
+      );
+    });
+
+    it("should set deactivatedAt when provided", async () => {
+      const deactivatedAt = "2026-02-28T00:00:00.000Z";
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.user.update.mockResolvedValue({
+        ...mockUser,
+        deactivatedAt: new Date(deactivatedAt),
+      });
+
+      const result = await service.updateUser(mockUserId, { deactivatedAt });
+
+      expect(result.deactivatedAt).toEqual(new Date(deactivatedAt));
+    });
+
+    it("should clear deactivatedAt when set to null", async () => {
+      const deactivatedUser = { ...mockUser, deactivatedAt: new Date() };
+      mockPrismaService.user.findUnique.mockResolvedValue(deactivatedUser);
+      mockPrismaService.user.update.mockResolvedValue({
+        ...deactivatedUser,
+        deactivatedAt: null,
+      });
+
+      const result = await service.updateUser(mockUserId, { deactivatedAt: null });
+
+      expect(result.deactivatedAt).toBeNull();
+    });
+
+    it("should throw NotFoundException if user does not exist", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+
+      await expect(service.updateUser("non-existent", { name: "Test" })).rejects.toThrow(
+        NotFoundException
+      );
+    });
+
+    it("should update emailVerified", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.user.update.mockResolvedValue({
+        ...mockUser,
+        emailVerified: true,
+      });
+
+      const result = await service.updateUser(mockUserId, { emailVerified: true });
+
+      expect(result.emailVerified).toBe(true);
+    });
+
+    it("should update preferences", async () => {
+      const prefs = { theme: "dark" };
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.user.update.mockResolvedValue({
+        ...mockUser,
+        preferences: prefs,
+      });
+
+      await service.updateUser(mockUserId, { preferences: prefs });
+
+      expect(mockPrismaService.user.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ preferences: prefs }),
+        })
+      );
+    });
+  });
+
+  describe("deactivateUser", () => {
+    it("should set deactivatedAt and invalidate sessions", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.user.update.mockResolvedValue({
+        ...mockUser,
+        deactivatedAt: new Date(),
+      });
+      mockPrismaService.session.deleteMany.mockResolvedValue({ count: 3 });
+
+      const result = await service.deactivateUser(mockUserId);
+
+      expect(result.deactivatedAt).toBeDefined();
+      expect(mockPrismaService.user.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { id: mockUserId },
+          data: { deactivatedAt: expect.any(Date) },
+        })
+      );
+      expect(mockPrismaService.session.deleteMany).toHaveBeenCalledWith({ where: { userId: mockUserId } });
+    });
+
+    it("should throw NotFoundException if user does not exist", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+
+      await expect(service.deactivateUser("non-existent")).rejects.toThrow(NotFoundException);
+    });
+
+    it("should throw BadRequestException if user is already deactivated", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue({
+        ...mockUser,
+        deactivatedAt: new Date(),
+      });
+
+      await expect(service.deactivateUser(mockUserId)).rejects.toThrow(BadRequestException);
+    });
+  });
+
+  describe("createWorkspace", () => {
+    it("should create a workspace with owner membership", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.workspace.create.mockResolvedValue(mockWorkspace);
+
+      const result = await service.createWorkspace({
+        name: "New Workspace",
+        ownerId: mockAdminId,
+      });
+
+      expect(result.name).toBe("Test Workspace");
+      expect(result.memberCount).toBe(1);
+      expect(mockPrismaService.workspace.create).toHaveBeenCalled();
+      expect(mockPrismaService.workspaceMember.create).toHaveBeenCalledWith({
+        data: {
+          workspaceId: mockWorkspace.id,
+          userId: mockAdminId,
+          role: WorkspaceMemberRole.OWNER,
+        },
+      });
+    });
+
+    it("should throw NotFoundException if owner does not exist", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+
+      await expect(
+        service.createWorkspace({ name: "New Workspace", ownerId: "non-existent" })
+      ).rejects.toThrow(NotFoundException);
+    });
+
+    it("should pass settings when provided", async () => {
+      const settings = { theme: "dark", features: ["chat"] };
+      mockPrismaService.user.findUnique.mockResolvedValue(mockUser);
+      mockPrismaService.workspace.create.mockResolvedValue({
+        ...mockWorkspace,
+        settings,
+      });
+
+      await service.createWorkspace({
+        name: "New Workspace",
+        ownerId: mockAdminId,
+        settings,
+      });
+
+      expect(mockPrismaService.workspace.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ settings }),
+        })
+      );
+    });
+  });
+
+  describe("updateWorkspace", () => {
+    it("should update workspace name", async () => {
+      mockPrismaService.workspace.findUnique.mockResolvedValue(mockWorkspace);
+      mockPrismaService.workspace.update.mockResolvedValue({
+        ...mockWorkspace,
+        name: "Updated Workspace",
+        _count: { members: 3 },
+      });
+
+      const result = await service.updateWorkspace(mockWorkspaceId, {
+        name: "Updated Workspace",
+      });
+
+      expect(result.name).toBe("Updated Workspace");
+      expect(result.memberCount).toBe(3);
+    });
+
+    it("should update workspace settings", async () => {
+      const newSettings = { notifications: true };
+      mockPrismaService.workspace.findUnique.mockResolvedValue(mockWorkspace);
+      mockPrismaService.workspace.update.mockResolvedValue({
+        ...mockWorkspace,
+        settings: newSettings,
+        _count: { members: 1 },
+      });
+
+      const result = await service.updateWorkspace(mockWorkspaceId, {
+        settings: newSettings,
+      });
+
+      expect(result.settings).toEqual(newSettings);
+    });
+
+    it("should throw NotFoundException if workspace does not exist", async () => {
+      mockPrismaService.workspace.findUnique.mockResolvedValue(null);
+
+      await expect(service.updateWorkspace("non-existent", { name: "Test" })).rejects.toThrow(
+        NotFoundException
+      );
+    });
+
+    it("should only update provided fields", async () => {
+      mockPrismaService.workspace.findUnique.mockResolvedValue(mockWorkspace);
+      mockPrismaService.workspace.update.mockResolvedValue({
+        ...mockWorkspace,
+        _count: { members: 1 },
+      });
+
+      await service.updateWorkspace(mockWorkspaceId, { name: "Only Name" });
+
+      expect(mockPrismaService.workspace.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: { name: "Only Name" },
+        })
+      );
+    });
+  });
+});

apps/api/src/admin/admin.service.ts

@@ -0,0 +1,309 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import { Prisma, WorkspaceMemberRole } from "@prisma/client";
+import { randomUUID } from "node:crypto";
+import { PrismaService } from "../prisma/prisma.service";
+import type { InviteUserDto } from "./dto/invite-user.dto";
+import type { UpdateUserDto } from "./dto/update-user.dto";
+import type { CreateWorkspaceDto } from "./dto/create-workspace.dto";
+import type {
+  AdminUserResponse,
+  AdminWorkspaceResponse,
+  InvitationResponse,
+  PaginatedResponse,
+} from "./types/admin.types";
+
+@Injectable()
+export class AdminService {
+  private readonly logger = new Logger(AdminService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  async listUsers(page = 1, limit = 50): Promise<PaginatedResponse<AdminUserResponse>> {
+    const skip = (page - 1) * limit;
+
+    const [users, total] = await Promise.all([
+      this.prisma.user.findMany({
+        include: {
+          workspaceMemberships: {
+            include: {
+              workspace: { select: { id: true, name: true } },
+            },
+          },
+        },
+        orderBy: { createdAt: "desc" },
+        skip,
+        take: limit,
+      }),
+      this.prisma.user.count(),
+    ]);
+
+    return {
+      data: users.map((user) => ({
+        id: user.id,
+        name: user.name,
+        email: user.email,
+        emailVerified: user.emailVerified,
+        image: user.image,
+        createdAt: user.createdAt,
+        deactivatedAt: user.deactivatedAt,
+        isLocalAuth: user.isLocalAuth,
+        invitedAt: user.invitedAt,
+        invitedBy: user.invitedBy,
+        workspaceMemberships: user.workspaceMemberships.map((m) => ({
+          workspaceId: m.workspaceId,
+          workspaceName: m.workspace.name,
+          role: m.role,
+          joinedAt: m.joinedAt,
+        })),
+      })),
+      meta: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  async inviteUser(dto: InviteUserDto, inviterId: string): Promise<InvitationResponse> {
+    const existing = await this.prisma.user.findUnique({
+      where: { email: dto.email },
+    });
+
+    if (existing) {
+      throw new ConflictException(`User with email ${dto.email} already exists`);
+    }
+
+    if (dto.workspaceId) {
+      const workspace = await this.prisma.workspace.findUnique({
+        where: { id: dto.workspaceId },
+      });
+      if (!workspace) {
+        throw new NotFoundException(`Workspace ${dto.workspaceId} not found`);
+      }
+    }
+
+    const invitationToken = randomUUID();
+    const now = new Date();
+
+    const user = await this.prisma.$transaction(async (tx) => {
+      const created = await tx.user.create({
+        data: {
+          email: dto.email,
+          name: dto.name ?? dto.email.split("@")[0] ?? dto.email,
+          emailVerified: false,
+          invitedBy: inviterId,
+          invitationToken,
+          invitedAt: now,
+        },
+      });
+
+      if (dto.workspaceId) {
+        await tx.workspaceMember.create({
+          data: {
+            workspaceId: dto.workspaceId,
+            userId: created.id,
+            role: dto.role ?? WorkspaceMemberRole.MEMBER,
+          },
+        });
+      }
+
+      return created;
+    });
+
+    this.logger.log(`User invited: ${user.email} by ${inviterId}`);
+
+    return {
+      userId: user.id,
+      invitationToken,
+      email: user.email,
+      invitedAt: now,
+    };
+  }
+
+  async updateUser(id: string, dto: UpdateUserDto): Promise<AdminUserResponse> {
+    const existing = await this.prisma.user.findUnique({ where: { id } });
+    if (!existing) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+
+    const data: Prisma.UserUpdateInput = {};
+
+    if (dto.name !== undefined) {
+      data.name = dto.name;
+    }
+    if (dto.emailVerified !== undefined) {
+      data.emailVerified = dto.emailVerified;
+    }
+    if (dto.preferences !== undefined) {
+      data.preferences = dto.preferences as Prisma.InputJsonValue;
+    }
+    if (dto.deactivatedAt !== undefined) {
+      data.deactivatedAt = dto.deactivatedAt ? new Date(dto.deactivatedAt) : null;
+    }
+
+    const user = await this.prisma.user.update({
+      where: { id },
+      data,
+      include: {
+        workspaceMemberships: {
+          include: {
+            workspace: { select: { id: true, name: true } },
+          },
+        },
+      },
+    });
+
+    this.logger.log(`User updated: ${id}`);
+
+    return {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      emailVerified: user.emailVerified,
+      image: user.image,
+      createdAt: user.createdAt,
+      deactivatedAt: user.deactivatedAt,
+      isLocalAuth: user.isLocalAuth,
+      invitedAt: user.invitedAt,
+      invitedBy: user.invitedBy,
+      workspaceMemberships: user.workspaceMemberships.map((m) => ({
+        workspaceId: m.workspaceId,
+        workspaceName: m.workspace.name,
+        role: m.role,
+        joinedAt: m.joinedAt,
+      })),
+    };
+  }
+
+  async deactivateUser(id: string): Promise<AdminUserResponse> {
+    const existing = await this.prisma.user.findUnique({ where: { id } });
+    if (!existing) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+
+    if (existing.deactivatedAt) {
+      throw new BadRequestException(`User ${id} is already deactivated`);
+    }
+
+    const [user] = await this.prisma.$transaction([
+      this.prisma.user.update({
+        where: { id },
+        data: { deactivatedAt: new Date() },
+        include: {
+          workspaceMemberships: {
+            include: {
+              workspace: { select: { id: true, name: true } },
+            },
+          },
+        },
+      }),
+      this.prisma.session.deleteMany({ where: { userId: id } }),
+    ]);
+
+    this.logger.log(`User deactivated and sessions invalidated: ${id}`);
+
+    return {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      emailVerified: user.emailVerified,
+      image: user.image,
+      createdAt: user.createdAt,
+      deactivatedAt: user.deactivatedAt,
+      isLocalAuth: user.isLocalAuth,
+      invitedAt: user.invitedAt,
+      invitedBy: user.invitedBy,
+      workspaceMemberships: user.workspaceMemberships.map((m) => ({
+        workspaceId: m.workspaceId,
+        workspaceName: m.workspace.name,
+        role: m.role,
+        joinedAt: m.joinedAt,
+      })),
+    };
+  }
+
+  async createWorkspace(dto: CreateWorkspaceDto): Promise<AdminWorkspaceResponse> {
+    const owner = await this.prisma.user.findUnique({ where: { id: dto.ownerId } });
+    if (!owner) {
+      throw new NotFoundException(`User ${dto.ownerId} not found`);
+    }
+
+    const workspace = await this.prisma.$transaction(async (tx) => {
+      const created = await tx.workspace.create({
+        data: {
+          name: dto.name,
+          ownerId: dto.ownerId,
+          settings: dto.settings ? (dto.settings as Prisma.InputJsonValue) : {},
+        },
+      });
+
+      await tx.workspaceMember.create({
+        data: {
+          workspaceId: created.id,
+          userId: dto.ownerId,
+          role: WorkspaceMemberRole.OWNER,
+        },
+      });
+
+      return created;
+    });
+
+    this.logger.log(`Workspace created: ${workspace.id} with owner ${dto.ownerId}`);
+
+    return {
+      id: workspace.id,
+      name: workspace.name,
+      ownerId: workspace.ownerId,
+      settings: workspace.settings as Record<string, unknown>,
+      createdAt: workspace.createdAt,
+      updatedAt: workspace.updatedAt,
+      memberCount: 1,
+    };
+  }
+
+  async updateWorkspace(
+    id: string,
+    dto: { name?: string; settings?: Record<string, unknown> }
+  ): Promise<AdminWorkspaceResponse> {
+    const existing = await this.prisma.workspace.findUnique({ where: { id } });
+    if (!existing) {
+      throw new NotFoundException(`Workspace ${id} not found`);
+    }
+
+    const data: Prisma.WorkspaceUpdateInput = {};
+
+    if (dto.name !== undefined) {
+      data.name = dto.name;
+    }
+    if (dto.settings !== undefined) {
+      data.settings = dto.settings as Prisma.InputJsonValue;
+    }
+
+    const workspace = await this.prisma.workspace.update({
+      where: { id },
+      data,
+      include: {
+        _count: { select: { members: true } },
+      },
+    });
+
+    this.logger.log(`Workspace updated: ${id}`);
+
+    return {
+      id: workspace.id,
+      name: workspace.name,
+      ownerId: workspace.ownerId,
+      settings: workspace.settings as Record<string, unknown>,
+      createdAt: workspace.createdAt,
+      updatedAt: workspace.updatedAt,
+      memberCount: workspace._count.members,
+    };
+  }
+}

apps/api/src/admin/dto/create-workspace.dto.ts

@@ -0,0 +1,15 @@
+import { IsObject, IsOptional, IsString, IsUUID, MaxLength, MinLength } from "class-validator";
+
+export class CreateWorkspaceDto {
+  @IsString({ message: "name must be a string" })
+  @MinLength(1, { message: "name must not be empty" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name!: string;
+
+  @IsUUID("4", { message: "ownerId must be a valid UUID" })
+  ownerId!: string;
+
+  @IsOptional()
+  @IsObject({ message: "settings must be an object" })
+  settings?: Record<string, unknown>;
+}

apps/api/src/admin/dto/invite-user.dto.ts

@@ -0,0 +1,20 @@
+import { WorkspaceMemberRole } from "@prisma/client";
+import { IsEmail, IsEnum, IsOptional, IsString, IsUUID, MaxLength } from "class-validator";
+
+export class InviteUserDto {
+  @IsEmail({}, { message: "email must be a valid email address" })
+  email!: string;
+
+  @IsOptional()
+  @IsString({ message: "name must be a string" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name?: string;
+
+  @IsOptional()
+  @IsUUID("4", { message: "workspaceId must be a valid UUID" })
+  workspaceId?: string;
+
+  @IsOptional()
+  @IsEnum(WorkspaceMemberRole, { message: "role must be a valid WorkspaceMemberRole" })
+  role?: WorkspaceMemberRole;
+}

apps/api/src/admin/dto/manage-member.dto.ts

@@ -0,0 +1,15 @@
+import { WorkspaceMemberRole } from "@prisma/client";
+import { IsEnum, IsUUID } from "class-validator";
+
+export class AddMemberDto {
+  @IsUUID("4", { message: "userId must be a valid UUID" })
+  userId!: string;
+
+  @IsEnum(WorkspaceMemberRole, { message: "role must be a valid WorkspaceMemberRole" })
+  role!: WorkspaceMemberRole;
+}
+
+export class UpdateMemberRoleDto {
+  @IsEnum(WorkspaceMemberRole, { message: "role must be a valid WorkspaceMemberRole" })
+  role!: WorkspaceMemberRole;
+}

apps/api/src/admin/dto/query-users.dto.ts

@@ -0,0 +1,17 @@
+import { IsInt, IsOptional, Max, Min } from "class-validator";
+import { Type } from "class-transformer";
+
+export class QueryUsersDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "page must be an integer" })
+  @Min(1, { message: "page must be at least 1" })
+  page?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "limit must be an integer" })
+  @Min(1, { message: "limit must be at least 1" })
+  @Max(100, { message: "limit must not exceed 100" })
+  limit?: number;
+}

apps/api/src/admin/dto/update-user.dto.ts

@@ -0,0 +1,27 @@
+import {
+  IsBoolean,
+  IsDateString,
+  IsObject,
+  IsOptional,
+  IsString,
+  MaxLength,
+} from "class-validator";
+
+export class UpdateUserDto {
+  @IsOptional()
+  @IsString({ message: "name must be a string" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name?: string;
+
+  @IsOptional()
+  @IsDateString({}, { message: "deactivatedAt must be a valid ISO 8601 date string" })
+  deactivatedAt?: string | null;
+
+  @IsOptional()
+  @IsBoolean({ message: "emailVerified must be a boolean" })
+  emailVerified?: boolean;
+
+  @IsOptional()
+  @IsObject({ message: "preferences must be an object" })
+  preferences?: Record<string, unknown>;
+}

apps/api/src/admin/dto/update-workspace.dto.ts

@@ -0,0 +1,13 @@
+import { IsObject, IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+
+export class UpdateWorkspaceDto {
+  @IsOptional()
+  @IsString({ message: "name must be a string" })
+  @MinLength(1, { message: "name must not be empty" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name?: string;
+
+  @IsOptional()
+  @IsObject({ message: "settings must be an object" })
+  settings?: Record<string, unknown>;
+}

apps/api/src/admin/types/admin.types.ts

@@ -0,0 +1,49 @@
+import type { WorkspaceMemberRole } from "@prisma/client";
+
+export interface AdminUserResponse {
+  id: string;
+  name: string;
+  email: string;
+  emailVerified: boolean;
+  image: string | null;
+  createdAt: Date;
+  deactivatedAt: Date | null;
+  isLocalAuth: boolean;
+  invitedAt: Date | null;
+  invitedBy: string | null;
+  workspaceMemberships: WorkspaceMembershipResponse[];
+}
+
+export interface WorkspaceMembershipResponse {
+  workspaceId: string;
+  workspaceName: string;
+  role: WorkspaceMemberRole;
+  joinedAt: Date;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+  };
+}
+
+export interface InvitationResponse {
+  userId: string;
+  invitationToken: string;
+  email: string;
+  invitedAt: Date;
+}
+
+export interface AdminWorkspaceResponse {
+  id: string;
+  name: string;
+  ownerId: string;
+  settings: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+  memberCount: number;
+}

apps/api/src/agent-memory/agent-memory.controller.spec.ts

@@ -0,0 +1,102 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { AgentMemoryController } from "./agent-memory.controller";
+import { AgentMemoryService } from "./agent-memory.service";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+describe("AgentMemoryController", () => {
+  let controller: AgentMemoryController;
+
+  const mockAgentMemoryService = {
+    upsert: vi.fn(),
+    findAll: vi.fn(),
+    findOne: vi.fn(),
+    remove: vi.fn(),
+  };
+
+  const mockGuard = { canActivate: vi.fn(() => true) };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [AgentMemoryController],
+      providers: [
+        {
+          provide: AgentMemoryService,
+          useValue: mockAgentMemoryService,
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(mockGuard)
+      .overrideGuard(WorkspaceGuard)
+      .useValue(mockGuard)
+      .overrideGuard(PermissionGuard)
+      .useValue(mockGuard)
+      .compile();
+
+    controller = module.get<AgentMemoryController>(AgentMemoryController);
+
+    vi.clearAllMocks();
+  });
+
+  const workspaceId = "workspace-1";
+  const agentId = "agent-1";
+  const key = "context";
+
+  describe("upsert", () => {
+    it("should upsert a memory entry", async () => {
+      const dto = { value: { foo: "bar" } };
+      const mockEntry = { id: "mem-1", workspaceId, agentId, key, value: dto.value };
+
+      mockAgentMemoryService.upsert.mockResolvedValue(mockEntry);
+
+      const result = await controller.upsert(agentId, key, dto, workspaceId);
+
+      expect(mockAgentMemoryService.upsert).toHaveBeenCalledWith(workspaceId, agentId, key, dto);
+      expect(result).toEqual(mockEntry);
+    });
+  });
+
+  describe("findAll", () => {
+    it("should list all memory entries for an agent", async () => {
+      const mockEntries = [
+        { id: "mem-1", key: "a", value: 1 },
+        { id: "mem-2", key: "b", value: 2 },
+      ];
+
+      mockAgentMemoryService.findAll.mockResolvedValue(mockEntries);
+
+      const result = await controller.findAll(agentId, workspaceId);
+
+      expect(mockAgentMemoryService.findAll).toHaveBeenCalledWith(workspaceId, agentId);
+      expect(result).toEqual(mockEntries);
+    });
+  });
+
+  describe("findOne", () => {
+    it("should get a single memory entry", async () => {
+      const mockEntry = { id: "mem-1", key, value: "v" };
+
+      mockAgentMemoryService.findOne.mockResolvedValue(mockEntry);
+
+      const result = await controller.findOne(agentId, key, workspaceId);
+
+      expect(mockAgentMemoryService.findOne).toHaveBeenCalledWith(workspaceId, agentId, key);
+      expect(result).toEqual(mockEntry);
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a memory entry", async () => {
+      const mockResponse = { message: "Memory entry deleted successfully" };
+
+      mockAgentMemoryService.remove.mockResolvedValue(mockResponse);
+
+      const result = await controller.remove(agentId, key, workspaceId);
+
+      expect(mockAgentMemoryService.remove).toHaveBeenCalledWith(workspaceId, agentId, key);
+      expect(result).toEqual(mockResponse);
+    });
+  });
+});

apps/api/src/agent-memory/agent-memory.controller.ts

@@ -0,0 +1,89 @@
+import {
+  Controller,
+  Get,
+  Put,
+  Delete,
+  Body,
+  Param,
+  UseGuards,
+  HttpCode,
+  HttpStatus,
+} from "@nestjs/common";
+import { AgentMemoryService } from "./agent-memory.service";
+import { UpsertAgentMemoryDto } from "./dto";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { Workspace, Permission, RequirePermission } from "../common/decorators";
+
+/**
+ * Controller for per-agent key/value memory endpoints.
+ * All endpoints require authentication and workspace context.
+ *
+ * Guards are applied in order:
+ * 1. AuthGuard - Verifies user authentication
+ * 2. WorkspaceGuard - Validates workspace access
+ * 3. PermissionGuard - Checks role-based permissions
+ */
+@Controller("agents/:agentId/memory")
+@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
+export class AgentMemoryController {
+  constructor(private readonly agentMemoryService: AgentMemoryService) {}
+
+  /**
+   * PUT /api/agents/:agentId/memory/:key
+   * Upsert a memory entry for an agent
+   * Requires: MEMBER role or higher
+   */
+  @Put(":key")
+  @RequirePermission(Permission.WORKSPACE_MEMBER)
+  async upsert(
+    @Param("agentId") agentId: string,
+    @Param("key") key: string,
+    @Body() dto: UpsertAgentMemoryDto,
+    @Workspace() workspaceId: string
+  ) {
+    return this.agentMemoryService.upsert(workspaceId, agentId, key, dto);
+  }
+
+  /**
+   * GET /api/agents/:agentId/memory
+   * List all memory entries for an agent
+   * Requires: Any workspace member (including GUEST)
+   */
+  @Get()
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findAll(@Param("agentId") agentId: string, @Workspace() workspaceId: string) {
+    return this.agentMemoryService.findAll(workspaceId, agentId);
+  }
+
+  /**
+   * GET /api/agents/:agentId/memory/:key
+   * Get a single memory entry by key
+   * Requires: Any workspace member (including GUEST)
+   */
+  @Get(":key")
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findOne(
+    @Param("agentId") agentId: string,
+    @Param("key") key: string,
+    @Workspace() workspaceId: string
+  ) {
+    return this.agentMemoryService.findOne(workspaceId, agentId, key);
+  }
+
+  /**
+   * DELETE /api/agents/:agentId/memory/:key
+   * Remove a memory entry
+   * Requires: MEMBER role or higher
+   */
+  @Delete(":key")
+  @HttpCode(HttpStatus.OK)
+  @RequirePermission(Permission.WORKSPACE_MEMBER)
+  async remove(
+    @Param("agentId") agentId: string,
+    @Param("key") key: string,
+    @Workspace() workspaceId: string
+  ) {
+    return this.agentMemoryService.remove(workspaceId, agentId, key);
+  }
+}

apps/api/src/agent-memory/agent-memory.integration.spec.ts

@@ -0,0 +1,198 @@
+import { beforeAll, beforeEach, describe, expect, it, afterAll } from "vitest";
+import { randomUUID as uuid } from "crypto";
+import { Test, TestingModule } from "@nestjs/testing";
+import { NotFoundException } from "@nestjs/common";
+import { PrismaClient } from "@prisma/client";
+import { AgentMemoryService } from "./agent-memory.service";
+import { PrismaService } from "../prisma/prisma.service";
+
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
+
+async function createWorkspace(
+  prisma: PrismaClient,
+  label: string
+): Promise<{ workspaceId: string; ownerId: string }> {
+  const workspace = await prisma.workspace.create({
+    data: {
+      name: `${label} ${Date.now()}`,
+      owner: {
+        create: {
+          email: `${label.toLowerCase().replace(/\s+/g, "-")}-${Date.now()}@example.com`,
+          name: `${label} Owner`,
+        },
+      },
+    },
+  });
+
+  return {
+    workspaceId: workspace.id,
+    ownerId: workspace.ownerId,
+  };
+}
+
+describeFn("AgentMemoryService Integration", () => {
+  let moduleRef: TestingModule;
+  let prisma: PrismaClient;
+  let service: AgentMemoryService;
+  let setupComplete = false;
+
+  let workspaceAId: string;
+  let workspaceAOwnerId: string;
+  let workspaceBId: string;
+  let workspaceBOwnerId: string;
+
+  beforeAll(async () => {
+    prisma = new PrismaClient();
+    await prisma.$connect();
+
+    const workspaceA = await createWorkspace(prisma, "Agent Memory Integration A");
+    workspaceAId = workspaceA.workspaceId;
+    workspaceAOwnerId = workspaceA.ownerId;
+
+    const workspaceB = await createWorkspace(prisma, "Agent Memory Integration B");
+    workspaceBId = workspaceB.workspaceId;
+    workspaceBOwnerId = workspaceB.ownerId;
+
+    moduleRef = await Test.createTestingModule({
+      providers: [
+        AgentMemoryService,
+        {
+          provide: PrismaService,
+          useValue: prisma,
+        },
+      ],
+    }).compile();
+
+    service = moduleRef.get<AgentMemoryService>(AgentMemoryService);
+    setupComplete = true;
+  });
+
+  beforeEach(async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    await prisma.agentMemory.deleteMany({
+      where: {
+        workspaceId: {
+          in: [workspaceAId, workspaceBId],
+        },
+      },
+    });
+  });
+
+  afterAll(async () => {
+    if (!prisma) {
+      return;
+    }
+
+    const workspaceIds = [workspaceAId, workspaceBId].filter(
+      (id): id is string => typeof id === "string"
+    );
+    const ownerIds = [workspaceAOwnerId, workspaceBOwnerId].filter(
+      (id): id is string => typeof id === "string"
+    );
+
+    if (workspaceIds.length > 0) {
+      await prisma.agentMemory.deleteMany({
+        where: {
+          workspaceId: {
+            in: workspaceIds,
+          },
+        },
+      });
+      await prisma.workspace.deleteMany({ where: { id: { in: workspaceIds } } });
+    }
+
+    if (ownerIds.length > 0) {
+      await prisma.user.deleteMany({ where: { id: { in: ownerIds } } });
+    }
+
+    if (moduleRef) {
+      await moduleRef.close();
+    }
+    await prisma.$disconnect();
+  });
+
+  it("upserts and lists memory entries", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const agentId = `agent-${uuid()}`;
+
+    const entry = await service.upsert(workspaceAId, agentId, "session-context", {
+      value: { intent: "create-tests", depth: "integration" },
+    });
+
+    expect(entry.workspaceId).toBe(workspaceAId);
+    expect(entry.agentId).toBe(agentId);
+    expect(entry.key).toBe("session-context");
+
+    const listed = await service.findAll(workspaceAId, agentId);
+
+    expect(listed).toHaveLength(1);
+    expect(listed[0]?.id).toBe(entry.id);
+    expect(listed[0]?.value).toMatchObject({ intent: "create-tests" });
+  });
+
+  it("updates existing key via upsert without creating duplicates", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const agentId = `agent-${uuid()}`;
+
+    const first = await service.upsert(workspaceAId, agentId, "preferences", {
+      value: { model: "fast" },
+    });
+
+    const second = await service.upsert(workspaceAId, agentId, "preferences", {
+      value: { model: "accurate" },
+    });
+
+    expect(second.id).toBe(first.id);
+    expect(second.value).toMatchObject({ model: "accurate" });
+
+    const rowCount = await prisma.agentMemory.count({
+      where: {
+        workspaceId: workspaceAId,
+        agentId,
+        key: "preferences",
+      },
+    });
+
+    expect(rowCount).toBe(1);
+  });
+
+  it("lists keys in sorted order and isolates by workspace", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const agentId = `agent-${uuid()}`;
+
+    await service.upsert(workspaceAId, agentId, "beta", { value: { v: 2 } });
+    await service.upsert(workspaceAId, agentId, "alpha", { value: { v: 1 } });
+    await service.upsert(workspaceBId, agentId, "alpha", { value: { v: 99 } });
+
+    const workspaceAEntries = await service.findAll(workspaceAId, agentId);
+    const workspaceBEntries = await service.findAll(workspaceBId, agentId);
+
+    expect(workspaceAEntries.map((row) => row.key)).toEqual(["alpha", "beta"]);
+    expect(workspaceBEntries).toHaveLength(1);
+    expect(workspaceBEntries[0]?.value).toMatchObject({ v: 99 });
+  });
+
+  it("throws NotFoundException when requesting unknown key", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    await expect(service.findOne(workspaceAId, `agent-${uuid()}`, "missing")).rejects.toThrow(
+      NotFoundException
+    );
+  });
+});

apps/api/src/agent-memory/agent-memory.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { AgentMemoryController } from "./agent-memory.controller";
+import { AgentMemoryService } from "./agent-memory.service";
+import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
+
+@Module({
+  imports: [PrismaModule, AuthModule],
+  controllers: [AgentMemoryController],
+  providers: [AgentMemoryService],
+  exports: [AgentMemoryService],
+})
+export class AgentMemoryModule {}

apps/api/src/agent-memory/agent-memory.service.spec.ts

@@ -0,0 +1,126 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { AgentMemoryService } from "./agent-memory.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { NotFoundException } from "@nestjs/common";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+describe("AgentMemoryService", () => {
+  let service: AgentMemoryService;
+
+  const mockPrismaService = {
+    agentMemory: {
+      upsert: vi.fn(),
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      delete: vi.fn(),
+    },
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        AgentMemoryService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<AgentMemoryService>(AgentMemoryService);
+
+    vi.clearAllMocks();
+  });
+
+  const workspaceId = "workspace-1";
+  const agentId = "agent-1";
+  const key = "session-context";
+
+  describe("upsert", () => {
+    it("should upsert a memory entry", async () => {
+      const dto = { value: { data: "some context" } };
+      const mockEntry = {
+        id: "mem-1",
+        workspaceId,
+        agentId,
+        key,
+        value: dto.value,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrismaService.agentMemory.upsert.mockResolvedValue(mockEntry);
+
+      const result = await service.upsert(workspaceId, agentId, key, dto);
+
+      expect(mockPrismaService.agentMemory.upsert).toHaveBeenCalledWith({
+        where: { workspaceId_agentId_key: { workspaceId, agentId, key } },
+        create: { workspaceId, agentId, key, value: dto.value },
+        update: { value: dto.value },
+      });
+      expect(result).toEqual(mockEntry);
+    });
+  });
+
+  describe("findAll", () => {
+    it("should return all memory entries for an agent", async () => {
+      const mockEntries = [
+        { id: "mem-1", key: "a", value: 1 },
+        { id: "mem-2", key: "b", value: 2 },
+      ];
+
+      mockPrismaService.agentMemory.findMany.mockResolvedValue(mockEntries);
+
+      const result = await service.findAll(workspaceId, agentId);
+
+      expect(mockPrismaService.agentMemory.findMany).toHaveBeenCalledWith({
+        where: { workspaceId, agentId },
+        orderBy: { key: "asc" },
+      });
+      expect(result).toEqual(mockEntries);
+    });
+  });
+
+  describe("findOne", () => {
+    it("should return a memory entry by key", async () => {
+      const mockEntry = { id: "mem-1", workspaceId, agentId, key, value: "ctx" };
+
+      mockPrismaService.agentMemory.findUnique.mockResolvedValue(mockEntry);
+
+      const result = await service.findOne(workspaceId, agentId, key);
+
+      expect(mockPrismaService.agentMemory.findUnique).toHaveBeenCalledWith({
+        where: { workspaceId_agentId_key: { workspaceId, agentId, key } },
+      });
+      expect(result).toEqual(mockEntry);
+    });
+
+    it("should throw NotFoundException when key not found", async () => {
+      mockPrismaService.agentMemory.findUnique.mockResolvedValue(null);
+
+      await expect(service.findOne(workspaceId, agentId, key)).rejects.toThrow(NotFoundException);
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a memory entry", async () => {
+      const mockEntry = { id: "mem-1", workspaceId, agentId, key, value: "x" };
+
+      mockPrismaService.agentMemory.findUnique.mockResolvedValue(mockEntry);
+      mockPrismaService.agentMemory.delete.mockResolvedValue(mockEntry);
+
+      const result = await service.remove(workspaceId, agentId, key);
+
+      expect(mockPrismaService.agentMemory.delete).toHaveBeenCalledWith({
+        where: { workspaceId_agentId_key: { workspaceId, agentId, key } },
+      });
+      expect(result).toEqual({ message: "Memory entry deleted successfully" });
+    });
+
+    it("should throw NotFoundException when key not found", async () => {
+      mockPrismaService.agentMemory.findUnique.mockResolvedValue(null);
+
+      await expect(service.remove(workspaceId, agentId, key)).rejects.toThrow(NotFoundException);
+    });
+  });
+});

apps/api/src/agent-memory/agent-memory.service.ts

@@ -0,0 +1,79 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import { PrismaService } from "../prisma/prisma.service";
+import { Prisma } from "@prisma/client";
+import type { UpsertAgentMemoryDto } from "./dto";
+
+@Injectable()
+export class AgentMemoryService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * Upsert a memory entry for an agent.
+   */
+  async upsert(workspaceId: string, agentId: string, key: string, dto: UpsertAgentMemoryDto) {
+    return this.prisma.agentMemory.upsert({
+      where: {
+        workspaceId_agentId_key: { workspaceId, agentId, key },
+      },
+      create: {
+        workspaceId,
+        agentId,
+        key,
+        value: dto.value as Prisma.InputJsonValue,
+      },
+      update: {
+        value: dto.value as Prisma.InputJsonValue,
+      },
+    });
+  }
+
+  /**
+   * List all memory entries for an agent in a workspace.
+   */
+  async findAll(workspaceId: string, agentId: string) {
+    return this.prisma.agentMemory.findMany({
+      where: { workspaceId, agentId },
+      orderBy: { key: "asc" },
+    });
+  }
+
+  /**
+   * Get a single memory entry by key.
+   */
+  async findOne(workspaceId: string, agentId: string, key: string) {
+    const entry = await this.prisma.agentMemory.findUnique({
+      where: {
+        workspaceId_agentId_key: { workspaceId, agentId, key },
+      },
+    });
+
+    if (!entry) {
+      throw new NotFoundException(`Memory key "${key}" not found for agent "${agentId}"`);
+    }
+
+    return entry;
+  }
+
+  /**
+   * Delete a memory entry by key.
+   */
+  async remove(workspaceId: string, agentId: string, key: string) {
+    const entry = await this.prisma.agentMemory.findUnique({
+      where: {
+        workspaceId_agentId_key: { workspaceId, agentId, key },
+      },
+    });
+
+    if (!entry) {
+      throw new NotFoundException(`Memory key "${key}" not found for agent "${agentId}"`);
+    }
+
+    await this.prisma.agentMemory.delete({
+      where: {
+        workspaceId_agentId_key: { workspaceId, agentId, key },
+      },
+    });
+
+    return { message: "Memory entry deleted successfully" };
+  }
+}

apps/api/src/agent-memory/dto/index.ts

@@ -0,0 +1 @@
+export * from "./upsert-agent-memory.dto";

apps/api/src/agent-memory/dto/upsert-agent-memory.dto.ts

@@ -0,0 +1,10 @@
+import { IsNotEmpty } from "class-validator";
+
+/**
+ * DTO for upserting an agent memory entry.
+ * The value accepts any JSON-serializable data.
+ */
+export class UpsertAgentMemoryDto {
+  @IsNotEmpty({ message: "value must not be empty" })
+  value!: unknown;
+}

apps/api/src/app.module.ts

@@ -27,6 +27,8 @@ import { LlmUsageModule } from "./llm-usage/llm-usage.module";
 import { BrainModule } from "./brain/brain.module";
 import { CronModule } from "./cron/cron.module";
 import { AgentTasksModule } from "./agent-tasks/agent-tasks.module";
+import { FindingsModule } from "./findings/findings.module";
+import { AgentMemoryModule } from "./agent-memory/agent-memory.module";
 import { ValkeyModule } from "./valkey/valkey.module";
 import { BullMqModule } from "./bullmq/bullmq.module";
 import { StitcherModule } from "./stitcher/stitcher.module";
@@ -42,6 +44,11 @@ import { SpeechModule } from "./speech/speech.module";
 import { DashboardModule } from "./dashboard/dashboard.module";
 import { TerminalModule } from "./terminal/terminal.module";
 import { PersonalitiesModule } from "./personalities/personalities.module";
+import { WorkspacesModule } from "./workspaces/workspaces.module";
+import { AdminModule } from "./admin/admin.module";
+import { TeamsModule } from "./teams/teams.module";
+import { ImportModule } from "./import/import.module";
+import { ConversationArchiveModule } from "./conversation-archive/conversation-archive.module";
 import { RlsContextInterceptor } from "./common/interceptors/rls-context.interceptor";
 
 @Module({
@@ -96,6 +103,8 @@ import { RlsContextInterceptor } from "./common/interceptors/rls-context.interce
     BrainModule,
     CronModule,
     AgentTasksModule,
+    FindingsModule,
+    AgentMemoryModule,
     RunnerJobsModule,
     JobEventsModule,
     JobStepsModule,
@@ -107,6 +116,11 @@ import { RlsContextInterceptor } from "./common/interceptors/rls-context.interce
     DashboardModule,
     TerminalModule,
     PersonalitiesModule,
+    WorkspacesModule,
+    AdminModule,
+    TeamsModule,
+    ImportModule,
+    ConversationArchiveModule,
   ],
   controllers: [AppController, CsrfController],
   providers: [

apps/api/src/auth/auth.controller.spec.ts

@@ -361,16 +361,13 @@ describe("AuthController", () => {
   });
 
   describe("getProfile", () => {
-    it("should return complete user profile with workspace fields", () => {
+    it("should return complete user profile with identity fields", () => {
       const mockUser: AuthUser = {
         id: "user-123",
         email: "test@example.com",
         name: "Test User",
         image: "https://example.com/avatar.jpg",
         emailVerified: true,
-        workspaceId: "workspace-123",
-        currentWorkspaceId: "workspace-456",
-        workspaceRole: "admin",
       };
 
       const result = controller.getProfile(mockUser);
@@ -381,13 +378,10 @@ describe("AuthController", () => {
         name: mockUser.name,
         image: mockUser.image,
         emailVerified: mockUser.emailVerified,
-        workspaceId: mockUser.workspaceId,
-        currentWorkspaceId: mockUser.currentWorkspaceId,
-        workspaceRole: mockUser.workspaceRole,
       });
     });
 
-    it("should return user profile with optional fields undefined", () => {
+    it("should return user profile with only required fields", () => {
       const mockUser: AuthUser = {
         id: "user-123",
         email: "test@example.com",
@@ -400,12 +394,11 @@ describe("AuthController", () => {
         id: mockUser.id,
         email: mockUser.email,
         name: mockUser.name,
-        image: undefined,
-        emailVerified: undefined,
-        workspaceId: undefined,
-        currentWorkspaceId: undefined,
-        workspaceRole: undefined,
       });
+      // Workspace fields are not included — served by GET /api/workspaces
+      expect(result).not.toHaveProperty("workspaceId");
+      expect(result).not.toHaveProperty("currentWorkspaceId");
+      expect(result).not.toHaveProperty("workspaceRole");
     });
   });
 

apps/api/src/auth/auth.controller.ts

@@ -72,15 +72,10 @@ export class AuthController {
     if (user.emailVerified !== undefined) {
       profile.emailVerified = user.emailVerified;
     }
-    if (user.workspaceId !== undefined) {
-      profile.workspaceId = user.workspaceId;
-    }
-    if (user.currentWorkspaceId !== undefined) {
-      profile.currentWorkspaceId = user.currentWorkspaceId;
-    }
-    if (user.workspaceRole !== undefined) {
-      profile.workspaceRole = user.workspaceRole;
-    }
+
+    // Workspace context is served by GET /api/workspaces, not the auth profile.
+    // The deprecated workspaceId/currentWorkspaceId/workspaceRole fields on
+    // AuthUser are never populated by BetterAuth and are omitted here.
 
     return profile;
   }

apps/api/src/auth/auth.module.ts

@@ -3,11 +3,14 @@ import { PrismaModule } from "../prisma/prisma.module";
 import { AuthService } from "./auth.service";
 import { AuthController } from "./auth.controller";
 import { AuthGuard } from "./guards/auth.guard";
+import { LocalAuthController } from "./local/local-auth.controller";
+import { LocalAuthService } from "./local/local-auth.service";
+import { LocalAuthEnabledGuard } from "./local/local-auth.guard";
 
 @Module({
   imports: [PrismaModule],
-  controllers: [AuthController],
-  providers: [AuthService, AuthGuard],
+  controllers: [AuthController, LocalAuthController],
+  providers: [AuthService, AuthGuard, LocalAuthService, LocalAuthEnabledGuard],
   exports: [AuthService, AuthGuard],
 })
 export class AuthModule {}

apps/api/src/auth/local/dto/local-login.dto.ts

@@ -0,0 +1,10 @@
+import { IsEmail, IsString, MinLength } from "class-validator";
+
+export class LocalLoginDto {
+  @IsEmail({}, { message: "email must be a valid email address" })
+  email!: string;
+
+  @IsString({ message: "password must be a string" })
+  @MinLength(1, { message: "password must not be empty" })
+  password!: string;
+}

apps/api/src/auth/local/dto/local-setup.dto.ts

@@ -0,0 +1,20 @@
+import { IsEmail, IsString, MinLength, MaxLength } from "class-validator";
+
+export class LocalSetupDto {
+  @IsEmail({}, { message: "email must be a valid email address" })
+  email!: string;
+
+  @IsString({ message: "name must be a string" })
+  @MinLength(1, { message: "name must not be empty" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name!: string;
+
+  @IsString({ message: "password must be a string" })
+  @MinLength(12, { message: "password must be at least 12 characters" })
+  @MaxLength(128, { message: "password must not exceed 128 characters" })
+  password!: string;
+
+  @IsString({ message: "setupToken must be a string" })
+  @MinLength(1, { message: "setupToken must not be empty" })
+  setupToken!: string;
+}

apps/api/src/auth/local/local-auth.controller.spec.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import {
+  NotFoundException,
+  ForbiddenException,
+  UnauthorizedException,
+  ConflictException,
+} from "@nestjs/common";
+import { LocalAuthController } from "./local-auth.controller";
+import { LocalAuthService } from "./local-auth.service";
+import { LocalAuthEnabledGuard } from "./local-auth.guard";
+
+describe("LocalAuthController", () => {
+  let controller: LocalAuthController;
+  let localAuthService: LocalAuthService;
+
+  const mockLocalAuthService = {
+    setup: vi.fn(),
+    login: vi.fn(),
+  };
+
+  const mockRequest = {
+    headers: { "user-agent": "TestAgent/1.0" },
+    ip: "127.0.0.1",
+    socket: { remoteAddress: "127.0.0.1" },
+  };
+
+  const originalEnv = {
+    ENABLE_LOCAL_AUTH: process.env.ENABLE_LOCAL_AUTH,
+  };
+
+  beforeEach(async () => {
+    process.env.ENABLE_LOCAL_AUTH = "true";
+
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [LocalAuthController],
+      providers: [
+        {
+          provide: LocalAuthService,
+          useValue: mockLocalAuthService,
+        },
+      ],
+    })
+      .overrideGuard(LocalAuthEnabledGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    controller = module.get<LocalAuthController>(LocalAuthController);
+    localAuthService = module.get<LocalAuthService>(LocalAuthService);
+
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalEnv.ENABLE_LOCAL_AUTH !== undefined) {
+      process.env.ENABLE_LOCAL_AUTH = originalEnv.ENABLE_LOCAL_AUTH;
+    } else {
+      delete process.env.ENABLE_LOCAL_AUTH;
+    }
+  });
+
+  describe("setup", () => {
+    const setupDto = {
+      email: "admin@example.com",
+      name: "Break Glass Admin",
+      password: "securePassword123!",
+      setupToken: "valid-token-123",
+    };
+
+    const mockSetupResult = {
+      user: {
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "Break Glass Admin",
+        isLocalAuth: true,
+        createdAt: new Date("2026-02-28T00:00:00Z"),
+      },
+      session: {
+        token: "session-token-abc",
+        expiresAt: new Date("2026-03-07T00:00:00Z"),
+      },
+    };
+
+    it("should create a break-glass user and return user data with session", async () => {
+      mockLocalAuthService.setup.mockResolvedValue(mockSetupResult);
+
+      const result = await controller.setup(setupDto, mockRequest as never);
+
+      expect(result).toEqual({
+        user: mockSetupResult.user,
+        session: mockSetupResult.session,
+      });
+      expect(mockLocalAuthService.setup).toHaveBeenCalledWith(
+        "admin@example.com",
+        "Break Glass Admin",
+        "securePassword123!",
+        "valid-token-123",
+        "127.0.0.1",
+        "TestAgent/1.0"
+      );
+    });
+
+    it("should extract client IP from x-forwarded-for header", async () => {
+      mockLocalAuthService.setup.mockResolvedValue(mockSetupResult);
+      const reqWithProxy = {
+        ...mockRequest,
+        headers: {
+          ...mockRequest.headers,
+          "x-forwarded-for": "203.0.113.50, 70.41.3.18",
+        },
+      };
+
+      await controller.setup(setupDto, reqWithProxy as never);
+
+      expect(mockLocalAuthService.setup).toHaveBeenCalledWith(
+        expect.any(String) as string,
+        expect.any(String) as string,
+        expect.any(String) as string,
+        expect.any(String) as string,
+        "203.0.113.50",
+        "TestAgent/1.0"
+      );
+    });
+
+    it("should propagate ForbiddenException from service", async () => {
+      mockLocalAuthService.setup.mockRejectedValue(new ForbiddenException("Invalid setup token"));
+
+      await expect(controller.setup(setupDto, mockRequest as never)).rejects.toThrow(
+        ForbiddenException
+      );
+    });
+
+    it("should propagate ConflictException from service", async () => {
+      mockLocalAuthService.setup.mockRejectedValue(
+        new ConflictException("A user with this email already exists")
+      );
+
+      await expect(controller.setup(setupDto, mockRequest as never)).rejects.toThrow(
+        ConflictException
+      );
+    });
+  });
+
+  describe("login", () => {
+    const loginDto = {
+      email: "admin@example.com",
+      password: "securePassword123!",
+    };
+
+    const mockLoginResult = {
+      user: {
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "Break Glass Admin",
+      },
+      session: {
+        token: "session-token-abc",
+        expiresAt: new Date("2026-03-07T00:00:00Z"),
+      },
+    };
+
+    it("should authenticate and return user data with session", async () => {
+      mockLocalAuthService.login.mockResolvedValue(mockLoginResult);
+
+      const result = await controller.login(loginDto, mockRequest as never);
+
+      expect(result).toEqual({
+        user: mockLoginResult.user,
+        session: mockLoginResult.session,
+      });
+      expect(mockLocalAuthService.login).toHaveBeenCalledWith(
+        "admin@example.com",
+        "securePassword123!",
+        "127.0.0.1",
+        "TestAgent/1.0"
+      );
+    });
+
+    it("should propagate UnauthorizedException from service", async () => {
+      mockLocalAuthService.login.mockRejectedValue(
+        new UnauthorizedException("Invalid email or password")
+      );
+
+      await expect(controller.login(loginDto, mockRequest as never)).rejects.toThrow(
+        UnauthorizedException
+      );
+    });
+  });
+});
+
+describe("LocalAuthEnabledGuard", () => {
+  let guard: LocalAuthEnabledGuard;
+
+  const originalEnv = process.env.ENABLE_LOCAL_AUTH;
+
+  beforeEach(() => {
+    guard = new LocalAuthEnabledGuard();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.ENABLE_LOCAL_AUTH = originalEnv;
+    } else {
+      delete process.env.ENABLE_LOCAL_AUTH;
+    }
+  });
+
+  it("should allow access when ENABLE_LOCAL_AUTH is true", () => {
+    process.env.ENABLE_LOCAL_AUTH = "true";
+
+    expect(guard.canActivate()).toBe(true);
+  });
+
+  it("should throw NotFoundException when ENABLE_LOCAL_AUTH is not set", () => {
+    delete process.env.ENABLE_LOCAL_AUTH;
+
+    expect(() => guard.canActivate()).toThrow(NotFoundException);
+  });
+
+  it("should throw NotFoundException when ENABLE_LOCAL_AUTH is false", () => {
+    process.env.ENABLE_LOCAL_AUTH = "false";
+
+    expect(() => guard.canActivate()).toThrow(NotFoundException);
+  });
+
+  it("should throw NotFoundException when ENABLE_LOCAL_AUTH is empty", () => {
+    process.env.ENABLE_LOCAL_AUTH = "";
+
+    expect(() => guard.canActivate()).toThrow(NotFoundException);
+  });
+});

apps/api/src/auth/local/local-auth.controller.ts

@@ -0,0 +1,81 @@
+import {
+  Controller,
+  Post,
+  Body,
+  UseGuards,
+  Req,
+  Logger,
+  HttpCode,
+  HttpStatus,
+} from "@nestjs/common";
+import { Throttle } from "@nestjs/throttler";
+import type { Request as ExpressRequest } from "express";
+import { SkipCsrf } from "../../common/decorators/skip-csrf.decorator";
+import { LocalAuthService } from "./local-auth.service";
+import { LocalAuthEnabledGuard } from "./local-auth.guard";
+import { LocalLoginDto } from "./dto/local-login.dto";
+import { LocalSetupDto } from "./dto/local-setup.dto";
+
+@Controller("auth/local")
+@UseGuards(LocalAuthEnabledGuard)
+export class LocalAuthController {
+  private readonly logger = new Logger(LocalAuthController.name);
+
+  constructor(private readonly localAuthService: LocalAuthService) {}
+
+  /**
+   * First-time break-glass user creation.
+   * Requires BREAKGLASS_SETUP_TOKEN from environment.
+   */
+  @Post("setup")
+  @SkipCsrf()
+  @Throttle({ strict: { limit: 5, ttl: 60000 } })
+  async setup(@Body() dto: LocalSetupDto, @Req() req: ExpressRequest) {
+    const ipAddress = this.getClientIp(req);
+    const userAgent = req.headers["user-agent"];
+
+    this.logger.log(`Break-glass setup attempt from ${ipAddress}`);
+
+    const result = await this.localAuthService.setup(
+      dto.email,
+      dto.name,
+      dto.password,
+      dto.setupToken,
+      ipAddress,
+      userAgent
+    );
+
+    return {
+      user: result.user,
+      session: result.session,
+    };
+  }
+
+  /**
+   * Break-glass login with email + password.
+   */
+  @Post("login")
+  @SkipCsrf()
+  @HttpCode(HttpStatus.OK)
+  @Throttle({ strict: { limit: 10, ttl: 60000 } })
+  async login(@Body() dto: LocalLoginDto, @Req() req: ExpressRequest) {
+    const ipAddress = this.getClientIp(req);
+    const userAgent = req.headers["user-agent"];
+
+    const result = await this.localAuthService.login(dto.email, dto.password, ipAddress, userAgent);
+
+    return {
+      user: result.user,
+      session: result.session,
+    };
+  }
+
+  private getClientIp(req: ExpressRequest): string {
+    const forwardedFor = req.headers["x-forwarded-for"];
+    if (forwardedFor) {
+      const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor;
+      return ips?.split(",")[0]?.trim() ?? "unknown";
+    }
+    return req.ip ?? req.socket.remoteAddress ?? "unknown";
+  }
+}

apps/api/src/auth/local/local-auth.guard.ts

@@ -0,0 +1,15 @@
+import { Injectable, CanActivate, NotFoundException } from "@nestjs/common";
+
+/**
+ * Guard that checks if local authentication is enabled via ENABLE_LOCAL_AUTH env var.
+ * Returns 404 when disabled so endpoints are invisible to callers.
+ */
+@Injectable()
+export class LocalAuthEnabledGuard implements CanActivate {
+  canActivate(): boolean {
+    if (process.env.ENABLE_LOCAL_AUTH !== "true") {
+      throw new NotFoundException();
+    }
+    return true;
+  }
+}

apps/api/src/auth/local/local-auth.service.spec.ts

@@ -0,0 +1,389 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import {
+  ConflictException,
+  ForbiddenException,
+  InternalServerErrorException,
+  UnauthorizedException,
+} from "@nestjs/common";
+import { hash } from "bcryptjs";
+import { LocalAuthService } from "./local-auth.service";
+import { PrismaService } from "../../prisma/prisma.service";
+
+describe("LocalAuthService", () => {
+  let service: LocalAuthService;
+
+  const mockTxSession = {
+    create: vi.fn(),
+  };
+
+  const mockTxWorkspace = {
+    findFirst: vi.fn(),
+    create: vi.fn(),
+  };
+
+  const mockTxWorkspaceMember = {
+    create: vi.fn(),
+  };
+
+  const mockTxUser = {
+    create: vi.fn(),
+    findUnique: vi.fn(),
+  };
+
+  const mockTx = {
+    user: mockTxUser,
+    workspace: mockTxWorkspace,
+    workspaceMember: mockTxWorkspaceMember,
+    session: mockTxSession,
+  };
+
+  const mockPrismaService = {
+    user: {
+      findUnique: vi.fn(),
+    },
+    session: {
+      create: vi.fn(),
+    },
+    $transaction: vi
+      .fn()
+      .mockImplementation((fn: (tx: typeof mockTx) => Promise<unknown>) => fn(mockTx)),
+  };
+
+  const originalEnv = {
+    BREAKGLASS_SETUP_TOKEN: process.env.BREAKGLASS_SETUP_TOKEN,
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        LocalAuthService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<LocalAuthService>(LocalAuthService);
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalEnv.BREAKGLASS_SETUP_TOKEN !== undefined) {
+      process.env.BREAKGLASS_SETUP_TOKEN = originalEnv.BREAKGLASS_SETUP_TOKEN;
+    } else {
+      delete process.env.BREAKGLASS_SETUP_TOKEN;
+    }
+  });
+
+  describe("setup", () => {
+    const validSetupArgs = {
+      email: "admin@example.com",
+      name: "Break Glass Admin",
+      password: "securePassword123!",
+      setupToken: "valid-token-123",
+    };
+
+    const mockCreatedUser = {
+      id: "user-uuid-123",
+      email: "admin@example.com",
+      name: "Break Glass Admin",
+      isLocalAuth: true,
+      createdAt: new Date("2026-02-28T00:00:00Z"),
+    };
+
+    const mockWorkspace = {
+      id: "workspace-uuid-123",
+    };
+
+    beforeEach(() => {
+      process.env.BREAKGLASS_SETUP_TOKEN = "valid-token-123";
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+      mockTxUser.create.mockResolvedValue(mockCreatedUser);
+      mockTxWorkspace.findFirst.mockResolvedValue(mockWorkspace);
+      mockTxWorkspaceMember.create.mockResolvedValue({});
+      mockTxSession.create.mockResolvedValue({});
+    });
+
+    it("should create a local auth user with hashed password", async () => {
+      const result = await service.setup(
+        validSetupArgs.email,
+        validSetupArgs.name,
+        validSetupArgs.password,
+        validSetupArgs.setupToken
+      );
+
+      expect(result.user).toEqual(mockCreatedUser);
+      expect(result.session.token).toBeDefined();
+      expect(result.session.token.length).toBeGreaterThan(0);
+      expect(result.session.expiresAt).toBeInstanceOf(Date);
+      expect(result.session.expiresAt.getTime()).toBeGreaterThan(Date.now());
+
+      expect(mockTxUser.create).toHaveBeenCalledWith({
+        data: expect.objectContaining({
+          email: "admin@example.com",
+          name: "Break Glass Admin",
+          isLocalAuth: true,
+          emailVerified: true,
+          passwordHash: expect.any(String) as string,
+        }),
+        select: {
+          id: true,
+          email: true,
+          name: true,
+          isLocalAuth: true,
+          createdAt: true,
+        },
+      });
+    });
+
+    it("should assign OWNER role on default workspace", async () => {
+      await service.setup(
+        validSetupArgs.email,
+        validSetupArgs.name,
+        validSetupArgs.password,
+        validSetupArgs.setupToken
+      );
+
+      expect(mockTxWorkspaceMember.create).toHaveBeenCalledWith({
+        data: {
+          workspaceId: "workspace-uuid-123",
+          userId: "user-uuid-123",
+          role: "OWNER",
+        },
+      });
+    });
+
+    it("should create a new workspace if none exists", async () => {
+      mockTxWorkspace.findFirst.mockResolvedValue(null);
+      mockTxWorkspace.create.mockResolvedValue({ id: "new-workspace-uuid" });
+
+      await service.setup(
+        validSetupArgs.email,
+        validSetupArgs.name,
+        validSetupArgs.password,
+        validSetupArgs.setupToken
+      );
+
+      expect(mockTxWorkspace.create).toHaveBeenCalledWith({
+        data: {
+          name: "Default Workspace",
+          ownerId: "user-uuid-123",
+          settings: {},
+        },
+        select: { id: true },
+      });
+      expect(mockTxWorkspaceMember.create).toHaveBeenCalledWith({
+        data: {
+          workspaceId: "new-workspace-uuid",
+          userId: "user-uuid-123",
+          role: "OWNER",
+        },
+      });
+    });
+
+    it("should create a BetterAuth-compatible session", async () => {
+      await service.setup(
+        validSetupArgs.email,
+        validSetupArgs.name,
+        validSetupArgs.password,
+        validSetupArgs.setupToken,
+        "192.168.1.1",
+        "TestAgent/1.0"
+      );
+
+      expect(mockTxSession.create).toHaveBeenCalledWith({
+        data: {
+          userId: "user-uuid-123",
+          token: expect.any(String) as string,
+          expiresAt: expect.any(Date) as Date,
+          ipAddress: "192.168.1.1",
+          userAgent: "TestAgent/1.0",
+        },
+      });
+    });
+
+    it("should reject when BREAKGLASS_SETUP_TOKEN is not set", async () => {
+      delete process.env.BREAKGLASS_SETUP_TOKEN;
+
+      await expect(
+        service.setup(
+          validSetupArgs.email,
+          validSetupArgs.name,
+          validSetupArgs.password,
+          validSetupArgs.setupToken
+        )
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it("should reject when BREAKGLASS_SETUP_TOKEN is empty", async () => {
+      process.env.BREAKGLASS_SETUP_TOKEN = "";
+
+      await expect(
+        service.setup(
+          validSetupArgs.email,
+          validSetupArgs.name,
+          validSetupArgs.password,
+          validSetupArgs.setupToken
+        )
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it("should reject when setup token does not match", async () => {
+      await expect(
+        service.setup(
+          validSetupArgs.email,
+          validSetupArgs.name,
+          validSetupArgs.password,
+          "wrong-token"
+        )
+      ).rejects.toThrow(ForbiddenException);
+    });
+
+    it("should reject when email already exists", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue({
+        id: "existing-user",
+        email: "admin@example.com",
+      });
+
+      await expect(
+        service.setup(
+          validSetupArgs.email,
+          validSetupArgs.name,
+          validSetupArgs.password,
+          validSetupArgs.setupToken
+        )
+      ).rejects.toThrow(ConflictException);
+    });
+
+    it("should return session token and expiry", async () => {
+      const result = await service.setup(
+        validSetupArgs.email,
+        validSetupArgs.name,
+        validSetupArgs.password,
+        validSetupArgs.setupToken
+      );
+
+      expect(typeof result.session.token).toBe("string");
+      expect(result.session.token.length).toBe(64); // 32 bytes hex
+      expect(result.session.expiresAt).toBeInstanceOf(Date);
+    });
+  });
+
+  describe("login", () => {
+    const validPasswordHash = "$2a$12$LJ3m4ys3Lz/YgP7xYz5k5uU6b5F6X1234567890abcdefghijkl";
+
+    beforeEach(async () => {
+      // Create a real bcrypt hash for testing
+      const realHash = await hash("securePassword123!", 4); // Low rounds for test speed
+      mockPrismaService.user.findUnique.mockResolvedValue({
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "Break Glass Admin",
+        isLocalAuth: true,
+        passwordHash: realHash,
+        deactivatedAt: null,
+      });
+      mockPrismaService.session.create.mockResolvedValue({});
+    });
+
+    it("should authenticate a valid local auth user", async () => {
+      const result = await service.login("admin@example.com", "securePassword123!");
+
+      expect(result.user).toEqual({
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "Break Glass Admin",
+      });
+      expect(result.session.token).toBeDefined();
+      expect(result.session.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("should create a session with ip and user agent", async () => {
+      await service.login("admin@example.com", "securePassword123!", "10.0.0.1", "Mozilla/5.0");
+
+      expect(mockPrismaService.session.create).toHaveBeenCalledWith({
+        data: {
+          userId: "user-uuid-123",
+          token: expect.any(String) as string,
+          expiresAt: expect.any(Date) as Date,
+          ipAddress: "10.0.0.1",
+          userAgent: "Mozilla/5.0",
+        },
+      });
+    });
+
+    it("should reject when user does not exist", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+
+      await expect(service.login("nonexistent@example.com", "password123456")).rejects.toThrow(
+        UnauthorizedException
+      );
+    });
+
+    it("should reject when user is not a local auth user", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue({
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "OIDC User",
+        isLocalAuth: false,
+        passwordHash: null,
+        deactivatedAt: null,
+      });
+
+      await expect(service.login("admin@example.com", "password123456")).rejects.toThrow(
+        UnauthorizedException
+      );
+    });
+
+    it("should reject when user is deactivated", async () => {
+      const realHash = await hash("securePassword123!", 4);
+      mockPrismaService.user.findUnique.mockResolvedValue({
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "Deactivated User",
+        isLocalAuth: true,
+        passwordHash: realHash,
+        deactivatedAt: new Date("2026-01-01"),
+      });
+
+      await expect(service.login("admin@example.com", "securePassword123!")).rejects.toThrow(
+        new UnauthorizedException("Account has been deactivated")
+      );
+    });
+
+    it("should reject when password is incorrect", async () => {
+      await expect(service.login("admin@example.com", "wrongPassword123!")).rejects.toThrow(
+        UnauthorizedException
+      );
+    });
+
+    it("should throw InternalServerError when local auth user has no password hash", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue({
+        id: "user-uuid-123",
+        email: "admin@example.com",
+        name: "Broken User",
+        isLocalAuth: true,
+        passwordHash: null,
+        deactivatedAt: null,
+      });
+
+      await expect(service.login("admin@example.com", "securePassword123!")).rejects.toThrow(
+        InternalServerErrorException
+      );
+    });
+
+    it("should not reveal whether email exists in error messages", async () => {
+      mockPrismaService.user.findUnique.mockResolvedValue(null);
+
+      try {
+        await service.login("nonexistent@example.com", "password123456");
+      } catch (error) {
+        expect(error).toBeInstanceOf(UnauthorizedException);
+        expect((error as UnauthorizedException).message).toBe("Invalid email or password");
+      }
+    });
+  });
+});

apps/api/src/auth/local/local-auth.service.ts

@@ -0,0 +1,230 @@
+import {
+  Injectable,
+  Logger,
+  ForbiddenException,
+  UnauthorizedException,
+  ConflictException,
+  InternalServerErrorException,
+} from "@nestjs/common";
+import { WorkspaceMemberRole } from "@prisma/client";
+import { hash, compare } from "bcryptjs";
+import { randomBytes, timingSafeEqual } from "crypto";
+import { PrismaService } from "../../prisma/prisma.service";
+
+const BCRYPT_ROUNDS = 12;
+
+/** Session expiry: 7 days (matches BetterAuth config in auth.config.ts) */
+const SESSION_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
+
+interface SetupResult {
+  user: {
+    id: string;
+    email: string;
+    name: string;
+    isLocalAuth: boolean;
+    createdAt: Date;
+  };
+  session: {
+    token: string;
+    expiresAt: Date;
+  };
+}
+
+interface LoginResult {
+  user: {
+    id: string;
+    email: string;
+    name: string;
+  };
+  session: {
+    token: string;
+    expiresAt: Date;
+  };
+}
+
+@Injectable()
+export class LocalAuthService {
+  private readonly logger = new Logger(LocalAuthService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * First-time break-glass user creation.
+   * Validates the setup token, creates a local auth user with bcrypt-hashed password,
+   * and assigns OWNER role on the default workspace.
+   */
+  async setup(
+    email: string,
+    name: string,
+    password: string,
+    setupToken: string,
+    ipAddress?: string,
+    userAgent?: string
+  ): Promise<SetupResult> {
+    this.validateSetupToken(setupToken);
+
+    const existing = await this.prisma.user.findUnique({ where: { email } });
+    if (existing) {
+      throw new ConflictException("A user with this email already exists");
+    }
+
+    const passwordHash = await hash(password, BCRYPT_ROUNDS);
+
+    const result = await this.prisma.$transaction(async (tx) => {
+      const user = await tx.user.create({
+        data: {
+          email,
+          name,
+          isLocalAuth: true,
+          passwordHash,
+          emailVerified: true,
+        },
+        select: {
+          id: true,
+          email: true,
+          name: true,
+          isLocalAuth: true,
+          createdAt: true,
+        },
+      });
+
+      // Find or create a default workspace and assign OWNER role
+      await this.assignDefaultWorkspace(tx, user.id);
+
+      // Create a BetterAuth-compatible session
+      const session = await this.createSession(tx, user.id, ipAddress, userAgent);
+
+      return { user, session };
+    });
+
+    this.logger.log(`Break-glass user created: ${email}`);
+    return result;
+  }
+
+  /**
+   * Break-glass login: verify email + password against bcrypt hash.
+   * Only works for users with isLocalAuth=true.
+   */
+  async login(
+    email: string,
+    password: string,
+    ipAddress?: string,
+    userAgent?: string
+  ): Promise<LoginResult> {
+    const user = await this.prisma.user.findUnique({
+      where: { email },
+      select: {
+        id: true,
+        email: true,
+        name: true,
+        isLocalAuth: true,
+        passwordHash: true,
+        deactivatedAt: true,
+      },
+    });
+
+    if (!user?.isLocalAuth) {
+      throw new UnauthorizedException("Invalid email or password");
+    }
+
+    if (user.deactivatedAt) {
+      throw new UnauthorizedException("Account has been deactivated");
+    }
+
+    if (!user.passwordHash) {
+      this.logger.error(`Local auth user ${email} has no password hash`);
+      throw new InternalServerErrorException("Account configuration error");
+    }
+
+    const passwordValid = await compare(password, user.passwordHash);
+    if (!passwordValid) {
+      throw new UnauthorizedException("Invalid email or password");
+    }
+
+    const session = await this.createSession(this.prisma, user.id, ipAddress, userAgent);
+
+    this.logger.log(`Break-glass login: ${email}`);
+    return {
+      user: { id: user.id, email: user.email, name: user.name },
+      session,
+    };
+  }
+
+  /**
+   * Validate the setup token against the environment variable.
+   */
+  private validateSetupToken(token: string): void {
+    const expectedToken = process.env.BREAKGLASS_SETUP_TOKEN;
+
+    if (!expectedToken || expectedToken.trim() === "") {
+      throw new ForbiddenException(
+        "Break-glass setup is not configured. Set BREAKGLASS_SETUP_TOKEN environment variable."
+      );
+    }
+
+    const tokenBuffer = Buffer.from(token);
+    const expectedBuffer = Buffer.from(expectedToken);
+    if (
+      tokenBuffer.length !== expectedBuffer.length ||
+      !timingSafeEqual(tokenBuffer, expectedBuffer)
+    ) {
+      this.logger.warn("Invalid break-glass setup token attempt");
+      throw new ForbiddenException("Invalid setup token");
+    }
+  }
+
+  /**
+   * Find the first workspace or create a default one, then assign OWNER role.
+   */
+  private async assignDefaultWorkspace(
+    tx: Parameters<Parameters<PrismaService["$transaction"]>[0]>[0],
+    userId: string
+  ): Promise<void> {
+    let workspace = await tx.workspace.findFirst({
+      orderBy: { createdAt: "asc" },
+      select: { id: true },
+    });
+
+    workspace ??= await tx.workspace.create({
+      data: {
+        name: "Default Workspace",
+        ownerId: userId,
+        settings: {},
+      },
+      select: { id: true },
+    });
+
+    await tx.workspaceMember.create({
+      data: {
+        workspaceId: workspace.id,
+        userId,
+        role: WorkspaceMemberRole.OWNER,
+      },
+    });
+  }
+
+  /**
+   * Create a BetterAuth-compatible session record.
+   */
+  private async createSession(
+    tx: { session: { create: typeof PrismaService.prototype.session.create } },
+    userId: string,
+    ipAddress?: string,
+    userAgent?: string
+  ): Promise<{ token: string; expiresAt: Date }> {
+    const token = randomBytes(32).toString("hex");
+    const expiresAt = new Date(Date.now() + SESSION_EXPIRY_MS);
+
+    await tx.session.create({
+      data: {
+        userId,
+        token,
+        expiresAt,
+        ipAddress: ipAddress ?? null,
+        userAgent: userAgent ?? null,
+      },
+    });
+
+    return { token, expiresAt };
+  }
+}

apps/api/src/common/utils/log-sanitizer.spec.ts

@@ -270,7 +270,7 @@ describe("sanitizeForLogging", () => {
       const duration = Date.now() - start;
 
       expect(result.password).toBe("[REDACTED]");
-      expect(duration).toBeLessThan(100); // Should complete in under 100ms
+      expect(duration).toBeLessThan(500); // Should complete in under 500ms
     });
   });
 

apps/api/src/conversation-archive/conversation-archive.controller.ts

@@ -0,0 +1,69 @@
+import { Controller, Post, Get, Body, Param, Query, UseGuards } from "@nestjs/common";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { Workspace, RequirePermission, Permission } from "../common/decorators";
+import { ConversationArchiveService } from "./conversation-archive.service";
+import { IngestConversationDto, SearchConversationDto, ListConversationsDto } from "./dto";
+
+/**
+ * Controller for conversation archive endpoints.
+ * All endpoints require workspace membership.
+ */
+@Controller("conversations")
+@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
+export class ConversationArchiveController {
+  constructor(private readonly service: ConversationArchiveService) {}
+
+  /**
+   * POST /api/conversations/ingest
+   * Ingest a conversation session log and auto-embed for semantic search.
+   * Requires: MEMBER or higher
+   */
+  @Post("ingest")
+  @RequirePermission(Permission.WORKSPACE_MEMBER)
+  async ingest(
+    @Workspace() workspaceId: string,
+    @Body() dto: IngestConversationDto
+  ): Promise<{ id: string }> {
+    return this.service.ingest(workspaceId, dto);
+  }
+
+  /**
+   * POST /api/conversations/search
+   * Vector similarity search across archived conversations.
+   * Requires: Any workspace member
+   */
+  @Post("search")
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async search(
+    @Workspace() workspaceId: string,
+    @Body() dto: SearchConversationDto
+  ): Promise<unknown> {
+    return this.service.search(workspaceId, dto);
+  }
+
+  /**
+   * GET /api/conversations
+   * List conversation archives with filtering and pagination.
+   * Requires: Any workspace member
+   */
+  @Get()
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findAll(
+    @Workspace() workspaceId: string,
+    @Query() query: ListConversationsDto
+  ): Promise<unknown> {
+    return this.service.findAll(workspaceId, query);
+  }
+
+  /**
+   * GET /api/conversations/:id
+   * Get a single conversation archive by ID (includes full messages).
+   * Requires: Any workspace member
+   */
+  @Get(":id")
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findOne(@Workspace() workspaceId: string, @Param("id") id: string): Promise<unknown> {
+    return this.service.findOne(workspaceId, id);
+  }
+}

apps/api/src/conversation-archive/conversation-archive.integration.spec.ts

@@ -0,0 +1,239 @@
+import { beforeAll, beforeEach, describe, expect, it, afterAll, vi } from "vitest";
+import { randomUUID as uuid } from "crypto";
+import { Test, TestingModule } from "@nestjs/testing";
+import { ConflictException } from "@nestjs/common";
+import { PrismaClient, Prisma } from "@prisma/client";
+import { EMBEDDING_DIMENSION } from "@mosaic/shared";
+import { ConversationArchiveService } from "./conversation-archive.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { EmbeddingService } from "../knowledge/services/embedding.service";
+
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
+
+function vector(value: number): number[] {
+  return Array.from({ length: EMBEDDING_DIMENSION }, () => value);
+}
+
+function toVectorLiteral(input: number[]): string {
+  return `[${input.join(",")}]`;
+}
+
+describeFn("ConversationArchiveService Integration", () => {
+  let moduleRef: TestingModule;
+  let prisma: PrismaClient;
+  let service: ConversationArchiveService;
+  let workspaceId: string;
+  let ownerId: string;
+  let setupComplete = false;
+
+  const embeddingServiceMock = {
+    isConfigured: vi.fn(),
+    generateEmbedding: vi.fn(),
+  };
+
+  beforeAll(async () => {
+    prisma = new PrismaClient();
+    await prisma.$connect();
+
+    const workspace = await prisma.workspace.create({
+      data: {
+        name: `Conversation Archive Integration ${Date.now()}`,
+        owner: {
+          create: {
+            email: `conversation-archive-integration-${Date.now()}@example.com`,
+            name: "Conversation Archive Integration Owner",
+          },
+        },
+      },
+    });
+
+    workspaceId = workspace.id;
+    ownerId = workspace.ownerId;
+
+    moduleRef = await Test.createTestingModule({
+      providers: [
+        ConversationArchiveService,
+        {
+          provide: PrismaService,
+          useValue: prisma,
+        },
+        {
+          provide: EmbeddingService,
+          useValue: embeddingServiceMock,
+        },
+      ],
+    }).compile();
+
+    service = moduleRef.get<ConversationArchiveService>(ConversationArchiveService);
+    setupComplete = true;
+  });
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    embeddingServiceMock.isConfigured.mockReturnValue(false);
+
+    if (!setupComplete) {
+      return;
+    }
+
+    await prisma.conversationArchive.deleteMany({ where: { workspaceId } });
+  });
+
+  afterAll(async () => {
+    if (!prisma) {
+      return;
+    }
+
+    if (workspaceId) {
+      await prisma.conversationArchive.deleteMany({ where: { workspaceId } });
+      await prisma.workspace.deleteMany({ where: { id: workspaceId } });
+    }
+    if (ownerId) {
+      await prisma.user.deleteMany({ where: { id: ownerId } });
+    }
+
+    if (moduleRef) {
+      await moduleRef.close();
+    }
+    await prisma.$disconnect();
+  });
+
+  it("ingests a conversation log", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const sessionId = `session-${uuid()}`;
+
+    const result = await service.ingest(workspaceId, {
+      sessionId,
+      agentId: "agent-conversation-ingest",
+      messages: [
+        { role: "user", content: "Can you summarize deployment issues?" },
+        { role: "assistant", content: "Yes, three retries timed out in staging." },
+      ],
+      summary: "Deployment retry failures discussed",
+      startedAt: "2026-02-28T21:00:00.000Z",
+      endedAt: "2026-02-28T21:05:00.000Z",
+      metadata: { source: "integration-test" },
+    });
+
+    expect(result.id).toBeDefined();
+
+    const stored = await prisma.conversationArchive.findUnique({
+      where: {
+        id: result.id,
+      },
+    });
+
+    expect(stored).toBeTruthy();
+    expect(stored?.workspaceId).toBe(workspaceId);
+    expect(stored?.sessionId).toBe(sessionId);
+    expect(stored?.messageCount).toBe(2);
+    expect(stored?.summary).toBe("Deployment retry failures discussed");
+  });
+
+  it("rejects duplicate session ingest per workspace", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const sessionId = `session-${uuid()}`;
+    const dto = {
+      sessionId,
+      agentId: "agent-conversation-duplicate",
+      messages: [{ role: "user", content: "hello" }],
+      summary: "simple conversation",
+      startedAt: "2026-02-28T22:00:00.000Z",
+    };
+
+    await service.ingest(workspaceId, dto);
+
+    await expect(service.ingest(workspaceId, dto)).rejects.toThrow(ConflictException);
+  });
+
+  it("rejects semantic search when embeddings are disabled", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    embeddingServiceMock.isConfigured.mockReturnValue(false);
+
+    await expect(
+      service.search(workspaceId, {
+        query: "deployment retries",
+      })
+    ).rejects.toThrow(ConflictException);
+  });
+
+  it("searches archived conversations by vector similarity", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const near = vector(0.02);
+    const far = vector(0.85);
+
+    const matching = await prisma.conversationArchive.create({
+      data: {
+        workspaceId,
+        sessionId: `session-search-${uuid()}`,
+        agentId: "agent-conversation-search-a",
+        messages: [
+          { role: "user", content: "What caused deployment retries?" },
+          { role: "assistant", content: "A connection pool timeout." },
+        ] as unknown as Prisma.InputJsonValue,
+        messageCount: 2,
+        summary: "Deployment retries caused by connection pool timeout",
+        startedAt: new Date("2026-02-28T23:00:00.000Z"),
+        metadata: { channel: "cli" } as Prisma.InputJsonValue,
+      },
+    });
+
+    const nonMatching = await prisma.conversationArchive.create({
+      data: {
+        workspaceId,
+        sessionId: `session-search-${uuid()}`,
+        agentId: "agent-conversation-search-b",
+        messages: [
+          { role: "user", content: "How is billing configured?" },
+        ] as unknown as Prisma.InputJsonValue,
+        messageCount: 1,
+        summary: "Billing and quotas conversation",
+        startedAt: new Date("2026-02-28T23:10:00.000Z"),
+        metadata: { channel: "cli" } as Prisma.InputJsonValue,
+      },
+    });
+
+    await prisma.$executeRaw`
+      UPDATE conversation_archives
+      SET embedding = ${toVectorLiteral(near)}::vector(${EMBEDDING_DIMENSION})
+      WHERE id = ${matching.id}::uuid
+    `;
+    await prisma.$executeRaw`
+      UPDATE conversation_archives
+      SET embedding = ${toVectorLiteral(far)}::vector(${EMBEDDING_DIMENSION})
+      WHERE id = ${nonMatching.id}::uuid
+    `;
+
+    embeddingServiceMock.isConfigured.mockReturnValue(true);
+    embeddingServiceMock.generateEmbedding.mockResolvedValue(near);
+
+    const result = await service.search(workspaceId, {
+      query: "deployment retries timeout",
+      agentId: "agent-conversation-search-a",
+      similarityThreshold: 0,
+      limit: 10,
+    });
+
+    const rows = result.data as Array<{ id: string; agent_id: string; similarity: number }>;
+
+    expect(result.pagination.total).toBe(1);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.id).toBe(matching.id);
+    expect(rows[0]?.agent_id).toBe("agent-conversation-search-a");
+    expect(rows[0]?.similarity).toBeGreaterThan(0);
+  });
+});

apps/api/src/conversation-archive/conversation-archive.module.ts

@@ -0,0 +1,14 @@
+import { Module } from "@nestjs/common";
+import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
+import { KnowledgeModule } from "../knowledge/knowledge.module";
+import { ConversationArchiveService } from "./conversation-archive.service";
+import { ConversationArchiveController } from "./conversation-archive.controller";
+
+@Module({
+  imports: [PrismaModule, AuthModule, KnowledgeModule],
+  controllers: [ConversationArchiveController],
+  providers: [ConversationArchiveService],
+  exports: [ConversationArchiveService],
+})
+export class ConversationArchiveModule {}

apps/api/src/conversation-archive/conversation-archive.service.spec.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { ConflictException, NotFoundException } from "@nestjs/common";
+import { ConversationArchiveService } from "./conversation-archive.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { EmbeddingService } from "../knowledge/services/embedding.service";
+
+const mockPrisma = {
+  conversationArchive: {
+    findUnique: vi.fn(),
+    create: vi.fn(),
+    count: vi.fn(),
+    findMany: vi.fn(),
+    findFirst: vi.fn(),
+  },
+  $queryRaw: vi.fn(),
+  $executeRaw: vi.fn(),
+};
+
+const mockEmbedding = {
+  isConfigured: vi.fn(),
+  generateEmbedding: vi.fn(),
+};
+
+describe("ConversationArchiveService", () => {
+  let service: ConversationArchiveService;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        ConversationArchiveService,
+        { provide: PrismaService, useValue: mockPrisma },
+        { provide: EmbeddingService, useValue: mockEmbedding },
+      ],
+    }).compile();
+
+    service = module.get<ConversationArchiveService>(ConversationArchiveService);
+  });
+
+  describe("ingest", () => {
+    const workspaceId = "ws-1";
+    const dto = {
+      sessionId: "sess-abc",
+      agentId: "agent-xyz",
+      messages: [
+        { role: "user", content: "Hello" },
+        { role: "assistant", content: "Hi there!" },
+      ],
+      summary: "A greeting conversation",
+      startedAt: "2026-02-28T10:00:00Z",
+    };
+
+    it("creates a conversation archive and returns id", async () => {
+      mockPrisma.conversationArchive.findUnique.mockResolvedValue(null);
+      mockPrisma.conversationArchive.create.mockResolvedValue({ id: "conv-1" });
+      mockEmbedding.isConfigured.mockReturnValue(false);
+
+      const result = await service.ingest(workspaceId, dto);
+
+      expect(result).toEqual({ id: "conv-1" });
+      expect(mockPrisma.conversationArchive.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            workspaceId,
+            sessionId: dto.sessionId,
+            agentId: dto.agentId,
+            messageCount: 2,
+          }),
+        })
+      );
+    });
+
+    it("throws ConflictException when session already exists", async () => {
+      mockPrisma.conversationArchive.findUnique.mockResolvedValue({ id: "existing" });
+
+      await expect(service.ingest(workspaceId, dto)).rejects.toThrow(ConflictException);
+    });
+  });
+
+  describe("findAll", () => {
+    const workspaceId = "ws-1";
+
+    it("returns paginated list", async () => {
+      mockPrisma.conversationArchive.count.mockResolvedValue(5);
+      mockPrisma.conversationArchive.findMany.mockResolvedValue([
+        { id: "conv-1", sessionId: "sess-1" },
+      ]);
+
+      const result = await service.findAll(workspaceId, { page: 1, limit: 10 });
+
+      expect(result.pagination.total).toBe(5);
+      expect(result.data).toHaveLength(1);
+    });
+
+    it("uses default pagination when not provided", async () => {
+      mockPrisma.conversationArchive.count.mockResolvedValue(0);
+      mockPrisma.conversationArchive.findMany.mockResolvedValue([]);
+
+      const result = await service.findAll(workspaceId, {});
+
+      expect(result.pagination.page).toBe(1);
+      expect(result.pagination.limit).toBe(20);
+    });
+  });
+
+  describe("findOne", () => {
+    const workspaceId = "ws-1";
+
+    it("returns record when found", async () => {
+      const record = { id: "conv-1", workspaceId, sessionId: "sess-1" };
+      mockPrisma.conversationArchive.findFirst.mockResolvedValue(record);
+
+      const result = await service.findOne(workspaceId, "conv-1");
+
+      expect(result).toEqual(record);
+    });
+
+    it("throws NotFoundException when record does not exist", async () => {
+      mockPrisma.conversationArchive.findFirst.mockResolvedValue(null);
+
+      await expect(service.findOne(workspaceId, "missing")).rejects.toThrow(NotFoundException);
+    });
+  });
+
+  describe("search", () => {
+    it("throws ConflictException when embedding is not configured", async () => {
+      mockEmbedding.isConfigured.mockReturnValue(false);
+
+      await expect(service.search("ws-1", { query: "test query" })).rejects.toThrow(
+        ConflictException
+      );
+    });
+
+    it("performs vector search when configured", async () => {
+      mockEmbedding.isConfigured.mockReturnValue(true);
+      mockEmbedding.generateEmbedding.mockResolvedValue(new Array(1536).fill(0.1));
+      mockPrisma.$queryRaw
+        .mockResolvedValueOnce([{ id: "conv-1", similarity: 0.9 }])
+        .mockResolvedValueOnce([{ count: BigInt(1) }]);
+
+      const result = await service.search("ws-1", { query: "greetings" });
+
+      expect(result.data).toHaveLength(1);
+      expect(result.pagination.total).toBe(1);
+    });
+  });
+});

apps/api/src/conversation-archive/conversation-archive.service.ts

@@ -0,0 +1,277 @@
+import { Injectable, Logger, NotFoundException, ConflictException } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { EMBEDDING_DIMENSION } from "@mosaic/shared";
+import { PrismaService } from "../prisma/prisma.service";
+import { EmbeddingService } from "../knowledge/services/embedding.service";
+import type { IngestConversationDto, SearchConversationDto, ListConversationsDto } from "./dto";
+
+/**
+ * Shape of a raw conversation archive row from $queryRaw vector search
+ */
+interface RawConversationResult {
+  id: string;
+  workspace_id: string;
+  session_id: string;
+  agent_id: string;
+  messages: unknown;
+  message_count: number;
+  summary: string;
+  started_at: Date;
+  ended_at: Date | null;
+  metadata: unknown;
+  created_at: Date;
+  updated_at: Date;
+  similarity: number;
+}
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedConversations<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+@Injectable()
+export class ConversationArchiveService {
+  private readonly logger = new Logger(ConversationArchiveService.name);
+  private readonly defaultSimilarityThreshold = 0.5;
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly embedding: EmbeddingService
+  ) {}
+
+  /**
+   * Ingest a conversation session log.
+   * Generates a vector embedding from the summary + message content and stores it alongside the record.
+   */
+  async ingest(workspaceId: string, dto: IngestConversationDto): Promise<{ id: string }> {
+    // Verify no duplicate session in this workspace
+    const existing = await this.prisma.conversationArchive.findUnique({
+      where: { workspaceId_sessionId: { workspaceId, sessionId: dto.sessionId } },
+      select: { id: true },
+    });
+
+    if (existing) {
+      throw new ConflictException(
+        `Conversation session '${dto.sessionId}' already exists in this workspace`
+      );
+    }
+
+    const messageCount = dto.messages.length;
+
+    // Create record first to get ID for embedding
+    const record = await this.prisma.conversationArchive.create({
+      data: {
+        workspaceId,
+        sessionId: dto.sessionId,
+        agentId: dto.agentId,
+        messages: dto.messages as unknown as Prisma.InputJsonValue,
+        messageCount,
+        summary: dto.summary,
+        startedAt: new Date(dto.startedAt),
+        endedAt: dto.endedAt ? new Date(dto.endedAt) : null,
+        metadata: (dto.metadata ?? {}) as Prisma.InputJsonValue,
+      },
+      select: { id: true },
+    });
+
+    // Generate and store embedding asynchronously (non-blocking for ingest)
+    if (this.embedding.isConfigured()) {
+      const textForEmbedding = this.buildEmbeddingText(dto.summary, dto.messages);
+      this.storeEmbedding(record.id, textForEmbedding).catch((err: unknown) => {
+        this.logger.error(`Failed to store embedding for conversation ${record.id}`, err);
+      });
+    }
+
+    this.logger.log(`Ingested conversation ${record.id} (session: ${dto.sessionId})`);
+    return { id: record.id };
+  }
+
+  /**
+   * Semantic vector search across conversation archives in a workspace.
+   */
+  async search(
+    workspaceId: string,
+    dto: SearchConversationDto
+  ): Promise<PaginatedConversations<RawConversationResult>> {
+    if (!this.embedding.isConfigured()) {
+      throw new ConflictException("Semantic search requires OpenAI API key to be configured");
+    }
+
+    const limit = dto.limit ?? 20;
+    const threshold = dto.similarityThreshold ?? this.defaultSimilarityThreshold;
+    const distanceThreshold = 1 - threshold;
+
+    const queryEmbedding = await this.embedding.generateEmbedding(dto.query);
+    const embeddingStr = `[${queryEmbedding.join(",")}]`;
+
+    const agentFilter = dto.agentId ? Prisma.sql`AND ca.agent_id = ${dto.agentId}` : Prisma.sql``;
+
+    const rows = await this.prisma.$queryRaw<RawConversationResult[]>`
+      SELECT
+        ca.id,
+        ca.workspace_id,
+        ca.session_id,
+        ca.agent_id,
+        ca.messages,
+        ca.message_count,
+        ca.summary,
+        ca.started_at,
+        ca.ended_at,
+        ca.metadata,
+        ca.created_at,
+        ca.updated_at,
+        (1 - (ca.embedding <=> ${embeddingStr}::vector(${EMBEDDING_DIMENSION}))) AS similarity
+      FROM conversation_archives ca
+      WHERE ca.workspace_id = ${workspaceId}::uuid
+        AND ca.embedding IS NOT NULL
+        AND (ca.embedding <=> ${embeddingStr}::vector(${EMBEDDING_DIMENSION})) <= ${distanceThreshold}
+        ${agentFilter}
+      ORDER BY ca.embedding <=> ${embeddingStr}::vector(${EMBEDDING_DIMENSION})
+      LIMIT ${limit}
+    `;
+
+    const countResult = await this.prisma.$queryRaw<[{ count: bigint }]>`
+      SELECT COUNT(*) AS count
+      FROM conversation_archives ca
+      WHERE ca.workspace_id = ${workspaceId}::uuid
+        AND ca.embedding IS NOT NULL
+        AND (ca.embedding <=> ${embeddingStr}::vector(${EMBEDDING_DIMENSION})) <= ${distanceThreshold}
+        ${agentFilter}
+    `;
+
+    const total = Number(countResult[0].count);
+
+    return {
+      data: rows,
+      pagination: {
+        page: 1,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  /**
+   * List conversation archives with filtering and pagination.
+   */
+  async findAll(
+    workspaceId: string,
+    query: ListConversationsDto
+  ): Promise<PaginatedConversations<object>> {
+    const page = query.page ?? 1;
+    const limit = query.limit ?? 20;
+    const skip = (page - 1) * limit;
+
+    const where: Prisma.ConversationArchiveWhereInput = {
+      workspaceId,
+      ...(query.agentId ? { agentId: query.agentId } : {}),
+      ...(query.startedAfter || query.startedBefore
+        ? {
+            startedAt: {
+              ...(query.startedAfter ? { gte: new Date(query.startedAfter) } : {}),
+              ...(query.startedBefore ? { lte: new Date(query.startedBefore) } : {}),
+            },
+          }
+        : {}),
+    };
+
+    const [total, records] = await Promise.all([
+      this.prisma.conversationArchive.count({ where }),
+      this.prisma.conversationArchive.findMany({
+        where,
+        select: {
+          id: true,
+          workspaceId: true,
+          sessionId: true,
+          agentId: true,
+          messageCount: true,
+          summary: true,
+          startedAt: true,
+          endedAt: true,
+          metadata: true,
+          createdAt: true,
+          updatedAt: true,
+        },
+        orderBy: { startedAt: "desc" },
+        skip,
+        take: limit,
+      }),
+    ]);
+
+    return {
+      data: records,
+      pagination: {
+        page,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  /**
+   * Get a single conversation archive by ID.
+   */
+  async findOne(workspaceId: string, id: string): Promise<object> {
+    const record = await this.prisma.conversationArchive.findFirst({
+      where: { id, workspaceId },
+      select: {
+        id: true,
+        workspaceId: true,
+        sessionId: true,
+        agentId: true,
+        messages: true,
+        messageCount: true,
+        summary: true,
+        startedAt: true,
+        endedAt: true,
+        metadata: true,
+        createdAt: true,
+        updatedAt: true,
+      },
+    });
+
+    if (!record) {
+      throw new NotFoundException(`Conversation archive '${id}' not found`);
+    }
+
+    return record;
+  }
+
+  /**
+   * Build text content for embedding from summary and messages.
+   */
+  private buildEmbeddingText(
+    summary: string,
+    messages: { role: string; content: string }[]
+  ): string {
+    const messageText = messages.map((m) => `${m.role}: ${m.content}`).join("\n");
+    return `${summary}\n\n${messageText}`.trim();
+  }
+
+  /**
+   * Generate embedding and store it on the conversation_archives row.
+   */
+  private async storeEmbedding(id: string, text: string): Promise<void> {
+    const vector = await this.embedding.generateEmbedding(text);
+    const embeddingStr = `[${vector.join(",")}]`;
+
+    await this.prisma.$executeRaw`
+      UPDATE conversation_archives
+      SET embedding = ${embeddingStr}::vector(${EMBEDDING_DIMENSION}),
+          updated_at = NOW()
+      WHERE id = ${id}::uuid
+    `;
+
+    this.logger.log(`Stored embedding for conversation ${id}`);
+  }
+}

apps/api/src/conversation-archive/dto/index.ts

@@ -0,0 +1,3 @@
+export { IngestConversationDto, ConversationMessageDto } from "./ingest-conversation.dto";
+export { SearchConversationDto } from "./search-conversation.dto";
+export { ListConversationsDto } from "./list-conversations.dto";

apps/api/src/conversation-archive/dto/ingest-conversation.dto.ts

@@ -0,0 +1,64 @@
+import {
+  IsString,
+  IsArray,
+  IsOptional,
+  IsDateString,
+  MinLength,
+  MaxLength,
+  IsObject,
+  ValidateNested,
+  ArrayMinSize,
+} from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * Represents a single message in a conversation session
+ */
+export class ConversationMessageDto {
+  @IsString()
+  role!: string;
+
+  @IsString()
+  @MinLength(1)
+  content!: string;
+
+  @IsOptional()
+  @IsDateString()
+  timestamp?: string;
+}
+
+/**
+ * DTO for ingesting a conversation session log
+ */
+export class IngestConversationDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(500)
+  sessionId!: string;
+
+  @IsString()
+  @MinLength(1)
+  @MaxLength(500)
+  agentId!: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateNested({ each: true })
+  @Type(() => ConversationMessageDto)
+  messages!: ConversationMessageDto[];
+
+  @IsString()
+  @MinLength(1)
+  summary!: string;
+
+  @IsDateString()
+  startedAt!: string;
+
+  @IsOptional()
+  @IsDateString()
+  endedAt?: string;
+
+  @IsOptional()
+  @IsObject()
+  metadata?: Record<string, unknown>;
+}

apps/api/src/conversation-archive/dto/list-conversations.dto.ts

@@ -0,0 +1,33 @@
+import { IsString, IsOptional, MaxLength, IsInt, Min, Max, IsDateString } from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * DTO for listing/filtering conversation archives
+ */
+export class ListConversationsDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  agentId?: string;
+
+  @IsOptional()
+  @IsDateString()
+  startedAfter?: string;
+
+  @IsOptional()
+  @IsDateString()
+  startedBefore?: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+}

apps/api/src/conversation-archive/dto/search-conversation.dto.ts

@@ -0,0 +1,40 @@
+import {
+  IsString,
+  IsOptional,
+  MinLength,
+  MaxLength,
+  IsInt,
+  Min,
+  Max,
+  IsNumber,
+} from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * DTO for semantic search across conversation archives
+ */
+export class SearchConversationDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(1000)
+  query!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  agentId?: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber()
+  @Min(0)
+  @Max(1)
+  similarityThreshold?: number;
+}

apps/api/src/coordinator-integration/coordinator-integration.rate-limit.spec.ts

@@ -245,7 +245,7 @@ describe("CoordinatorIntegrationController - Rate Limiting", () => {
         .set("X-API-Key", "test-coordinator-key");
 
       expect(response.status).toBe(HttpStatus.TOO_MANY_REQUESTS);
-    });
+    }, 30000);
   });
 
   describe("Per-API-Key Rate Limiting", () => {

apps/api/src/findings/dto/create-finding.dto.ts

@@ -0,0 +1,33 @@
+import { IsObject, IsOptional, IsString, IsUUID, MaxLength, MinLength } from "class-validator";
+
+/**
+ * DTO for creating a finding
+ */
+export class CreateFindingDto {
+  @IsOptional()
+  @IsUUID("4", { message: "taskId must be a valid UUID" })
+  taskId?: string;
+
+  @IsString({ message: "agentId must be a string" })
+  @MinLength(1, { message: "agentId must not be empty" })
+  @MaxLength(255, { message: "agentId must not exceed 255 characters" })
+  agentId!: string;
+
+  @IsString({ message: "type must be a string" })
+  @MinLength(1, { message: "type must not be empty" })
+  @MaxLength(100, { message: "type must not exceed 100 characters" })
+  type!: string;
+
+  @IsString({ message: "title must be a string" })
+  @MinLength(1, { message: "title must not be empty" })
+  @MaxLength(255, { message: "title must not exceed 255 characters" })
+  title!: string;
+
+  @IsObject({ message: "data must be an object" })
+  data!: Record<string, unknown>;
+
+  @IsString({ message: "summary must be a string" })
+  @MinLength(1, { message: "summary must not be empty" })
+  @MaxLength(20000, { message: "summary must not exceed 20000 characters" })
+  summary!: string;
+}

apps/api/src/findings/dto/index.ts

@@ -0,0 +1,3 @@
+export { CreateFindingDto } from "./create-finding.dto";
+export { QueryFindingsDto } from "./query-findings.dto";
+export { SearchFindingsDto } from "./search-findings.dto";

apps/api/src/findings/dto/query-findings.dto.ts

@@ -0,0 +1,32 @@
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, IsString, IsUUID, Max, Min } from "class-validator";
+
+/**
+ * DTO for querying findings with filters and pagination
+ */
+export class QueryFindingsDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "page must be an integer" })
+  @Min(1, { message: "page must be at least 1" })
+  page?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "limit must be an integer" })
+  @Min(1, { message: "limit must be at least 1" })
+  @Max(100, { message: "limit must not exceed 100" })
+  limit?: number;
+
+  @IsOptional()
+  @IsString({ message: "agentId must be a string" })
+  agentId?: string;
+
+  @IsOptional()
+  @IsString({ message: "type must be a string" })
+  type?: string;
+
+  @IsOptional()
+  @IsUUID("4", { message: "taskId must be a valid UUID" })
+  taskId?: string;
+}

apps/api/src/findings/dto/search-findings.dto.ts

@@ -0,0 +1,52 @@
+import { Type } from "class-transformer";
+import {
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Max,
+  MaxLength,
+  Min,
+} from "class-validator";
+
+/**
+ * DTO for finding semantic similarity search
+ */
+export class SearchFindingsDto {
+  @IsString({ message: "query must be a string" })
+  @MaxLength(1000, { message: "query must not exceed 1000 characters" })
+  query!: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "page must be an integer" })
+  @Min(1, { message: "page must be at least 1" })
+  page?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "limit must be an integer" })
+  @Min(1, { message: "limit must be at least 1" })
+  @Max(100, { message: "limit must not exceed 100" })
+  limit?: number;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsNumber({}, { message: "similarityThreshold must be a number" })
+  @Min(0, { message: "similarityThreshold must be at least 0" })
+  @Max(1, { message: "similarityThreshold must not exceed 1" })
+  similarityThreshold?: number;
+
+  @IsOptional()
+  @IsString({ message: "agentId must be a string" })
+  agentId?: string;
+
+  @IsOptional()
+  @IsString({ message: "type must be a string" })
+  type?: string;
+
+  @IsOptional()
+  @IsUUID("4", { message: "taskId must be a valid UUID" })
+  taskId?: string;
+}

apps/api/src/findings/findings.controller.spec.ts

@@ -0,0 +1,195 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { FindingsController } from "./findings.controller";
+import { FindingsService } from "./findings.service";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { CreateFindingDto, QueryFindingsDto, SearchFindingsDto } from "./dto";
+
+describe("FindingsController", () => {
+  let controller: FindingsController;
+  let service: FindingsService;
+
+  const mockFindingsService = {
+    create: vi.fn(),
+    findAll: vi.fn(),
+    findOne: vi.fn(),
+    search: vi.fn(),
+    remove: vi.fn(),
+  };
+
+  const mockAuthGuard = {
+    canActivate: vi.fn(() => true),
+  };
+
+  const mockWorkspaceGuard = {
+    canActivate: vi.fn(() => true),
+  };
+
+  const mockPermissionGuard = {
+    canActivate: vi.fn(() => true),
+  };
+
+  const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
+  const findingId = "550e8400-e29b-41d4-a716-446655440002";
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [FindingsController],
+      providers: [
+        {
+          provide: FindingsService,
+          useValue: mockFindingsService,
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(mockAuthGuard)
+      .overrideGuard(WorkspaceGuard)
+      .useValue(mockWorkspaceGuard)
+      .overrideGuard(PermissionGuard)
+      .useValue(mockPermissionGuard)
+      .compile();
+
+    controller = module.get<FindingsController>(FindingsController);
+    service = module.get<FindingsService>(FindingsService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(controller).toBeDefined();
+  });
+
+  describe("create", () => {
+    it("should create a finding", async () => {
+      const createDto: CreateFindingDto = {
+        agentId: "research-agent",
+        type: "security",
+        title: "SQL injection risk",
+        data: { severity: "high" },
+        summary: "Potential SQL injection in search endpoint.",
+      };
+
+      const createdFinding = {
+        id: findingId,
+        workspaceId,
+        taskId: null,
+        ...createDto,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockFindingsService.create.mockResolvedValue(createdFinding);
+
+      const result = await controller.create(createDto, workspaceId);
+
+      expect(result).toEqual(createdFinding);
+      expect(service.create).toHaveBeenCalledWith(workspaceId, createDto);
+    });
+  });
+
+  describe("findAll", () => {
+    it("should return paginated findings", async () => {
+      const query: QueryFindingsDto = {
+        page: 1,
+        limit: 10,
+        type: "security",
+      };
+
+      const response = {
+        data: [],
+        meta: {
+          total: 0,
+          page: 1,
+          limit: 10,
+          totalPages: 0,
+        },
+      };
+
+      mockFindingsService.findAll.mockResolvedValue(response);
+
+      const result = await controller.findAll(query, workspaceId);
+
+      expect(result).toEqual(response);
+      expect(service.findAll).toHaveBeenCalledWith(workspaceId, query);
+    });
+  });
+
+  describe("findOne", () => {
+    it("should return a finding", async () => {
+      const finding = {
+        id: findingId,
+        workspaceId,
+        taskId: null,
+        agentId: "research-agent",
+        type: "security",
+        title: "SQL injection risk",
+        data: { severity: "high" },
+        summary: "Potential SQL injection in search endpoint.",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockFindingsService.findOne.mockResolvedValue(finding);
+
+      const result = await controller.findOne(findingId, workspaceId);
+
+      expect(result).toEqual(finding);
+      expect(service.findOne).toHaveBeenCalledWith(findingId, workspaceId);
+    });
+  });
+
+  describe("search", () => {
+    it("should perform semantic search", async () => {
+      const searchDto: SearchFindingsDto = {
+        query: "sql injection",
+        limit: 5,
+      };
+
+      const response = {
+        data: [
+          {
+            id: findingId,
+            workspaceId,
+            taskId: null,
+            agentId: "research-agent",
+            type: "security",
+            title: "SQL injection risk",
+            data: { severity: "high" },
+            summary: "Potential SQL injection in search endpoint.",
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            score: 0.91,
+          },
+        ],
+        meta: {
+          total: 1,
+          page: 1,
+          limit: 5,
+          totalPages: 1,
+        },
+        query: "sql injection",
+      };
+
+      mockFindingsService.search.mockResolvedValue(response);
+
+      const result = await controller.search(searchDto, workspaceId);
+
+      expect(result).toEqual(response);
+      expect(service.search).toHaveBeenCalledWith(workspaceId, searchDto);
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a finding", async () => {
+      const response = { message: "Finding deleted successfully" };
+      mockFindingsService.remove.mockResolvedValue(response);
+
+      const result = await controller.remove(findingId, workspaceId);
+
+      expect(result).toEqual(response);
+      expect(service.remove).toHaveBeenCalledWith(findingId, workspaceId);
+    });
+  });
+});

apps/api/src/findings/findings.controller.ts

@@ -0,0 +1,81 @@
+import { Body, Controller, Delete, Get, Param, Post, Query, UseGuards } from "@nestjs/common";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { Workspace, Permission, RequirePermission } from "../common/decorators";
+import { CreateFindingDto, QueryFindingsDto, SearchFindingsDto } from "./dto";
+import {
+  FindingsService,
+  FindingsSearchResponse,
+  PaginatedFindingsResponse,
+} from "./findings.service";
+
+/**
+ * Controller for findings endpoints
+ * All endpoints require authentication and workspace context
+ */
+@Controller("findings")
+@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
+export class FindingsController {
+  constructor(private readonly findingsService: FindingsService) {}
+
+  /**
+   * POST /api/findings
+   * Create a new finding and embed its summary
+   * Requires: MEMBER role or higher
+   */
+  @Post()
+  @RequirePermission(Permission.WORKSPACE_MEMBER)
+  async create(@Body() createFindingDto: CreateFindingDto, @Workspace() workspaceId: string) {
+    return this.findingsService.create(workspaceId, createFindingDto);
+  }
+
+  /**
+   * GET /api/findings
+   * Get paginated findings with optional filters
+   * Requires: Any workspace member
+   */
+  @Get()
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findAll(
+    @Query() query: QueryFindingsDto,
+    @Workspace() workspaceId: string
+  ): Promise<PaginatedFindingsResponse> {
+    return this.findingsService.findAll(workspaceId, query);
+  }
+
+  /**
+   * GET /api/findings/:id
+   * Get a single finding by ID
+   * Requires: Any workspace member
+   */
+  @Get(":id")
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findOne(@Param("id") id: string, @Workspace() workspaceId: string) {
+    return this.findingsService.findOne(id, workspaceId);
+  }
+
+  /**
+   * POST /api/findings/search
+   * Semantic search findings by vector similarity
+   * Requires: Any workspace member
+   */
+  @Post("search")
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async search(
+    @Body() searchDto: SearchFindingsDto,
+    @Workspace() workspaceId: string
+  ): Promise<FindingsSearchResponse> {
+    return this.findingsService.search(workspaceId, searchDto);
+  }
+
+  /**
+   * DELETE /api/findings/:id
+   * Delete a finding
+   * Requires: ADMIN role or higher
+   */
+  @Delete(":id")
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async remove(@Param("id") id: string, @Workspace() workspaceId: string) {
+    return this.findingsService.remove(id, workspaceId);
+  }
+}

apps/api/src/findings/findings.integration.spec.ts

@@ -0,0 +1,226 @@
+import { beforeAll, beforeEach, describe, expect, it, afterAll, vi } from "vitest";
+import { randomUUID as uuid } from "crypto";
+import { Test, TestingModule } from "@nestjs/testing";
+import { BadRequestException, NotFoundException } from "@nestjs/common";
+import { PrismaClient, Prisma } from "@prisma/client";
+import { FindingsService } from "./findings.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { EmbeddingService } from "../knowledge/services/embedding.service";
+
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
+
+const EMBEDDING_DIMENSION = 1536;
+
+function vector(value: number): number[] {
+  return Array.from({ length: EMBEDDING_DIMENSION }, () => value);
+}
+
+function toVectorLiteral(input: number[]): string {
+  return `[${input.join(",")}]`;
+}
+
+describeFn("FindingsService Integration", () => {
+  let moduleRef: TestingModule;
+  let prisma: PrismaClient;
+  let service: FindingsService;
+  let workspaceId: string;
+  let ownerId: string;
+  let setupComplete = false;
+
+  const embeddingServiceMock = {
+    isConfigured: vi.fn(),
+    generateEmbedding: vi.fn(),
+  };
+
+  beforeAll(async () => {
+    prisma = new PrismaClient();
+    await prisma.$connect();
+
+    const workspace = await prisma.workspace.create({
+      data: {
+        name: `Findings Integration ${Date.now()}`,
+        owner: {
+          create: {
+            email: `findings-integration-${Date.now()}@example.com`,
+            name: "Findings Integration Owner",
+          },
+        },
+      },
+    });
+
+    workspaceId = workspace.id;
+    ownerId = workspace.ownerId;
+
+    moduleRef = await Test.createTestingModule({
+      providers: [
+        FindingsService,
+        {
+          provide: PrismaService,
+          useValue: prisma,
+        },
+        {
+          provide: EmbeddingService,
+          useValue: embeddingServiceMock,
+        },
+      ],
+    }).compile();
+
+    service = moduleRef.get<FindingsService>(FindingsService);
+    setupComplete = true;
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    embeddingServiceMock.isConfigured.mockReturnValue(false);
+  });
+
+  afterAll(async () => {
+    if (!prisma) {
+      return;
+    }
+
+    if (workspaceId) {
+      await prisma.finding.deleteMany({ where: { workspaceId } });
+      await prisma.workspace.deleteMany({ where: { id: workspaceId } });
+    }
+    if (ownerId) {
+      await prisma.user.deleteMany({ where: { id: ownerId } });
+    }
+
+    if (moduleRef) {
+      await moduleRef.close();
+    }
+    await prisma.$disconnect();
+  });
+
+  it("creates, lists, fetches, and deletes findings", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const created = await service.create(workspaceId, {
+      agentId: "agent-findings-crud",
+      type: "security",
+      title: "Unescaped SQL fragment",
+      data: { severity: "high" },
+      summary: "Potential injection risk in dynamic query path.",
+    });
+
+    expect(created.id).toBeDefined();
+    expect(created.workspaceId).toBe(workspaceId);
+    expect(created.taskId).toBeNull();
+
+    const listed = await service.findAll(workspaceId, {
+      page: 1,
+      limit: 10,
+      agentId: "agent-findings-crud",
+    });
+
+    expect(listed.meta.total).toBeGreaterThanOrEqual(1);
+    expect(listed.data.some((row) => row.id === created.id)).toBe(true);
+
+    const found = await service.findOne(created.id, workspaceId);
+    expect(found.id).toBe(created.id);
+    expect(found.title).toBe("Unescaped SQL fragment");
+
+    await expect(service.findOne(created.id, uuid())).rejects.toThrow(NotFoundException);
+
+    await expect(service.remove(created.id, workspaceId)).resolves.toEqual({
+      message: "Finding deleted successfully",
+    });
+
+    await expect(service.findOne(created.id, workspaceId)).rejects.toThrow(NotFoundException);
+  });
+
+  it("rejects create when taskId does not exist in workspace", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    await expect(
+      service.create(workspaceId, {
+        taskId: uuid(),
+        agentId: "agent-findings-missing-task",
+        type: "bug",
+        title: "Invalid task id",
+        data: { source: "integration-test" },
+        summary: "Should fail when task relation is not found.",
+      })
+    ).rejects.toThrow(NotFoundException);
+  });
+
+  it("rejects vector search when embeddings are disabled", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    embeddingServiceMock.isConfigured.mockReturnValue(false);
+
+    await expect(
+      service.search(workspaceId, {
+        query: "security issue",
+      })
+    ).rejects.toThrow(BadRequestException);
+  });
+
+  it("searches findings by vector similarity with filters", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const near = vector(0.01);
+    const far = vector(0.9);
+
+    const matchedFinding = await prisma.finding.create({
+      data: {
+        workspaceId,
+        agentId: "agent-findings-search-a",
+        type: "incident",
+        title: "Authentication bypass",
+        data: { score: 0.9 } as Prisma.InputJsonValue,
+        summary: "Bypass risk found in login checks.",
+      },
+    });
+
+    const otherFinding = await prisma.finding.create({
+      data: {
+        workspaceId,
+        agentId: "agent-findings-search-b",
+        type: "incident",
+        title: "Retry timeout",
+        data: { score: 0.2 } as Prisma.InputJsonValue,
+        summary: "Timeout issue in downstream retries.",
+      },
+    });
+
+    await prisma.$executeRaw`
+      UPDATE findings
+      SET embedding = ${toVectorLiteral(near)}::vector(1536)
+      WHERE id = ${matchedFinding.id}::uuid
+    `;
+    await prisma.$executeRaw`
+      UPDATE findings
+      SET embedding = ${toVectorLiteral(far)}::vector(1536)
+      WHERE id = ${otherFinding.id}::uuid
+    `;
+
+    embeddingServiceMock.isConfigured.mockReturnValue(true);
+    embeddingServiceMock.generateEmbedding.mockResolvedValue(near);
+
+    const result = await service.search(workspaceId, {
+      query: "authentication bypass risk",
+      agentId: "agent-findings-search-a",
+      limit: 10,
+      similarityThreshold: 0,
+    });
+
+    expect(result.query).toBe("authentication bypass risk");
+    expect(result.meta.total).toBe(1);
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0]?.id).toBe(matchedFinding.id);
+    expect(result.data[0]?.agentId).toBe("agent-findings-search-a");
+    expect(result.data.find((row) => row.id === otherFinding.id)).toBeUndefined();
+  });
+});

apps/api/src/findings/findings.module.ts

@@ -0,0 +1,14 @@
+import { Module } from "@nestjs/common";
+import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
+import { KnowledgeModule } from "../knowledge/knowledge.module";
+import { FindingsController } from "./findings.controller";
+import { FindingsService } from "./findings.service";
+
+@Module({
+  imports: [PrismaModule, AuthModule, KnowledgeModule],
+  controllers: [FindingsController],
+  providers: [FindingsService],
+  exports: [FindingsService],
+})
+export class FindingsModule {}

apps/api/src/findings/findings.service.spec.ts

@@ -0,0 +1,300 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { BadRequestException, NotFoundException } from "@nestjs/common";
+import { FindingsService } from "./findings.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { EmbeddingService } from "../knowledge/services/embedding.service";
+
+describe("FindingsService", () => {
+  let service: FindingsService;
+  let prisma: PrismaService;
+  let embeddingService: EmbeddingService;
+
+  const mockWorkspaceId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockFindingId = "550e8400-e29b-41d4-a716-446655440002";
+  const mockTaskId = "550e8400-e29b-41d4-a716-446655440003";
+
+  const mockPrismaService = {
+    finding: {
+      create: vi.fn(),
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      count: vi.fn(),
+      delete: vi.fn(),
+    },
+    agentTask: {
+      findUnique: vi.fn(),
+    },
+    $queryRaw: vi.fn(),
+    $executeRaw: vi.fn(),
+  };
+
+  const mockEmbeddingService = {
+    isConfigured: vi.fn(),
+    generateEmbedding: vi.fn(),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        FindingsService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+        {
+          provide: EmbeddingService,
+          useValue: mockEmbeddingService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<FindingsService>(FindingsService);
+    prisma = module.get<PrismaService>(PrismaService);
+    embeddingService = module.get<EmbeddingService>(EmbeddingService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(service).toBeDefined();
+  });
+
+  describe("create", () => {
+    it("should create a finding and store embedding when configured", async () => {
+      const createDto = {
+        taskId: mockTaskId,
+        agentId: "research-agent",
+        type: "security",
+        title: "SQL injection risk",
+        data: { severity: "high" },
+        summary: "Potential SQL injection in search endpoint.",
+      };
+
+      const createdFinding = {
+        id: mockFindingId,
+        workspaceId: mockWorkspaceId,
+        ...createDto,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrismaService.agentTask.findUnique.mockResolvedValue({
+        id: mockTaskId,
+        workspaceId: mockWorkspaceId,
+      });
+      mockPrismaService.finding.create.mockResolvedValue(createdFinding);
+      mockPrismaService.finding.findUnique.mockResolvedValue(createdFinding);
+      mockEmbeddingService.isConfigured.mockReturnValue(true);
+      mockEmbeddingService.generateEmbedding.mockResolvedValue([0.1, 0.2, 0.3]);
+      mockPrismaService.$executeRaw.mockResolvedValue(1);
+
+      const result = await service.create(mockWorkspaceId, createDto);
+
+      expect(result).toEqual(createdFinding);
+      expect(prisma.finding.create).toHaveBeenCalledWith({
+        data: expect.objectContaining({
+          workspaceId: mockWorkspaceId,
+          taskId: mockTaskId,
+          agentId: "research-agent",
+          type: "security",
+          title: "SQL injection risk",
+        }),
+        select: expect.any(Object),
+      });
+      expect(embeddingService.generateEmbedding).toHaveBeenCalledWith(createDto.summary);
+      expect(prisma.$executeRaw).toHaveBeenCalled();
+    });
+
+    it("should create a finding without embedding when not configured", async () => {
+      const createDto = {
+        agentId: "research-agent",
+        type: "security",
+        title: "SQL injection risk",
+        data: { severity: "high" },
+        summary: "Potential SQL injection in search endpoint.",
+      };
+
+      const createdFinding = {
+        id: mockFindingId,
+        workspaceId: mockWorkspaceId,
+        taskId: null,
+        ...createDto,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrismaService.finding.create.mockResolvedValue(createdFinding);
+      mockEmbeddingService.isConfigured.mockReturnValue(false);
+
+      const result = await service.create(mockWorkspaceId, createDto);
+
+      expect(result).toEqual(createdFinding);
+      expect(embeddingService.generateEmbedding).not.toHaveBeenCalled();
+      expect(prisma.$executeRaw).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("findAll", () => {
+    it("should return paginated findings with filters", async () => {
+      const findings = [
+        {
+          id: mockFindingId,
+          workspaceId: mockWorkspaceId,
+          taskId: null,
+          agentId: "research-agent",
+          type: "security",
+          title: "SQL injection risk",
+          data: { severity: "high" },
+          summary: "Potential SQL injection in search endpoint.",
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      ];
+
+      mockPrismaService.finding.findMany.mockResolvedValue(findings);
+      mockPrismaService.finding.count.mockResolvedValue(1);
+
+      const result = await service.findAll(mockWorkspaceId, {
+        page: 1,
+        limit: 10,
+        type: "security",
+        agentId: "research-agent",
+      });
+
+      expect(result).toEqual({
+        data: findings,
+        meta: {
+          total: 1,
+          page: 1,
+          limit: 10,
+          totalPages: 1,
+        },
+      });
+      expect(prisma.finding.findMany).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: {
+            workspaceId: mockWorkspaceId,
+            type: "security",
+            agentId: "research-agent",
+          },
+        })
+      );
+    });
+  });
+
+  describe("findOne", () => {
+    it("should return a finding", async () => {
+      const finding = {
+        id: mockFindingId,
+        workspaceId: mockWorkspaceId,
+        taskId: null,
+        agentId: "research-agent",
+        type: "security",
+        title: "SQL injection risk",
+        data: { severity: "high" },
+        summary: "Potential SQL injection in search endpoint.",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrismaService.finding.findUnique.mockResolvedValue(finding);
+
+      const result = await service.findOne(mockFindingId, mockWorkspaceId);
+
+      expect(result).toEqual(finding);
+      expect(prisma.finding.findUnique).toHaveBeenCalledWith({
+        where: {
+          id: mockFindingId,
+          workspaceId: mockWorkspaceId,
+        },
+        select: expect.any(Object),
+      });
+    });
+
+    it("should throw when finding does not exist", async () => {
+      mockPrismaService.finding.findUnique.mockResolvedValue(null);
+
+      await expect(service.findOne(mockFindingId, mockWorkspaceId)).rejects.toThrow(
+        NotFoundException
+      );
+    });
+  });
+
+  describe("search", () => {
+    it("should throw BadRequestException when embeddings are not configured", async () => {
+      mockEmbeddingService.isConfigured.mockReturnValue(false);
+
+      await expect(
+        service.search(mockWorkspaceId, {
+          query: "sql injection",
+        })
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it("should return similarity-ranked search results", async () => {
+      mockEmbeddingService.isConfigured.mockReturnValue(true);
+      mockEmbeddingService.generateEmbedding.mockResolvedValue([0.1, 0.2, 0.3]);
+      mockPrismaService.$queryRaw
+        .mockResolvedValueOnce([
+          {
+            id: mockFindingId,
+            workspace_id: mockWorkspaceId,
+            task_id: null,
+            agent_id: "research-agent",
+            type: "security",
+            title: "SQL injection risk",
+            data: { severity: "high" },
+            summary: "Potential SQL injection in search endpoint.",
+            created_at: new Date(),
+            updated_at: new Date(),
+            score: 0.91,
+          },
+        ])
+        .mockResolvedValueOnce([{ count: BigInt(1) }]);
+
+      const result = await service.search(mockWorkspaceId, {
+        query: "sql injection",
+        page: 1,
+        limit: 5,
+        similarityThreshold: 0.5,
+      });
+
+      expect(result.query).toBe("sql injection");
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].score).toBe(0.91);
+      expect(result.meta.total).toBe(1);
+      expect(prisma.$queryRaw).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a finding", async () => {
+      mockPrismaService.finding.findUnique.mockResolvedValue({
+        id: mockFindingId,
+        workspaceId: mockWorkspaceId,
+      });
+      mockPrismaService.finding.delete.mockResolvedValue({
+        id: mockFindingId,
+      });
+
+      const result = await service.remove(mockFindingId, mockWorkspaceId);
+
+      expect(result).toEqual({ message: "Finding deleted successfully" });
+      expect(prisma.finding.delete).toHaveBeenCalledWith({
+        where: {
+          id: mockFindingId,
+          workspaceId: mockWorkspaceId,
+        },
+      });
+    });
+
+    it("should throw when finding does not exist", async () => {
+      mockPrismaService.finding.findUnique.mockResolvedValue(null);
+
+      await expect(service.remove(mockFindingId, mockWorkspaceId)).rejects.toThrow(
+        NotFoundException
+      );
+    });
+  });
+});

apps/api/src/findings/findings.service.ts

@@ -0,0 +1,337 @@
+import { BadRequestException, Injectable, Logger, NotFoundException } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { PrismaService } from "../prisma/prisma.service";
+import { EmbeddingService } from "../knowledge/services/embedding.service";
+import type { CreateFindingDto, QueryFindingsDto, SearchFindingsDto } from "./dto";
+
+const findingSelect = {
+  id: true,
+  workspaceId: true,
+  taskId: true,
+  agentId: true,
+  type: true,
+  title: true,
+  data: true,
+  summary: true,
+  createdAt: true,
+  updatedAt: true,
+} satisfies Prisma.FindingSelect;
+
+type FindingRecord = Prisma.FindingGetPayload<{ select: typeof findingSelect }>;
+
+interface RawFindingSearchResult {
+  id: string;
+  workspace_id: string;
+  task_id: string | null;
+  agent_id: string;
+  type: string;
+  title: string;
+  data: Prisma.JsonValue;
+  summary: string;
+  created_at: Date;
+  updated_at: Date;
+  score: number;
+}
+
+export interface FindingSearchResult extends FindingRecord {
+  score: number;
+}
+
+interface PaginatedMeta {
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+
+export interface PaginatedFindingsResponse {
+  data: FindingRecord[];
+  meta: PaginatedMeta;
+}
+
+export interface FindingsSearchResponse {
+  data: FindingSearchResult[];
+  meta: PaginatedMeta;
+  query: string;
+  similarityThreshold: number;
+}
+
+/**
+ * Service for managing structured findings with vector search support
+ */
+@Injectable()
+export class FindingsService {
+  private readonly logger = new Logger(FindingsService.name);
+  private readonly defaultSimilarityThreshold: number;
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly embeddingService: EmbeddingService
+  ) {
+    const parsedThreshold = Number.parseFloat(process.env.FINDINGS_SIMILARITY_THRESHOLD ?? "0.5");
+
+    this.defaultSimilarityThreshold =
+      Number.isFinite(parsedThreshold) && parsedThreshold >= 0 && parsedThreshold <= 1
+        ? parsedThreshold
+        : 0.5;
+  }
+
+  /**
+   * Create a finding and generate its embedding from the summary when available
+   */
+  async create(workspaceId: string, createFindingDto: CreateFindingDto): Promise<FindingRecord> {
+    if (createFindingDto.taskId) {
+      const task = await this.prisma.agentTask.findUnique({
+        where: {
+          id: createFindingDto.taskId,
+          workspaceId,
+        },
+        select: { id: true },
+      });
+
+      if (!task) {
+        throw new NotFoundException(`Agent task with ID ${createFindingDto.taskId} not found`);
+      }
+    }
+
+    const createInput: Prisma.FindingUncheckedCreateInput = {
+      workspaceId,
+      agentId: createFindingDto.agentId,
+      type: createFindingDto.type,
+      title: createFindingDto.title,
+      data: createFindingDto.data as Prisma.InputJsonValue,
+      summary: createFindingDto.summary,
+    };
+
+    if (createFindingDto.taskId) {
+      createInput.taskId = createFindingDto.taskId;
+    }
+
+    const finding = await this.prisma.finding.create({
+      data: createInput,
+      select: findingSelect,
+    });
+
+    await this.generateAndStoreEmbedding(finding.id, workspaceId, finding.summary);
+
+    if (this.embeddingService.isConfigured()) {
+      return this.findOne(finding.id, workspaceId);
+    }
+
+    return finding;
+  }
+
+  /**
+   * Get paginated findings with optional filters
+   */
+  async findAll(workspaceId: string, query: QueryFindingsDto): Promise<PaginatedFindingsResponse> {
+    const page = query.page ?? 1;
+    const limit = query.limit ?? 50;
+    const skip = (page - 1) * limit;
+
+    const where: Prisma.FindingWhereInput = {
+      workspaceId,
+    };
+
+    if (query.agentId) {
+      where.agentId = query.agentId;
+    }
+
+    if (query.type) {
+      where.type = query.type;
+    }
+
+    if (query.taskId) {
+      where.taskId = query.taskId;
+    }
+
+    const [data, total] = await Promise.all([
+      this.prisma.finding.findMany({
+        where,
+        select: findingSelect,
+        orderBy: {
+          createdAt: "desc",
+        },
+        skip,
+        take: limit,
+      }),
+      this.prisma.finding.count({ where }),
+    ]);
+
+    return {
+      data,
+      meta: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  /**
+   * Get a single finding by ID
+   */
+  async findOne(id: string, workspaceId: string): Promise<FindingRecord> {
+    const finding = await this.prisma.finding.findUnique({
+      where: {
+        id,
+        workspaceId,
+      },
+      select: findingSelect,
+    });
+
+    if (!finding) {
+      throw new NotFoundException(`Finding with ID ${id} not found`);
+    }
+
+    return finding;
+  }
+
+  /**
+   * Semantic search findings using vector similarity
+   */
+  async search(workspaceId: string, searchDto: SearchFindingsDto): Promise<FindingsSearchResponse> {
+    if (!this.embeddingService.isConfigured()) {
+      throw new BadRequestException(
+        "Finding vector search requires OPENAI_API_KEY to be configured"
+      );
+    }
+
+    const page = searchDto.page ?? 1;
+    const limit = searchDto.limit ?? 20;
+    const offset = (page - 1) * limit;
+    const similarityThreshold = searchDto.similarityThreshold ?? this.defaultSimilarityThreshold;
+    const distanceThreshold = 1 - similarityThreshold;
+
+    const queryEmbedding = await this.embeddingService.generateEmbedding(searchDto.query);
+    const embeddingString = `[${queryEmbedding.join(",")}]`;
+
+    const agentFilter = searchDto.agentId
+      ? Prisma.sql`AND f.agent_id = ${searchDto.agentId}`
+      : Prisma.sql``;
+    const typeFilter = searchDto.type ? Prisma.sql`AND f.type = ${searchDto.type}` : Prisma.sql``;
+    const taskFilter = searchDto.taskId
+      ? Prisma.sql`AND f.task_id = ${searchDto.taskId}::uuid`
+      : Prisma.sql``;
+
+    const searchResults = await this.prisma.$queryRaw<RawFindingSearchResult[]>`
+      SELECT
+        f.id,
+        f.workspace_id,
+        f.task_id,
+        f.agent_id,
+        f.type,
+        f.title,
+        f.data,
+        f.summary,
+        f.created_at,
+        f.updated_at,
+        (1 - (f.embedding <=> ${embeddingString}::vector)) AS score
+      FROM findings f
+      WHERE f.workspace_id = ${workspaceId}::uuid
+        AND f.embedding IS NOT NULL
+        ${agentFilter}
+        ${typeFilter}
+        ${taskFilter}
+        AND (f.embedding <=> ${embeddingString}::vector) <= ${distanceThreshold}
+      ORDER BY f.embedding <=> ${embeddingString}::vector
+      LIMIT ${limit}
+      OFFSET ${offset}
+    `;
+
+    const countResult = await this.prisma.$queryRaw<[{ count: bigint }]>`
+      SELECT COUNT(*) as count
+      FROM findings f
+      WHERE f.workspace_id = ${workspaceId}::uuid
+        AND f.embedding IS NOT NULL
+        ${agentFilter}
+        ${typeFilter}
+        ${taskFilter}
+        AND (f.embedding <=> ${embeddingString}::vector) <= ${distanceThreshold}
+    `;
+
+    const total = Number(countResult[0].count);
+
+    const data: FindingSearchResult[] = searchResults.map((row) => ({
+      id: row.id,
+      workspaceId: row.workspace_id,
+      taskId: row.task_id,
+      agentId: row.agent_id,
+      type: row.type,
+      title: row.title,
+      data: row.data,
+      summary: row.summary,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      score: row.score,
+    }));
+
+    return {
+      data,
+      meta: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+      query: searchDto.query,
+      similarityThreshold,
+    };
+  }
+
+  /**
+   * Delete a finding
+   */
+  async remove(id: string, workspaceId: string): Promise<{ message: string }> {
+    const existingFinding = await this.prisma.finding.findUnique({
+      where: {
+        id,
+        workspaceId,
+      },
+      select: { id: true },
+    });
+
+    if (!existingFinding) {
+      throw new NotFoundException(`Finding with ID ${id} not found`);
+    }
+
+    await this.prisma.finding.delete({
+      where: {
+        id,
+        workspaceId,
+      },
+    });
+
+    return { message: "Finding deleted successfully" };
+  }
+
+  /**
+   * Generate and persist embedding for a finding summary
+   */
+  private async generateAndStoreEmbedding(
+    findingId: string,
+    workspaceId: string,
+    summary: string
+  ): Promise<void> {
+    if (!this.embeddingService.isConfigured()) {
+      return;
+    }
+
+    try {
+      const embedding = await this.embeddingService.generateEmbedding(summary);
+      const embeddingString = `[${embedding.join(",")}]`;
+
+      await this.prisma.$executeRaw`
+        UPDATE findings
+        SET embedding = ${embeddingString}::vector,
+            updated_at = NOW()
+        WHERE id = ${findingId}::uuid
+          AND workspace_id = ${workspaceId}::uuid
+      `;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`Failed to generate embedding for finding ${findingId}: ${message}`);
+    }
+  }
+}

apps/api/src/import/dto/import-project.dto.ts

@@ -0,0 +1,89 @@
+import { IsNumber, IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+
+/**
+ * DTO for a single jarvis-brain project record.
+ * This matches the project object shape consumed by scripts/migrate-brain.ts.
+ */
+export class ImportProjectDto {
+  @IsString({ message: "id must be a string" })
+  @MinLength(1, { message: "id must not be empty" })
+  @MaxLength(255, { message: "id must not exceed 255 characters" })
+  id!: string;
+
+  @IsString({ message: "name must be a string" })
+  @MinLength(1, { message: "name must not be empty" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name!: string;
+
+  @IsOptional()
+  @IsString({ message: "description must be a string" })
+  description?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "domain must be a string" })
+  domain?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "status must be a string" })
+  status?: string | null;
+
+  // jarvis-brain project priority can be a number, string, or null
+  @IsOptional()
+  priority?: number | string | null;
+
+  @IsOptional()
+  @IsNumber({}, { message: "progress must be a number" })
+  progress?: number | null;
+
+  @IsOptional()
+  @IsString({ message: "repo must be a string" })
+  repo?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "branch must be a string" })
+  branch?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "current_milestone must be a string" })
+  current_milestone?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "next_milestone must be a string" })
+  next_milestone?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "blocker must be a string" })
+  blocker?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "owner must be a string" })
+  owner?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "docs_path must be a string" })
+  docs_path?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "created must be a string" })
+  created?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "updated must be a string" })
+  updated?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "target_date must be a string" })
+  target_date?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "notes must be a string" })
+  notes?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "notes_nontechnical must be a string" })
+  notes_nontechnical?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "parent must be a string" })
+  parent?: string | null;
+}

apps/api/src/import/dto/import-response.dto.ts

@@ -0,0 +1,5 @@
+export interface ImportResponseDto {
+  imported: number;
+  skipped: number;
+  errors: string[];
+}

apps/api/src/import/dto/import-task.dto.ts

@@ -0,0 +1,76 @@
+import { IsArray, IsNumber, IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+
+/**
+ * DTO for a single jarvis-brain task record.
+ * This matches the task object shape consumed by scripts/migrate-brain.ts.
+ */
+export class ImportTaskDto {
+  @IsString({ message: "id must be a string" })
+  @MinLength(1, { message: "id must not be empty" })
+  @MaxLength(255, { message: "id must not exceed 255 characters" })
+  id!: string;
+
+  @IsString({ message: "title must be a string" })
+  @MinLength(1, { message: "title must not be empty" })
+  @MaxLength(255, { message: "title must not exceed 255 characters" })
+  title!: string;
+
+  @IsOptional()
+  @IsString({ message: "domain must be a string" })
+  domain?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "project must be a string" })
+  project?: string | null;
+
+  @IsOptional()
+  @IsArray({ message: "related must be an array" })
+  @IsString({ each: true, message: "related items must be strings" })
+  related?: string[];
+
+  @IsOptional()
+  @IsString({ message: "priority must be a string" })
+  priority?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "status must be a string" })
+  status?: string | null;
+
+  @IsOptional()
+  @IsNumber({}, { message: "progress must be a number" })
+  progress?: number | null;
+
+  @IsOptional()
+  @IsString({ message: "due must be a string" })
+  due?: string | null;
+
+  @IsOptional()
+  @IsArray({ message: "blocks must be an array" })
+  @IsString({ each: true, message: "blocks items must be strings" })
+  blocks?: string[];
+
+  @IsOptional()
+  @IsArray({ message: "blocked_by must be an array" })
+  @IsString({ each: true, message: "blocked_by items must be strings" })
+  blocked_by?: string[];
+
+  @IsOptional()
+  @IsString({ message: "assignee must be a string" })
+  assignee?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "created must be a string" })
+  created?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "updated must be a string" })
+  updated?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "notes must be a string" })
+  notes?: string | null;
+
+  @IsOptional()
+  @IsString({ message: "notes_nontechnical must be a string" })
+  notes_nontechnical?: string | null;
+}

apps/api/src/import/dto/index.ts

@@ -0,0 +1,3 @@
+export { ImportTaskDto } from "./import-task.dto";
+export { ImportProjectDto } from "./import-project.dto";
+export type { ImportResponseDto } from "./import-response.dto";

apps/api/src/import/import.controller.ts

@@ -0,0 +1,33 @@
+import { Body, Controller, ParseArrayPipe, Post, UseGuards } from "@nestjs/common";
+import type { AuthUser } from "@mosaic/shared";
+import { CurrentUser } from "../auth/decorators/current-user.decorator";
+import { AdminGuard } from "../auth/guards/admin.guard";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { Workspace } from "../common/decorators";
+import { WorkspaceGuard } from "../common/guards";
+import { ImportProjectDto, type ImportResponseDto, ImportTaskDto } from "./dto";
+import { ImportService } from "./import.service";
+
+@Controller("import")
+@UseGuards(AuthGuard, WorkspaceGuard, AdminGuard)
+export class ImportController {
+  constructor(private readonly importService: ImportService) {}
+
+  @Post("tasks")
+  async importTasks(
+    @Body(new ParseArrayPipe({ items: ImportTaskDto })) taskPayload: ImportTaskDto[],
+    @Workspace() workspaceId: string,
+    @CurrentUser() user: AuthUser
+  ): Promise<ImportResponseDto> {
+    return this.importService.importTasks(workspaceId, user.id, taskPayload);
+  }
+
+  @Post("projects")
+  async importProjects(
+    @Body(new ParseArrayPipe({ items: ImportProjectDto })) projectPayload: ImportProjectDto[],
+    @Workspace() workspaceId: string,
+    @CurrentUser() user: AuthUser
+  ): Promise<ImportResponseDto> {
+    return this.importService.importProjects(workspaceId, user.id, projectPayload);
+  }
+}

apps/api/src/import/import.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { PrismaModule } from "../prisma/prisma.module";
+import { ImportController } from "./import.controller";
+import { ImportService } from "./import.service";
+
+@Module({
+  imports: [PrismaModule, AuthModule],
+  controllers: [ImportController],
+  providers: [ImportService],
+  exports: [ImportService],
+})
+export class ImportModule {}

apps/api/src/import/import.service.spec.ts

@@ -0,0 +1,251 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { ProjectStatus, TaskPriority, TaskStatus } from "@prisma/client";
+import { ImportService } from "./import.service";
+import { PrismaService } from "../prisma/prisma.service";
+
+describe("ImportService", () => {
+  let service: ImportService;
+
+  const mockPrismaService = {
+    withWorkspaceContext: vi.fn(),
+    domain: {
+      findUnique: vi.fn(),
+      create: vi.fn(),
+    },
+    project: {
+      findFirst: vi.fn(),
+      create: vi.fn(),
+    },
+    task: {
+      findFirst: vi.fn(),
+      create: vi.fn(),
+    },
+  };
+
+  const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
+  const userId = "550e8400-e29b-41d4-a716-446655440002";
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        ImportService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<ImportService>(ImportService);
+    vi.clearAllMocks();
+
+    mockPrismaService.withWorkspaceContext.mockImplementation(
+      async (_userId: string, _workspaceId: string, fn: (client: unknown) => Promise<unknown>) => {
+        return fn(mockPrismaService);
+      }
+    );
+  });
+
+  it("should be defined", () => {
+    expect(service).toBeDefined();
+  });
+
+  describe("importTasks", () => {
+    it("maps status/priority/domain and imports a task", async () => {
+      mockPrismaService.task.findFirst.mockResolvedValue(null);
+      mockPrismaService.domain.findUnique.mockResolvedValue(null);
+      mockPrismaService.domain.create.mockResolvedValue({ id: "domain-id" });
+      mockPrismaService.project.findFirst.mockResolvedValue(null);
+      mockPrismaService.task.create.mockResolvedValue({ id: "task-id" });
+
+      const result = await service.importTasks(workspaceId, userId, [
+        {
+          id: "task-1",
+          title: "Import me",
+          domain: "Platform Ops",
+          status: "in-progress",
+          priority: "critical",
+          project: null,
+          related: [],
+          blocks: [],
+          blocked_by: [],
+          progress: 42,
+          due: "2026-03-15",
+          created: "2026-03-01T10:00:00.000Z",
+          updated: "2026-03-05T12:00:00.000Z",
+          assignee: null,
+          notes: "notes",
+          notes_nontechnical: "non technical",
+        },
+      ]);
+
+      expect(result).toEqual({ imported: 1, skipped: 0, errors: [] });
+      expect(mockPrismaService.task.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            title: "Import me",
+            status: TaskStatus.IN_PROGRESS,
+            priority: TaskPriority.HIGH,
+            domainId: "domain-id",
+          }),
+        })
+      );
+    });
+
+    it("skips existing task by brainId", async () => {
+      mockPrismaService.task.findFirst.mockResolvedValue({ id: "existing-task-id" });
+
+      const result = await service.importTasks(workspaceId, userId, [
+        {
+          id: "task-1",
+          title: "Existing",
+          domain: null,
+          status: "pending",
+          priority: "medium",
+          project: null,
+          related: [],
+          blocks: [],
+          blocked_by: [],
+          progress: null,
+          due: null,
+          created: null,
+          updated: null,
+          assignee: null,
+          notes: null,
+          notes_nontechnical: null,
+        },
+      ]);
+
+      expect(result.imported).toBe(0);
+      expect(result.skipped).toBe(1);
+      expect(mockPrismaService.task.create).not.toHaveBeenCalled();
+    });
+
+    it("collects mapping/missing-project errors while importing", async () => {
+      mockPrismaService.task.findFirst.mockResolvedValue(null);
+      mockPrismaService.project.findFirst.mockResolvedValue(null);
+      mockPrismaService.task.create.mockResolvedValue({ id: "task-id" });
+
+      const result = await service.importTasks(workspaceId, userId, [
+        {
+          id: "task-1",
+          title: "Needs project",
+          domain: null,
+          status: "mystery-status",
+          priority: "mystery-priority",
+          project: "brain-project-1",
+          related: [],
+          blocks: [],
+          blocked_by: [],
+          progress: null,
+          due: null,
+          created: null,
+          updated: null,
+          assignee: null,
+          notes: null,
+          notes_nontechnical: null,
+        },
+      ]);
+
+      expect(result.imported).toBe(1);
+      expect(result.errors).toEqual(
+        expect.arrayContaining([
+          expect.stringContaining('Unknown task status "mystery-status"'),
+          expect.stringContaining('Unknown task priority "mystery-priority"'),
+          expect.stringContaining('referenced project "brain-project-1" not found'),
+        ])
+      );
+      expect(mockPrismaService.task.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            status: TaskStatus.NOT_STARTED,
+            priority: TaskPriority.MEDIUM,
+            projectId: null,
+          }),
+        })
+      );
+    });
+  });
+
+  describe("importProjects", () => {
+    it("maps status/domain and imports a project", async () => {
+      mockPrismaService.project.findFirst.mockResolvedValue(null);
+      mockPrismaService.domain.findUnique.mockResolvedValue(null);
+      mockPrismaService.domain.create.mockResolvedValue({ id: "domain-id" });
+      mockPrismaService.project.create.mockResolvedValue({ id: "project-id" });
+
+      const result = await service.importProjects(workspaceId, userId, [
+        {
+          id: "project-1",
+          name: "Project One",
+          description: "desc",
+          domain: "Backend",
+          status: "in-progress",
+          priority: "high",
+          progress: 50,
+          repo: "git@example.com/repo",
+          branch: "main",
+          current_milestone: "MS21",
+          next_milestone: "MS22",
+          blocker: null,
+          owner: "owner",
+          docs_path: "docs/PRD.md",
+          created: "2026-03-01",
+          updated: "2026-03-05",
+          target_date: "2026-04-01",
+          notes: "notes",
+          notes_nontechnical: "non tech",
+          parent: null,
+        },
+      ]);
+
+      expect(result).toEqual({ imported: 1, skipped: 0, errors: [] });
+      expect(mockPrismaService.project.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            name: "Project One",
+            status: ProjectStatus.ACTIVE,
+            domainId: "domain-id",
+          }),
+        })
+      );
+    });
+
+    it("captures create failures as errors", async () => {
+      mockPrismaService.project.findFirst.mockResolvedValue(null);
+      mockPrismaService.project.create.mockRejectedValue(new Error("db failed"));
+
+      const result = await service.importProjects(workspaceId, userId, [
+        {
+          id: "project-1",
+          name: "Project One",
+          description: null,
+          domain: null,
+          status: "planning",
+          priority: null,
+          progress: null,
+          repo: null,
+          branch: null,
+          current_milestone: null,
+          next_milestone: null,
+          blocker: null,
+          owner: null,
+          docs_path: null,
+          created: null,
+          updated: null,
+          target_date: null,
+          notes: null,
+          notes_nontechnical: null,
+          parent: null,
+        },
+      ]);
+
+      expect(result.imported).toBe(0);
+      expect(result.skipped).toBe(1);
+      expect(result.errors).toEqual([
+        expect.stringContaining("project project-1: failed to import: db failed"),
+      ]);
+    });
+  });
+});

apps/api/src/import/import.service.ts

@@ -0,0 +1,496 @@
+import { Injectable } from "@nestjs/common";
+import { Prisma, PrismaClient, ProjectStatus, TaskPriority, TaskStatus } from "@prisma/client";
+import { PrismaService } from "../prisma/prisma.service";
+import type { ImportProjectDto, ImportResponseDto, ImportTaskDto } from "./dto";
+
+interface TaskStatusMapping {
+  status: TaskStatus;
+  issue: string | null;
+}
+
+interface TaskPriorityMapping {
+  priority: TaskPriority;
+  issue: string | null;
+}
+
+interface ProjectStatusMapping {
+  status: ProjectStatus;
+  issue: string | null;
+}
+
+@Injectable()
+export class ImportService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async importTasks(
+    workspaceId: string,
+    userId: string,
+    taskPayload: ImportTaskDto[]
+  ): Promise<ImportResponseDto> {
+    const errors: string[] = [];
+    let imported = 0;
+    let skipped = 0;
+
+    const importTimestamp = new Date().toISOString();
+    const seenBrainTaskIds = new Set<string>();
+    const domainIdBySlug = new Map<string, string>();
+    const projectIdByBrainId = new Map<string, string | null>();
+
+    await this.prisma.withWorkspaceContext(userId, workspaceId, async (tx: PrismaClient) => {
+      for (const [index, task] of taskPayload.entries()) {
+        const brainId = task.id.trim();
+
+        if (seenBrainTaskIds.has(brainId)) {
+          skipped += 1;
+          errors.push(`task ${brainId}: duplicate item in request body`);
+          continue;
+        }
+        seenBrainTaskIds.add(brainId);
+
+        try {
+          const existingTask = await tx.task.findFirst({
+            where: {
+              workspaceId,
+              metadata: {
+                path: ["brainId"],
+                equals: brainId,
+              },
+            },
+            select: { id: true },
+          });
+
+          if (existingTask) {
+            skipped += 1;
+            continue;
+          }
+
+          const mappedStatus = this.mapTaskStatus(task.status ?? null);
+          if (mappedStatus.issue) {
+            errors.push(`task ${brainId}: ${mappedStatus.issue}`);
+          }
+
+          const mappedPriority = this.mapTaskPriority(task.priority ?? null);
+          if (mappedPriority.issue) {
+            errors.push(`task ${brainId}: ${mappedPriority.issue}`);
+          }
+
+          const projectBrainId = task.project?.trim() ? task.project.trim() : null;
+          const projectId = await this.resolveProjectId(
+            tx,
+            workspaceId,
+            projectBrainId,
+            projectIdByBrainId,
+            brainId,
+            errors
+          );
+
+          const domainId = await this.resolveDomainId(
+            tx,
+            workspaceId,
+            task.domain ?? null,
+            importTimestamp,
+            domainIdBySlug
+          );
+
+          const createdAt =
+            this.normalizeDate(task.created ?? null, `task ${brainId}.created`, errors) ??
+            new Date();
+          const updatedAt =
+            this.normalizeDate(task.updated ?? null, `task ${brainId}.updated`, errors) ??
+            createdAt;
+          const dueDate = this.normalizeDate(task.due ?? null, `task ${brainId}.due`, errors);
+          const completedAt = mappedStatus.status === TaskStatus.COMPLETED ? updatedAt : null;
+
+          const metadata = this.asJsonValue({
+            source: "jarvis-brain",
+            brainId,
+            brainDomain: task.domain ?? null,
+            brainProjectId: projectBrainId,
+            rawStatus: task.status ?? null,
+            rawPriority: task.priority ?? null,
+            related: task.related ?? [],
+            blocks: task.blocks ?? [],
+            blockedBy: task.blocked_by ?? [],
+            assignee: task.assignee ?? null,
+            progress: task.progress ?? null,
+            notes: task.notes ?? null,
+            notesNonTechnical: task.notes_nontechnical ?? null,
+            importedAt: importTimestamp,
+          });
+
+          await tx.task.create({
+            data: {
+              workspaceId,
+              title: task.title,
+              description: task.notes ?? null,
+              status: mappedStatus.status,
+              priority: mappedPriority.priority,
+              dueDate,
+              creatorId: userId,
+              projectId,
+              domainId,
+              metadata,
+              createdAt,
+              updatedAt,
+              completedAt,
+            },
+          });
+
+          imported += 1;
+        } catch (error) {
+          skipped += 1;
+          errors.push(
+            `task ${brainId || `index-${String(index)}`}: failed to import: ${this.getErrorMessage(error)}`
+          );
+        }
+      }
+    });
+
+    return {
+      imported,
+      skipped,
+      errors,
+    };
+  }
+
+  async importProjects(
+    workspaceId: string,
+    userId: string,
+    projectPayload: ImportProjectDto[]
+  ): Promise<ImportResponseDto> {
+    const errors: string[] = [];
+    let imported = 0;
+    let skipped = 0;
+
+    const importTimestamp = new Date().toISOString();
+    const seenBrainProjectIds = new Set<string>();
+    const domainIdBySlug = new Map<string, string>();
+
+    await this.prisma.withWorkspaceContext(userId, workspaceId, async (tx: PrismaClient) => {
+      for (const [index, project] of projectPayload.entries()) {
+        const brainId = project.id.trim();
+
+        if (seenBrainProjectIds.has(brainId)) {
+          skipped += 1;
+          errors.push(`project ${brainId}: duplicate item in request body`);
+          continue;
+        }
+        seenBrainProjectIds.add(brainId);
+
+        try {
+          const existingProject = await tx.project.findFirst({
+            where: {
+              workspaceId,
+              metadata: {
+                path: ["brainId"],
+                equals: brainId,
+              },
+            },
+            select: { id: true },
+          });
+
+          if (existingProject) {
+            skipped += 1;
+            continue;
+          }
+
+          const mappedStatus = this.mapProjectStatus(project.status ?? null);
+          if (mappedStatus.issue) {
+            errors.push(`project ${brainId}: ${mappedStatus.issue}`);
+          }
+
+          const domainId = await this.resolveDomainId(
+            tx,
+            workspaceId,
+            project.domain ?? null,
+            importTimestamp,
+            domainIdBySlug
+          );
+
+          const createdAt =
+            this.normalizeDate(project.created ?? null, `project ${brainId}.created`, errors) ??
+            new Date();
+          const updatedAt =
+            this.normalizeDate(project.updated ?? null, `project ${brainId}.updated`, errors) ??
+            createdAt;
+          const startDate = this.normalizeDate(
+            project.created ?? null,
+            `project ${brainId}.startDate`,
+            errors
+          );
+          const endDate = this.normalizeDate(
+            project.target_date ?? null,
+            `project ${brainId}.target_date`,
+            errors
+          );
+
+          const metadata = this.asJsonValue({
+            source: "jarvis-brain",
+            brainId,
+            brainDomain: project.domain ?? null,
+            rawStatus: project.status ?? null,
+            rawPriority: project.priority ?? null,
+            progress: project.progress ?? null,
+            repo: project.repo ?? null,
+            branch: project.branch ?? null,
+            currentMilestone: project.current_milestone ?? null,
+            nextMilestone: project.next_milestone ?? null,
+            blocker: project.blocker ?? null,
+            owner: project.owner ?? null,
+            docsPath: project.docs_path ?? null,
+            targetDate: project.target_date ?? null,
+            notes: project.notes ?? null,
+            notesNonTechnical: project.notes_nontechnical ?? null,
+            parent: project.parent ?? null,
+            importedAt: importTimestamp,
+          });
+
+          await tx.project.create({
+            data: {
+              workspaceId,
+              name: project.name,
+              description: project.description ?? null,
+              status: mappedStatus.status,
+              startDate,
+              endDate,
+              creatorId: userId,
+              domainId,
+              metadata,
+              createdAt,
+              updatedAt,
+            },
+          });
+
+          imported += 1;
+        } catch (error) {
+          skipped += 1;
+          errors.push(
+            `project ${brainId || `index-${String(index)}`}: failed to import: ${this.getErrorMessage(error)}`
+          );
+        }
+      }
+    });
+
+    return {
+      imported,
+      skipped,
+      errors,
+    };
+  }
+
+  private async resolveProjectId(
+    tx: PrismaClient,
+    workspaceId: string,
+    projectBrainId: string | null,
+    projectIdByBrainId: Map<string, string | null>,
+    taskBrainId: string,
+    errors: string[]
+  ): Promise<string | null> {
+    if (!projectBrainId) {
+      return null;
+    }
+
+    if (projectIdByBrainId.has(projectBrainId)) {
+      return projectIdByBrainId.get(projectBrainId) ?? null;
+    }
+
+    const existingProject = await tx.project.findFirst({
+      where: {
+        workspaceId,
+        metadata: {
+          path: ["brainId"],
+          equals: projectBrainId,
+        },
+      },
+      select: { id: true },
+    });
+
+    if (!existingProject) {
+      projectIdByBrainId.set(projectBrainId, null);
+      errors.push(`task ${taskBrainId}: referenced project "${projectBrainId}" not found`);
+      return null;
+    }
+
+    projectIdByBrainId.set(projectBrainId, existingProject.id);
+    return existingProject.id;
+  }
+
+  private async resolveDomainId(
+    tx: PrismaClient,
+    workspaceId: string,
+    rawDomain: string | null,
+    importTimestamp: string,
+    domainIdBySlug: Map<string, string>
+  ): Promise<string | null> {
+    const domainSlug = this.normalizeDomain(rawDomain);
+    if (!domainSlug) {
+      return null;
+    }
+
+    const cachedId = domainIdBySlug.get(domainSlug);
+    if (cachedId) {
+      return cachedId;
+    }
+
+    const existingDomain = await tx.domain.findUnique({
+      where: {
+        workspaceId_slug: {
+          workspaceId,
+          slug: domainSlug,
+        },
+      },
+      select: { id: true },
+    });
+
+    if (existingDomain) {
+      domainIdBySlug.set(domainSlug, existingDomain.id);
+      return existingDomain.id;
+    }
+
+    const trimmedDomainName = rawDomain?.trim();
+    const domainName =
+      trimmedDomainName && trimmedDomainName.length > 0 ? trimmedDomainName : domainSlug;
+    const createdDomain = await tx.domain.create({
+      data: {
+        workspaceId,
+        slug: domainSlug,
+        name: domainName,
+        metadata: this.asJsonValue({
+          source: "jarvis-brain",
+          brainId: domainName,
+          sourceValues: [domainName],
+          importedAt: importTimestamp,
+        }),
+      },
+      select: { id: true },
+    });
+
+    domainIdBySlug.set(domainSlug, createdDomain.id);
+    return createdDomain.id;
+  }
+
+  private normalizeKey(value: string | null | undefined): string {
+    return value?.trim().toLowerCase() ?? "";
+  }
+
+  private mapTaskStatus(rawStatus: string | null): TaskStatusMapping {
+    const statusKey = this.normalizeKey(rawStatus);
+
+    switch (statusKey) {
+      case "done":
+        return { status: TaskStatus.COMPLETED, issue: null };
+      case "in-progress":
+        return { status: TaskStatus.IN_PROGRESS, issue: null };
+      case "backlog":
+      case "pending":
+      case "scheduled":
+      case "not-started":
+      case "planned":
+        return { status: TaskStatus.NOT_STARTED, issue: null };
+      case "blocked":
+      case "on-hold":
+        return { status: TaskStatus.PAUSED, issue: null };
+      case "cancelled":
+        return { status: TaskStatus.ARCHIVED, issue: null };
+      default:
+        return {
+          status: TaskStatus.NOT_STARTED,
+          issue: `Unknown task status "${rawStatus ?? "null"}" mapped to NOT_STARTED`,
+        };
+    }
+  }
+
+  private mapTaskPriority(rawPriority: string | null): TaskPriorityMapping {
+    const priorityKey = this.normalizeKey(rawPriority);
+
+    switch (priorityKey) {
+      case "critical":
+      case "high":
+        return { priority: TaskPriority.HIGH, issue: null };
+      case "medium":
+        return { priority: TaskPriority.MEDIUM, issue: null };
+      case "low":
+        return { priority: TaskPriority.LOW, issue: null };
+      default:
+        return {
+          priority: TaskPriority.MEDIUM,
+          issue: `Unknown task priority "${rawPriority ?? "null"}" mapped to MEDIUM`,
+        };
+    }
+  }
+
+  private mapProjectStatus(rawStatus: string | null): ProjectStatusMapping {
+    const statusKey = this.normalizeKey(rawStatus);
+
+    switch (statusKey) {
+      case "active":
+      case "in-progress":
+        return { status: ProjectStatus.ACTIVE, issue: null };
+      case "backlog":
+      case "planning":
+        return { status: ProjectStatus.PLANNING, issue: null };
+      case "paused":
+      case "blocked":
+        return { status: ProjectStatus.PAUSED, issue: null };
+      case "archived":
+      case "maintenance":
+        return { status: ProjectStatus.ARCHIVED, issue: null };
+      default:
+        return {
+          status: ProjectStatus.PLANNING,
+          issue: `Unknown project status "${rawStatus ?? "null"}" mapped to PLANNING`,
+        };
+    }
+  }
+
+  private normalizeDomain(rawDomain: string | null | undefined): string | null {
+    if (!rawDomain) {
+      return null;
+    }
+
+    const trimmed = rawDomain.trim();
+    if (trimmed.length === 0) {
+      return null;
+    }
+
+    const slug = trimmed
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+
+    return slug.length > 0 ? slug : null;
+  }
+
+  private normalizeDate(rawValue: string | null, context: string, errors: string[]): Date | null {
+    if (!rawValue) {
+      return null;
+    }
+
+    const trimmed = rawValue.trim();
+    if (trimmed.length === 0) {
+      return null;
+    }
+
+    const value = /^\d{4}-\d{2}-\d{2}$/.test(trimmed) ? `${trimmed}T00:00:00.000Z` : trimmed;
+    const parsedDate = new Date(value);
+
+    if (Number.isNaN(parsedDate.getTime())) {
+      errors.push(`${context}: invalid date "${rawValue}"`);
+      return null;
+    }
+
+    return parsedDate;
+  }
+
+  private asJsonValue(value: Record<string, unknown>): Prisma.InputJsonValue {
+    return value as Prisma.InputJsonValue;
+  }
+
+  private getErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+
+    return String(error);
+  }
+}

apps/api/src/tasks/dto/create-task.dto.ts

@@ -50,6 +50,12 @@ export class CreateTaskDto {
   @IsUUID("4", { message: "parentId must be a valid UUID" })
   parentId?: string;
 
+  @IsOptional()
+  @IsString({ message: "assignedAgent must be a string" })
+  @MinLength(1, { message: "assignedAgent must not be empty" })
+  @MaxLength(255, { message: "assignedAgent must not exceed 255 characters" })
+  assignedAgent?: string;
+
   @IsOptional()
   @IsInt({ message: "sortOrder must be an integer" })
   @Min(0, { message: "sortOrder must be at least 0" })

apps/api/src/tasks/dto/update-task.dto.ts

@@ -52,6 +52,12 @@ export class UpdateTaskDto {
   @IsUUID("4", { message: "parentId must be a valid UUID" })
   parentId?: string | null;
 
+  @IsOptional()
+  @IsString({ message: "assignedAgent must be a string" })
+  @MinLength(1, { message: "assignedAgent must not be empty" })
+  @MaxLength(255, { message: "assignedAgent must not exceed 255 characters" })
+  assignedAgent?: string | null;
+
   @IsOptional()
   @IsInt({ message: "sortOrder must be an integer" })
   @Min(0, { message: "sortOrder must be at least 0" })

apps/api/src/tasks/tasks.assigned-agent.integration.spec.ts

@@ -0,0 +1,162 @@
+import { beforeAll, beforeEach, describe, expect, it, afterAll, vi } from "vitest";
+import { randomUUID as uuid } from "crypto";
+import { Test, TestingModule } from "@nestjs/testing";
+import { PrismaClient } from "@prisma/client";
+import { TasksService } from "./tasks.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { ActivityService } from "../activity/activity.service";
+
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
+
+describeFn("TasksService assignedAgent Integration", () => {
+  let moduleRef: TestingModule;
+  let prisma: PrismaClient;
+  let service: TasksService;
+  let workspaceId: string;
+  let ownerId: string;
+  let setupComplete = false;
+
+  const activityServiceMock = {
+    logTaskCreated: vi.fn().mockResolvedValue(undefined),
+    logTaskUpdated: vi.fn().mockResolvedValue(undefined),
+    logTaskDeleted: vi.fn().mockResolvedValue(undefined),
+    logTaskCompleted: vi.fn().mockResolvedValue(undefined),
+    logTaskAssigned: vi.fn().mockResolvedValue(undefined),
+  };
+
+  beforeAll(async () => {
+    prisma = new PrismaClient();
+    await prisma.$connect();
+
+    const workspace = await prisma.workspace.create({
+      data: {
+        name: `Tasks Assigned Agent Integration ${Date.now()}`,
+        owner: {
+          create: {
+            email: `tasks-assigned-agent-integration-${Date.now()}@example.com`,
+            name: "Tasks Assigned Agent Integration Owner",
+          },
+        },
+      },
+    });
+
+    workspaceId = workspace.id;
+    ownerId = workspace.ownerId;
+
+    moduleRef = await Test.createTestingModule({
+      providers: [
+        TasksService,
+        {
+          provide: PrismaService,
+          useValue: prisma,
+        },
+        {
+          provide: ActivityService,
+          useValue: activityServiceMock,
+        },
+      ],
+    }).compile();
+
+    service = moduleRef.get<TasksService>(TasksService);
+    setupComplete = true;
+  });
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    if (!setupComplete) {
+      return;
+    }
+
+    await prisma.task.deleteMany({ where: { workspaceId } });
+  });
+
+  afterAll(async () => {
+    if (!prisma) {
+      return;
+    }
+
+    if (workspaceId) {
+      await prisma.task.deleteMany({ where: { workspaceId } });
+      await prisma.workspace.deleteMany({ where: { id: workspaceId } });
+    }
+    if (ownerId) {
+      await prisma.user.deleteMany({ where: { id: ownerId } });
+    }
+
+    if (moduleRef) {
+      await moduleRef.close();
+    }
+    await prisma.$disconnect();
+  });
+
+  it("persists assignedAgent on create", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const task = await service.create(workspaceId, ownerId, {
+      title: `Assigned agent create ${uuid()}`,
+      assignedAgent: "fleet-worker-1",
+    });
+
+    expect(task.assignedAgent).toBe("fleet-worker-1");
+
+    const stored = await prisma.task.findUnique({
+      where: {
+        id: task.id,
+      },
+      select: {
+        id: true,
+        assignedAgent: true,
+      },
+    });
+
+    expect(stored).toMatchObject({
+      id: task.id,
+      assignedAgent: "fleet-worker-1",
+    });
+
+    const listed = await service.findAll({ workspaceId, page: 1, limit: 10 }, ownerId);
+    const listedTask = listed.data.find((row) => row.id === task.id);
+
+    expect(listedTask?.assignedAgent).toBe("fleet-worker-1");
+  });
+
+  it("updates and clears assignedAgent", async () => {
+    if (!setupComplete) {
+      return;
+    }
+
+    const created = await service.create(workspaceId, ownerId, {
+      title: `Assigned agent update ${uuid()}`,
+    });
+
+    expect(created.assignedAgent).toBeNull();
+
+    const updated = await service.update(created.id, workspaceId, ownerId, {
+      assignedAgent: "fleet-worker-2",
+    });
+
+    expect(updated.assignedAgent).toBe("fleet-worker-2");
+
+    const cleared = await service.update(created.id, workspaceId, ownerId, {
+      assignedAgent: null,
+    });
+
+    expect(cleared.assignedAgent).toBeNull();
+
+    const stored = await prisma.task.findUnique({
+      where: {
+        id: created.id,
+      },
+      select: {
+        assignedAgent: true,
+      },
+    });
+
+    expect(stored?.assignedAgent).toBeNull();
+  });
+});

apps/api/src/tasks/tasks.service.spec.ts

@@ -48,6 +48,7 @@ describe("TasksService", () => {
     creatorId: mockUserId,
     projectId: null,
     parentId: null,
+    assignedAgent: null,
     sortOrder: 0,
     metadata: {},
     createdAt: new Date(),
@@ -158,6 +159,28 @@ describe("TasksService", () => {
         })
       );
     });
+
+    it("should include assignedAgent when provided", async () => {
+      const createDto = {
+        title: "Agent-owned Task",
+        assignedAgent: "fleet-worker-1",
+      };
+
+      mockPrismaService.task.create.mockResolvedValue({
+        ...mockTask,
+        assignedAgent: createDto.assignedAgent,
+      });
+
+      await service.create(mockWorkspaceId, mockUserId, createDto);
+
+      expect(prisma.task.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            assignedAgent: createDto.assignedAgent,
+          }),
+        })
+      );
+    });
   });
 
   describe("findAll", () => {
@@ -469,6 +492,26 @@ describe("TasksService", () => {
         service.update(mockTaskId, mockWorkspaceId, mockUserId, { title: "Test" })
       ).rejects.toThrow(NotFoundException);
     });
+
+    it("should update assignedAgent when provided", async () => {
+      const updateDto = { assignedAgent: "fleet-worker-2" };
+
+      mockPrismaService.task.findUnique.mockResolvedValue(mockTask);
+      mockPrismaService.task.update.mockResolvedValue({
+        ...mockTask,
+        assignedAgent: updateDto.assignedAgent,
+      });
+
+      await service.update(mockTaskId, mockWorkspaceId, mockUserId, updateDto);
+
+      expect(prisma.task.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            assignedAgent: updateDto.assignedAgent,
+          }),
+        })
+      );
+    });
   });
 
   describe("remove", () => {

apps/api/src/tasks/tasks.service.ts

@@ -67,6 +67,9 @@ export class TasksService {
       metadata: createTaskDto.metadata
         ? (createTaskDto.metadata as unknown as Prisma.InputJsonValue)
         : {},
+      ...(createTaskDto.assignedAgent !== undefined && {
+        assignedAgent: createTaskDto.assignedAgent,
+      }),
       ...(assigneeConnection && { assignee: assigneeConnection }),
       ...(projectConnection && { project: projectConnection }),
       ...(parentConnection && { parent: parentConnection }),
@@ -291,6 +294,9 @@ export class TasksService {
         if (updateTaskDto.parentId !== undefined && updateTaskDto.parentId !== null) {
           data.parent = { connect: { id: updateTaskDto.parentId } };
         }
+        if (updateTaskDto.assignedAgent !== undefined) {
+          data.assignedAgent = updateTaskDto.assignedAgent;
+        }
 
         // Handle completedAt based on status changes
         if (updateTaskDto.status) {

apps/api/src/teams/dto/create-team.dto.ts

@@ -0,0 +1,13 @@
+import { IsOptional, IsString, MaxLength, MinLength } from "class-validator";
+
+export class CreateTeamDto {
+  @IsString({ message: "name must be a string" })
+  @MinLength(1, { message: "name must not be empty" })
+  @MaxLength(255, { message: "name must not exceed 255 characters" })
+  name!: string;
+
+  @IsOptional()
+  @IsString({ message: "description must be a string" })
+  @MaxLength(10000, { message: "description must not exceed 10000 characters" })
+  description?: string;
+}

apps/api/src/teams/dto/manage-team-member.dto.ts

@@ -0,0 +1,11 @@
+import { TeamMemberRole } from "@prisma/client";
+import { IsEnum, IsOptional, IsUUID } from "class-validator";
+
+export class ManageTeamMemberDto {
+  @IsUUID("4", { message: "userId must be a valid UUID" })
+  userId!: string;
+
+  @IsOptional()
+  @IsEnum(TeamMemberRole, { message: "role must be a valid TeamMemberRole" })
+  role?: TeamMemberRole;
+}

apps/api/src/teams/teams.controller.spec.ts

@@ -0,0 +1,150 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { TeamMemberRole } from "@prisma/client";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { PermissionGuard, WorkspaceGuard } from "../common/guards";
+import { TeamsController } from "./teams.controller";
+import { TeamsService } from "./teams.service";
+
+describe("TeamsController", () => {
+  let controller: TeamsController;
+  let service: TeamsService;
+
+  const mockTeamsService = {
+    create: vi.fn(),
+    findAll: vi.fn(),
+    addMember: vi.fn(),
+    removeMember: vi.fn(),
+    remove: vi.fn(),
+  };
+
+  const mockWorkspaceId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockTeamId = "550e8400-e29b-41d4-a716-446655440002";
+  const mockUserId = "550e8400-e29b-41d4-a716-446655440003";
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [TeamsController],
+      providers: [
+        {
+          provide: TeamsService,
+          useValue: mockTeamsService,
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: vi.fn(() => true) })
+      .overrideGuard(WorkspaceGuard)
+      .useValue({ canActivate: vi.fn(() => true) })
+      .overrideGuard(PermissionGuard)
+      .useValue({ canActivate: vi.fn(() => true) })
+      .compile();
+
+    controller = module.get<TeamsController>(TeamsController);
+    service = module.get<TeamsService>(TeamsService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(controller).toBeDefined();
+  });
+
+  describe("create", () => {
+    it("should create a team in a workspace", async () => {
+      const createDto = {
+        name: "Platform Team",
+        description: "Owns platform services",
+      };
+
+      const createdTeam = {
+        id: mockTeamId,
+        workspaceId: mockWorkspaceId,
+        name: createDto.name,
+        description: createDto.description,
+        metadata: {},
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockTeamsService.create.mockResolvedValue(createdTeam);
+
+      const result = await controller.create(createDto, mockWorkspaceId);
+
+      expect(result).toEqual(createdTeam);
+      expect(service.create).toHaveBeenCalledWith(mockWorkspaceId, createDto);
+    });
+  });
+
+  describe("findAll", () => {
+    it("should list teams in a workspace", async () => {
+      const teams = [
+        {
+          id: mockTeamId,
+          workspaceId: mockWorkspaceId,
+          name: "Platform Team",
+          description: "Owns platform services",
+          metadata: {},
+          createdAt: new Date(),
+          updatedAt: new Date(),
+          _count: { members: 2 },
+        },
+      ];
+
+      mockTeamsService.findAll.mockResolvedValue(teams);
+
+      const result = await controller.findAll(mockWorkspaceId);
+
+      expect(result).toEqual(teams);
+      expect(service.findAll).toHaveBeenCalledWith(mockWorkspaceId);
+    });
+  });
+
+  describe("addMember", () => {
+    it("should add a member to a team", async () => {
+      const dto = {
+        userId: mockUserId,
+        role: TeamMemberRole.ADMIN,
+      };
+
+      const createdTeamMember = {
+        teamId: mockTeamId,
+        userId: mockUserId,
+        role: TeamMemberRole.ADMIN,
+        joinedAt: new Date(),
+        user: {
+          id: mockUserId,
+          name: "Test User",
+          email: "test@example.com",
+        },
+      };
+
+      mockTeamsService.addMember.mockResolvedValue(createdTeamMember);
+
+      const result = await controller.addMember(mockTeamId, dto, mockWorkspaceId);
+
+      expect(result).toEqual(createdTeamMember);
+      expect(service.addMember).toHaveBeenCalledWith(mockWorkspaceId, mockTeamId, dto);
+    });
+  });
+
+  describe("removeMember", () => {
+    it("should remove a member from a team", async () => {
+      mockTeamsService.removeMember.mockResolvedValue(undefined);
+
+      await controller.removeMember(mockTeamId, mockUserId, mockWorkspaceId);
+
+      expect(service.removeMember).toHaveBeenCalledWith(mockWorkspaceId, mockTeamId, mockUserId);
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a team", async () => {
+      mockTeamsService.remove.mockResolvedValue(undefined);
+
+      await controller.remove(mockTeamId, mockWorkspaceId);
+
+      expect(service.remove).toHaveBeenCalledWith(mockWorkspaceId, mockTeamId);
+    });
+  });
+});

apps/api/src/teams/teams.controller.ts

@@ -0,0 +1,51 @@
+import { Body, Controller, Delete, Get, Param, Post, UseGuards } from "@nestjs/common";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { PermissionGuard, WorkspaceGuard } from "../common/guards";
+import { Permission, RequirePermission, Workspace } from "../common/decorators";
+import { CreateTeamDto } from "./dto/create-team.dto";
+import { ManageTeamMemberDto } from "./dto/manage-team-member.dto";
+import { TeamsService } from "./teams.service";
+
+@Controller("workspaces/:workspaceId/teams")
+@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
+export class TeamsController {
+  constructor(private readonly teamsService: TeamsService) {}
+
+  @Post()
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async create(@Body() createTeamDto: CreateTeamDto, @Workspace() workspaceId: string) {
+    return this.teamsService.create(workspaceId, createTeamDto);
+  }
+
+  @Get()
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async findAll(@Workspace() workspaceId: string) {
+    return this.teamsService.findAll(workspaceId);
+  }
+
+  @Post(":teamId/members")
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async addMember(
+    @Param("teamId") teamId: string,
+    @Body() dto: ManageTeamMemberDto,
+    @Workspace() workspaceId: string
+  ) {
+    return this.teamsService.addMember(workspaceId, teamId, dto);
+  }
+
+  @Delete(":teamId/members/:userId")
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async removeMember(
+    @Param("teamId") teamId: string,
+    @Param("userId") userId: string,
+    @Workspace() workspaceId: string
+  ) {
+    return this.teamsService.removeMember(workspaceId, teamId, userId);
+  }
+
+  @Delete(":teamId")
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async remove(@Param("teamId") teamId: string, @Workspace() workspaceId: string) {
+    return this.teamsService.remove(workspaceId, teamId);
+  }
+}

apps/api/src/teams/teams.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { PrismaModule } from "../prisma/prisma.module";
+import { TeamsController } from "./teams.controller";
+import { TeamsService } from "./teams.service";
+
+@Module({
+  imports: [PrismaModule, AuthModule],
+  controllers: [TeamsController],
+  providers: [TeamsService],
+  exports: [TeamsService],
+})
+export class TeamsModule {}

apps/api/src/teams/teams.service.spec.ts

@@ -0,0 +1,286 @@
+import { BadRequestException, ConflictException, NotFoundException } from "@nestjs/common";
+import { Test, TestingModule } from "@nestjs/testing";
+import { TeamMemberRole } from "@prisma/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PrismaService } from "../prisma/prisma.service";
+import { TeamsService } from "./teams.service";
+
+describe("TeamsService", () => {
+  let service: TeamsService;
+  let prisma: PrismaService;
+
+  const mockPrismaService = {
+    team: {
+      create: vi.fn(),
+      findMany: vi.fn(),
+      findFirst: vi.fn(),
+      deleteMany: vi.fn(),
+    },
+    workspaceMember: {
+      findUnique: vi.fn(),
+    },
+    teamMember: {
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      deleteMany: vi.fn(),
+    },
+  };
+
+  const mockWorkspaceId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockTeamId = "550e8400-e29b-41d4-a716-446655440002";
+  const mockUserId = "550e8400-e29b-41d4-a716-446655440003";
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        TeamsService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<TeamsService>(TeamsService);
+    prisma = module.get<PrismaService>(PrismaService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(service).toBeDefined();
+  });
+
+  describe("create", () => {
+    it("should create a team", async () => {
+      const createDto = {
+        name: "Platform Team",
+        description: "Owns platform services",
+      };
+
+      const createdTeam = {
+        id: mockTeamId,
+        workspaceId: mockWorkspaceId,
+        name: createDto.name,
+        description: createDto.description,
+        metadata: {},
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockPrismaService.team.create.mockResolvedValue(createdTeam);
+
+      const result = await service.create(mockWorkspaceId, createDto);
+
+      expect(result).toEqual(createdTeam);
+      expect(prisma.team.create).toHaveBeenCalledWith({
+        data: {
+          workspaceId: mockWorkspaceId,
+          name: createDto.name,
+          description: createDto.description,
+        },
+      });
+    });
+  });
+
+  describe("findAll", () => {
+    it("should list teams for a workspace", async () => {
+      const teams = [
+        {
+          id: mockTeamId,
+          workspaceId: mockWorkspaceId,
+          name: "Platform Team",
+          description: "Owns platform services",
+          metadata: {},
+          createdAt: new Date(),
+          updatedAt: new Date(),
+          _count: { members: 1 },
+        },
+      ];
+
+      mockPrismaService.team.findMany.mockResolvedValue(teams);
+
+      const result = await service.findAll(mockWorkspaceId);
+
+      expect(result).toEqual(teams);
+      expect(prisma.team.findMany).toHaveBeenCalledWith({
+        where: { workspaceId: mockWorkspaceId },
+        include: {
+          _count: {
+            select: { members: true },
+          },
+        },
+        orderBy: { createdAt: "asc" },
+      });
+    });
+  });
+
+  describe("addMember", () => {
+    it("should add a workspace member to a team", async () => {
+      const dto = {
+        userId: mockUserId,
+        role: TeamMemberRole.ADMIN,
+      };
+
+      const createdTeamMember = {
+        teamId: mockTeamId,
+        userId: mockUserId,
+        role: TeamMemberRole.ADMIN,
+        joinedAt: new Date(),
+        user: {
+          id: mockUserId,
+          name: "Test User",
+          email: "test@example.com",
+        },
+      };
+
+      mockPrismaService.team.findFirst.mockResolvedValue({ id: mockTeamId });
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValue({ userId: mockUserId });
+      mockPrismaService.teamMember.findUnique.mockResolvedValue(null);
+      mockPrismaService.teamMember.create.mockResolvedValue(createdTeamMember);
+
+      const result = await service.addMember(mockWorkspaceId, mockTeamId, dto);
+
+      expect(result).toEqual(createdTeamMember);
+      expect(prisma.team.findFirst).toHaveBeenCalledWith({
+        where: {
+          id: mockTeamId,
+          workspaceId: mockWorkspaceId,
+        },
+        select: { id: true },
+      });
+      expect(prisma.workspaceMember.findUnique).toHaveBeenCalledWith({
+        where: {
+          workspaceId_userId: {
+            workspaceId: mockWorkspaceId,
+            userId: mockUserId,
+          },
+        },
+        select: { userId: true },
+      });
+      expect(prisma.teamMember.create).toHaveBeenCalledWith({
+        data: {
+          teamId: mockTeamId,
+          userId: mockUserId,
+          role: TeamMemberRole.ADMIN,
+        },
+        include: {
+          user: {
+            select: {
+              id: true,
+              name: true,
+              email: true,
+            },
+          },
+        },
+      });
+    });
+
+    it("should use MEMBER role when role is omitted", async () => {
+      const dto = { userId: mockUserId };
+
+      mockPrismaService.team.findFirst.mockResolvedValue({ id: mockTeamId });
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValue({ userId: mockUserId });
+      mockPrismaService.teamMember.findUnique.mockResolvedValue(null);
+      mockPrismaService.teamMember.create.mockResolvedValue({
+        teamId: mockTeamId,
+        userId: mockUserId,
+        role: TeamMemberRole.MEMBER,
+        joinedAt: new Date(),
+      });
+
+      await service.addMember(mockWorkspaceId, mockTeamId, dto);
+
+      expect(prisma.teamMember.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            role: TeamMemberRole.MEMBER,
+          }),
+        })
+      );
+    });
+
+    it("should throw when team does not belong to workspace", async () => {
+      mockPrismaService.team.findFirst.mockResolvedValue(null);
+
+      await expect(
+        service.addMember(mockWorkspaceId, mockTeamId, { userId: mockUserId })
+      ).rejects.toThrow(NotFoundException);
+      expect(prisma.workspaceMember.findUnique).not.toHaveBeenCalled();
+    });
+
+    it("should throw when user is not a workspace member", async () => {
+      mockPrismaService.team.findFirst.mockResolvedValue({ id: mockTeamId });
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValue(null);
+
+      await expect(
+        service.addMember(mockWorkspaceId, mockTeamId, { userId: mockUserId })
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it("should throw when user is already in the team", async () => {
+      mockPrismaService.team.findFirst.mockResolvedValue({ id: mockTeamId });
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValue({ userId: mockUserId });
+      mockPrismaService.teamMember.findUnique.mockResolvedValue({ userId: mockUserId });
+
+      await expect(
+        service.addMember(mockWorkspaceId, mockTeamId, { userId: mockUserId })
+      ).rejects.toThrow(ConflictException);
+    });
+  });
+
+  describe("removeMember", () => {
+    it("should remove a member from a team", async () => {
+      mockPrismaService.team.findFirst.mockResolvedValue({ id: mockTeamId });
+      mockPrismaService.teamMember.deleteMany.mockResolvedValue({ count: 1 });
+
+      await service.removeMember(mockWorkspaceId, mockTeamId, mockUserId);
+
+      expect(prisma.teamMember.deleteMany).toHaveBeenCalledWith({
+        where: {
+          teamId: mockTeamId,
+          userId: mockUserId,
+        },
+      });
+    });
+
+    it("should throw when team does not belong to workspace", async () => {
+      mockPrismaService.team.findFirst.mockResolvedValue(null);
+
+      await expect(service.removeMember(mockWorkspaceId, mockTeamId, mockUserId)).rejects.toThrow(
+        NotFoundException
+      );
+      expect(prisma.teamMember.deleteMany).not.toHaveBeenCalled();
+    });
+
+    it("should throw when user is not in the team", async () => {
+      mockPrismaService.team.findFirst.mockResolvedValue({ id: mockTeamId });
+      mockPrismaService.teamMember.deleteMany.mockResolvedValue({ count: 0 });
+
+      await expect(service.removeMember(mockWorkspaceId, mockTeamId, mockUserId)).rejects.toThrow(
+        NotFoundException
+      );
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a team", async () => {
+      mockPrismaService.team.deleteMany.mockResolvedValue({ count: 1 });
+
+      await service.remove(mockWorkspaceId, mockTeamId);
+
+      expect(prisma.team.deleteMany).toHaveBeenCalledWith({
+        where: {
+          id: mockTeamId,
+          workspaceId: mockWorkspaceId,
+        },
+      });
+    });
+
+    it("should throw when team is not found", async () => {
+      mockPrismaService.team.deleteMany.mockResolvedValue({ count: 0 });
+
+      await expect(service.remove(mockWorkspaceId, mockTeamId)).rejects.toThrow(NotFoundException);
+    });
+  });
+});

apps/api/src/teams/teams.service.ts

@@ -0,0 +1,130 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
+import { TeamMemberRole } from "@prisma/client";
+import { PrismaService } from "../prisma/prisma.service";
+import { CreateTeamDto } from "./dto/create-team.dto";
+import { ManageTeamMemberDto } from "./dto/manage-team-member.dto";
+
+@Injectable()
+export class TeamsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async create(workspaceId: string, createTeamDto: CreateTeamDto) {
+    return this.prisma.team.create({
+      data: {
+        workspaceId,
+        name: createTeamDto.name,
+        description: createTeamDto.description ?? null,
+      },
+    });
+  }
+
+  async findAll(workspaceId: string) {
+    return this.prisma.team.findMany({
+      where: { workspaceId },
+      include: {
+        _count: {
+          select: { members: true },
+        },
+      },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  async addMember(workspaceId: string, teamId: string, dto: ManageTeamMemberDto) {
+    await this.ensureTeamInWorkspace(workspaceId, teamId);
+
+    const workspaceMember = await this.prisma.workspaceMember.findUnique({
+      where: {
+        workspaceId_userId: {
+          workspaceId,
+          userId: dto.userId,
+        },
+      },
+      select: { userId: true },
+    });
+
+    if (!workspaceMember) {
+      throw new BadRequestException(
+        `User ${dto.userId} must be a workspace member before being added to a team`
+      );
+    }
+
+    const existingTeamMember = await this.prisma.teamMember.findUnique({
+      where: {
+        teamId_userId: {
+          teamId,
+          userId: dto.userId,
+        },
+      },
+      select: { userId: true },
+    });
+
+    if (existingTeamMember) {
+      throw new ConflictException(`User ${dto.userId} is already a member of team ${teamId}`);
+    }
+
+    return this.prisma.teamMember.create({
+      data: {
+        teamId,
+        userId: dto.userId,
+        role: dto.role ?? TeamMemberRole.MEMBER,
+      },
+      include: {
+        user: {
+          select: {
+            id: true,
+            name: true,
+            email: true,
+          },
+        },
+      },
+    });
+  }
+
+  async removeMember(workspaceId: string, teamId: string, userId: string): Promise<void> {
+    await this.ensureTeamInWorkspace(workspaceId, teamId);
+
+    const result = await this.prisma.teamMember.deleteMany({
+      where: {
+        teamId,
+        userId,
+      },
+    });
+
+    if (result.count === 0) {
+      throw new NotFoundException(`User ${userId} is not a member of team ${teamId}`);
+    }
+  }
+
+  async remove(workspaceId: string, teamId: string): Promise<void> {
+    const result = await this.prisma.team.deleteMany({
+      where: {
+        id: teamId,
+        workspaceId,
+      },
+    });
+
+    if (result.count === 0) {
+      throw new NotFoundException(`Team with ID ${teamId} not found`);
+    }
+  }
+
+  private async ensureTeamInWorkspace(workspaceId: string, teamId: string): Promise<void> {
+    const team = await this.prisma.team.findFirst({
+      where: {
+        id: teamId,
+        workspaceId,
+      },
+      select: { id: true },
+    });
+
+    if (!team) {
+      throw new NotFoundException(`Team with ID ${teamId} not found`);
+    }
+  }
+}

apps/api/src/workspaces/dto/add-member.dto.ts

@@ -0,0 +1,13 @@
+import { WorkspaceMemberRole } from "@prisma/client";
+import { IsEnum, IsUUID } from "class-validator";
+
+/**
+ * DTO for adding a user to a workspace.
+ */
+export class AddMemberDto {
+  @IsUUID("4", { message: "userId must be a valid UUID" })
+  userId!: string;
+
+  @IsEnum(WorkspaceMemberRole, { message: "role must be a valid WorkspaceMemberRole" })
+  role!: WorkspaceMemberRole;
+}

apps/api/src/workspaces/dto/index.ts

@@ -0,0 +1,3 @@
+export { AddMemberDto } from "./add-member.dto";
+export { UpdateMemberRoleDto } from "./update-member-role.dto";
+export { WorkspaceResponseDto } from "./workspace-response.dto";

apps/api/src/workspaces/dto/update-member-role.dto.ts

@@ -0,0 +1,10 @@
+import { WorkspaceMemberRole } from "@prisma/client";
+import { IsEnum } from "class-validator";
+
+/**
+ * DTO for updating a workspace member's role.
+ */
+export class UpdateMemberRoleDto {
+  @IsEnum(WorkspaceMemberRole, { message: "role must be a valid WorkspaceMemberRole" })
+  role!: WorkspaceMemberRole;
+}

apps/api/src/workspaces/dto/workspace-response.dto.ts

@@ -0,0 +1,12 @@
+import type { WorkspaceMemberRole } from "@prisma/client";
+
+/**
+ * Response DTO for a workspace the authenticated user belongs to.
+ */
+export class WorkspaceResponseDto {
+  id!: string;
+  name!: string;
+  ownerId!: string;
+  role!: WorkspaceMemberRole;
+  createdAt!: Date;
+}

apps/api/src/workspaces/index.ts

@@ -0,0 +1,3 @@
+export { WorkspacesModule } from "./workspaces.module";
+export { WorkspacesService } from "./workspaces.service";
+export { WorkspacesController } from "./workspaces.controller";

apps/api/src/workspaces/workspaces.controller.spec.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { WorkspacesController } from "./workspaces.controller";
+import { WorkspacesService } from "./workspaces.service";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { WorkspaceMemberRole } from "@prisma/client";
+import type { AuthUser } from "@mosaic/shared";
+
+describe("WorkspacesController", () => {
+  let controller: WorkspacesController;
+  let service: WorkspacesService;
+
+  const mockWorkspacesService = {
+    getUserWorkspaces: vi.fn(),
+    addMember: vi.fn(),
+    updateMemberRole: vi.fn(),
+    removeMember: vi.fn(),
+  };
+
+  const mockUser: AuthUser = {
+    id: "user-1",
+    email: "test@example.com",
+    name: "Test User",
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [WorkspacesController],
+      providers: [
+        {
+          provide: WorkspacesService,
+          useValue: mockWorkspacesService,
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true })
+      .overrideGuard(WorkspaceGuard)
+      .useValue({ canActivate: () => true })
+      .overrideGuard(PermissionGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    controller = module.get<WorkspacesController>(WorkspacesController);
+    service = module.get<WorkspacesService>(WorkspacesService);
+
+    vi.clearAllMocks();
+  });
+
+  describe("GET /api/workspaces", () => {
+    it("should call service with authenticated user id", async () => {
+      mockWorkspacesService.getUserWorkspaces.mockResolvedValueOnce([]);
+
+      await controller.getUserWorkspaces(mockUser);
+
+      expect(service.getUserWorkspaces).toHaveBeenCalledWith("user-1");
+    });
+
+    it("should return workspace list from service", async () => {
+      const mockWorkspaces = [
+        {
+          id: "ws-1",
+          name: "My Workspace",
+          ownerId: "user-1",
+          role: WorkspaceMemberRole.OWNER,
+          createdAt: new Date("2026-01-01"),
+        },
+      ];
+      mockWorkspacesService.getUserWorkspaces.mockResolvedValueOnce(mockWorkspaces);
+
+      const result = await controller.getUserWorkspaces(mockUser);
+
+      expect(result).toEqual(mockWorkspaces);
+    });
+
+    it("should propagate service errors", async () => {
+      mockWorkspacesService.getUserWorkspaces.mockRejectedValueOnce(new Error("Database error"));
+
+      await expect(controller.getUserWorkspaces(mockUser)).rejects.toThrow("Database error");
+    });
+  });
+
+  describe("POST /api/workspaces/:id/members", () => {
+    it("should call service with workspace id, actor id, and add member dto", async () => {
+      const workspaceId = "ws-1";
+      const addMemberDto = {
+        userId: "user-2",
+        role: WorkspaceMemberRole.MEMBER,
+      };
+      const mockMember = {
+        workspaceId,
+        userId: "user-2",
+        role: WorkspaceMemberRole.MEMBER,
+        joinedAt: new Date("2026-02-01"),
+      };
+      mockWorkspacesService.addMember.mockResolvedValueOnce(mockMember);
+
+      const result = await controller.addMember(workspaceId, addMemberDto, mockUser);
+
+      expect(result).toEqual(mockMember);
+      expect(service.addMember).toHaveBeenCalledWith(workspaceId, mockUser.id, addMemberDto);
+    });
+  });
+
+  describe("PATCH /api/workspaces/:id/members/:userId", () => {
+    it("should call service with workspace id, actor id, target user id, and role dto", async () => {
+      const workspaceId = "ws-1";
+      const targetUserId = "user-2";
+      const updateRoleDto = {
+        role: WorkspaceMemberRole.ADMIN,
+      };
+      const mockMember = {
+        workspaceId,
+        userId: targetUserId,
+        role: WorkspaceMemberRole.ADMIN,
+        joinedAt: new Date("2026-02-01"),
+      };
+      mockWorkspacesService.updateMemberRole.mockResolvedValueOnce(mockMember);
+
+      const result = await controller.updateMemberRole(
+        workspaceId,
+        targetUserId,
+        updateRoleDto,
+        mockUser
+      );
+
+      expect(result).toEqual(mockMember);
+      expect(service.updateMemberRole).toHaveBeenCalledWith(
+        workspaceId,
+        mockUser.id,
+        targetUserId,
+        updateRoleDto
+      );
+    });
+  });
+
+  describe("DELETE /api/workspaces/:id/members/:userId", () => {
+    it("should call service with workspace id, actor id, and target user id", async () => {
+      const workspaceId = "ws-1";
+      const targetUserId = "user-2";
+      mockWorkspacesService.removeMember.mockResolvedValueOnce(undefined);
+
+      await controller.removeMember(workspaceId, targetUserId, mockUser);
+
+      expect(service.removeMember).toHaveBeenCalledWith(workspaceId, mockUser.id, targetUserId);
+    });
+  });
+});

apps/api/src/workspaces/workspaces.controller.ts

@@ -0,0 +1,85 @@
+import { Body, Controller, Delete, Get, Param, Patch, Post, UseGuards } from "@nestjs/common";
+import { WorkspacesService } from "./workspaces.service";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { CurrentUser } from "../auth/decorators/current-user.decorator";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { Permission, RequirePermission } from "../common/decorators";
+import type { WorkspaceMember } from "@prisma/client";
+import type { AuthenticatedUser } from "../common/types/user.types";
+import type { AddMemberDto, UpdateMemberRoleDto, WorkspaceResponseDto } from "./dto";
+
+/**
+ * User-scoped workspace operations.
+ *
+ * Intentionally does NOT use WorkspaceGuard — these routes operate across all
+ * workspaces the user belongs to, not within a single workspace context.
+ */
+@Controller("workspaces")
+@UseGuards(AuthGuard)
+export class WorkspacesController {
+  constructor(private readonly workspacesService: WorkspacesService) {}
+
+  /**
+   * GET /api/workspaces
+   * Returns workspaces the authenticated user is a member of.
+   * Auto-provisions a default workspace if the user has none.
+   */
+  @Get()
+  async getUserWorkspaces(@CurrentUser() user: AuthenticatedUser): Promise<WorkspaceResponseDto[]> {
+    return this.workspacesService.getUserWorkspaces(user.id);
+  }
+
+  /**
+   * POST /api/workspaces/:workspaceId/members
+   * Add a member to a workspace with the specified role.
+   * Requires: ADMIN role or higher.
+   */
+  @Post(":workspaceId/members")
+  @UseGuards(WorkspaceGuard, PermissionGuard)
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async addMember(
+    @Param("workspaceId") workspaceId: string,
+    @Body() addMemberDto: AddMemberDto,
+    @CurrentUser() user: AuthenticatedUser
+  ): Promise<WorkspaceMember> {
+    return this.workspacesService.addMember(workspaceId, user.id, addMemberDto);
+  }
+
+  /**
+   * PATCH /api/workspaces/:workspaceId/members/:userId
+   * Change a member role in a workspace.
+   * Requires: ADMIN role or higher.
+   */
+  @Patch(":workspaceId/members/:userId")
+  @UseGuards(WorkspaceGuard, PermissionGuard)
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async updateMemberRole(
+    @Param("workspaceId") workspaceId: string,
+    @Param("userId") targetUserId: string,
+    @Body() updateMemberRoleDto: UpdateMemberRoleDto,
+    @CurrentUser() user: AuthenticatedUser
+  ): Promise<WorkspaceMember> {
+    return this.workspacesService.updateMemberRole(
+      workspaceId,
+      user.id,
+      targetUserId,
+      updateMemberRoleDto
+    );
+  }
+
+  /**
+   * DELETE /api/workspaces/:workspaceId/members/:userId
+   * Remove a member from a workspace.
+   * Requires: ADMIN role or higher.
+   */
+  @Delete(":workspaceId/members/:userId")
+  @UseGuards(WorkspaceGuard, PermissionGuard)
+  @RequirePermission(Permission.WORKSPACE_ADMIN)
+  async removeMember(
+    @Param("workspaceId") workspaceId: string,
+    @Param("userId") targetUserId: string,
+    @CurrentUser() user: AuthenticatedUser
+  ): Promise<void> {
+    await this.workspacesService.removeMember(workspaceId, user.id, targetUserId);
+  }
+}

apps/api/src/workspaces/workspaces.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { WorkspacesController } from "./workspaces.controller";
+import { WorkspacesService } from "./workspaces.service";
+import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
+
+@Module({
+  imports: [PrismaModule, AuthModule],
+  controllers: [WorkspacesController],
+  providers: [WorkspacesService],
+  exports: [WorkspacesService],
+})
+export class WorkspacesModule {}

apps/api/src/workspaces/workspaces.service.spec.ts

@@ -0,0 +1,516 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { WorkspacesService } from "./workspaces.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { WorkspaceMemberRole } from "@prisma/client";
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  NotFoundException,
+} from "@nestjs/common";
+
+describe("WorkspacesService", () => {
+  let service: WorkspacesService;
+
+  const mockUserId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockAdminUserId = "550e8400-e29b-41d4-a716-446655440010";
+  const mockMemberUserId = "550e8400-e29b-41d4-a716-446655440011";
+  const mockWorkspaceId = "550e8400-e29b-41d4-a716-446655440002";
+
+  const mockWorkspace = {
+    id: mockWorkspaceId,
+    name: "Test Workspace",
+    ownerId: mockUserId,
+    settings: {},
+    matrixRoomId: null,
+    createdAt: new Date("2026-01-01"),
+    updatedAt: new Date("2026-01-01"),
+  };
+
+  const mockMembership = {
+    workspaceId: mockWorkspaceId,
+    userId: mockUserId,
+    role: WorkspaceMemberRole.OWNER,
+    joinedAt: new Date("2026-01-01"),
+    workspace: {
+      id: mockWorkspaceId,
+      name: "Test Workspace",
+      ownerId: mockUserId,
+      createdAt: new Date("2026-01-01"),
+    },
+  };
+
+  const mockPrismaService = {
+    workspaceMember: {
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      count: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+    },
+    workspace: {
+      create: vi.fn(),
+    },
+    user: {
+      findUnique: vi.fn(),
+    },
+    $transaction: vi.fn(),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        WorkspacesService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<WorkspacesService>(WorkspacesService);
+
+    vi.clearAllMocks();
+
+    mockPrismaService.$transaction.mockImplementation(
+      async (fn: (tx: typeof mockPrismaService) => Promise<unknown>) =>
+        fn(mockPrismaService as unknown as typeof mockPrismaService)
+    );
+  });
+
+  describe("getUserWorkspaces", () => {
+    it("should return all workspaces user is a member of", async () => {
+      mockPrismaService.workspaceMember.findMany.mockResolvedValueOnce([mockMembership]);
+
+      const result = await service.getUserWorkspaces(mockUserId);
+
+      expect(result).toEqual([
+        {
+          id: mockWorkspaceId,
+          name: "Test Workspace",
+          ownerId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          createdAt: mockMembership.workspace.createdAt,
+        },
+      ]);
+      expect(mockPrismaService.workspaceMember.findMany).toHaveBeenCalledWith({
+        where: { userId: mockUserId },
+        include: {
+          workspace: {
+            select: { id: true, name: true, ownerId: true, createdAt: true },
+          },
+        },
+        orderBy: { joinedAt: "asc" },
+      });
+    });
+
+    it("should return multiple workspaces ordered by joinedAt", async () => {
+      const secondWorkspace = {
+        ...mockMembership,
+        workspaceId: "ws-2",
+        role: WorkspaceMemberRole.MEMBER,
+        joinedAt: new Date("2026-02-01"),
+        workspace: {
+          id: "ws-2",
+          name: "Second Workspace",
+          ownerId: "other-user",
+          createdAt: new Date("2026-02-01"),
+        },
+      };
+
+      mockPrismaService.workspaceMember.findMany.mockResolvedValueOnce([
+        mockMembership,
+        secondWorkspace,
+      ]);
+
+      const result = await service.getUserWorkspaces(mockUserId);
+
+      expect(result).toHaveLength(2);
+      expect(result[0].id).toBe(mockWorkspaceId);
+      expect(result[1].id).toBe("ws-2");
+      expect(result[1].role).toBe(WorkspaceMemberRole.MEMBER);
+    });
+
+    it("should auto-provision a default workspace when user has no memberships", async () => {
+      mockPrismaService.workspaceMember.findMany.mockResolvedValueOnce([]);
+      mockPrismaService.$transaction.mockImplementationOnce(
+        async (fn: (tx: typeof mockPrismaService) => Promise<unknown>) => {
+          const txMock = {
+            workspaceMember: {
+              findFirst: vi.fn().mockResolvedValueOnce(null),
+              create: vi.fn().mockResolvedValueOnce({}),
+            },
+            workspace: {
+              create: vi.fn().mockResolvedValueOnce(mockWorkspace),
+            },
+          };
+          return fn(txMock as unknown as typeof mockPrismaService);
+        }
+      );
+
+      const result = await service.getUserWorkspaces(mockUserId);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe("Test Workspace");
+      expect(result[0].role).toBe(WorkspaceMemberRole.OWNER);
+      expect(mockPrismaService.$transaction).toHaveBeenCalledTimes(1);
+    });
+
+    it("should return existing workspace if one was created between initial check and transaction", async () => {
+      // Simulates a race condition: initial findMany returns [], but inside the
+      // transaction another request already created a workspace.
+      mockPrismaService.workspaceMember.findMany.mockResolvedValueOnce([]);
+      mockPrismaService.$transaction.mockImplementationOnce(
+        async (fn: (tx: typeof mockPrismaService) => Promise<unknown>) => {
+          const txMock = {
+            workspaceMember: {
+              findFirst: vi.fn().mockResolvedValueOnce(mockMembership),
+            },
+            workspace: {
+              create: vi.fn(),
+            },
+          };
+          return fn(txMock as unknown as typeof mockPrismaService);
+        }
+      );
+
+      const result = await service.getUserWorkspaces(mockUserId);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].id).toBe(mockWorkspaceId);
+      expect(result[0].name).toBe("Test Workspace");
+    });
+
+    it("should create workspace with correct data during auto-provisioning", async () => {
+      mockPrismaService.workspaceMember.findMany.mockResolvedValueOnce([]);
+
+      let capturedWorkspaceData: unknown;
+      let capturedMemberData: unknown;
+
+      mockPrismaService.$transaction.mockImplementationOnce(
+        async (fn: (tx: typeof mockPrismaService) => Promise<unknown>) => {
+          const txMock = {
+            workspaceMember: {
+              findFirst: vi.fn().mockResolvedValueOnce(null),
+              create: vi.fn().mockImplementation((args: unknown) => {
+                capturedMemberData = args;
+                return {};
+              }),
+            },
+            workspace: {
+              create: vi.fn().mockImplementation((args: unknown) => {
+                capturedWorkspaceData = args;
+                return mockWorkspace;
+              }),
+            },
+          };
+          return fn(txMock as unknown as typeof mockPrismaService);
+        }
+      );
+
+      await service.getUserWorkspaces(mockUserId);
+
+      expect(capturedWorkspaceData).toEqual({
+        data: {
+          name: "My Workspace",
+          ownerId: mockUserId,
+          settings: {},
+        },
+      });
+      expect(capturedMemberData).toEqual({
+        data: {
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+        },
+      });
+    });
+
+    it("should not auto-provision when user already has workspaces", async () => {
+      mockPrismaService.workspaceMember.findMany.mockResolvedValueOnce([mockMembership]);
+
+      await service.getUserWorkspaces(mockUserId);
+
+      expect(mockPrismaService.$transaction).not.toHaveBeenCalled();
+    });
+
+    it("should propagate database errors", async () => {
+      mockPrismaService.workspaceMember.findMany.mockRejectedValueOnce(
+        new Error("Database connection failed")
+      );
+
+      await expect(service.getUserWorkspaces(mockUserId)).rejects.toThrow(
+        "Database connection failed"
+      );
+    });
+  });
+
+  describe("addMember", () => {
+    const addMemberDto = {
+      userId: mockMemberUserId,
+      role: WorkspaceMemberRole.MEMBER,
+    };
+
+    it("should add a new member to the workspace", async () => {
+      const createdMembership = {
+        workspaceId: mockWorkspaceId,
+        userId: mockMemberUserId,
+        role: WorkspaceMemberRole.MEMBER,
+        joinedAt: new Date("2026-02-02"),
+      };
+      mockPrismaService.user.findUnique.mockResolvedValueOnce({ id: mockMemberUserId });
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockAdminUserId,
+          role: WorkspaceMemberRole.ADMIN,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce(null);
+      mockPrismaService.workspaceMember.create.mockResolvedValueOnce(createdMembership);
+
+      const result = await service.addMember(mockWorkspaceId, mockAdminUserId, addMemberDto);
+
+      expect(result).toEqual(createdMembership);
+      expect(mockPrismaService.workspaceMember.create).toHaveBeenCalledWith({
+        data: {
+          workspaceId: mockWorkspaceId,
+          userId: mockMemberUserId,
+          role: WorkspaceMemberRole.MEMBER,
+        },
+      });
+    });
+
+    it("should throw NotFoundException when user does not exist", async () => {
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValueOnce({
+        workspaceId: mockWorkspaceId,
+        userId: mockAdminUserId,
+        role: WorkspaceMemberRole.ADMIN,
+        joinedAt: new Date("2026-01-01"),
+      });
+      mockPrismaService.user.findUnique.mockResolvedValueOnce(null);
+
+      await expect(
+        service.addMember(mockWorkspaceId, mockAdminUserId, addMemberDto)
+      ).rejects.toThrow(NotFoundException);
+    });
+
+    it("should throw ConflictException when user is already a member", async () => {
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValueOnce({
+        workspaceId: mockWorkspaceId,
+        userId: mockAdminUserId,
+        role: WorkspaceMemberRole.ADMIN,
+        joinedAt: new Date("2026-01-01"),
+      });
+      mockPrismaService.user.findUnique.mockResolvedValueOnce({ id: mockMemberUserId });
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValueOnce({
+        workspaceId: mockWorkspaceId,
+        userId: mockMemberUserId,
+        role: WorkspaceMemberRole.MEMBER,
+        joinedAt: new Date("2026-01-02"),
+      });
+
+      await expect(
+        service.addMember(mockWorkspaceId, mockAdminUserId, addMemberDto)
+      ).rejects.toThrow(ConflictException);
+    });
+
+    it("should throw ForbiddenException when admin tries to assign OWNER role", async () => {
+      mockPrismaService.workspaceMember.findUnique.mockResolvedValueOnce({
+        workspaceId: mockWorkspaceId,
+        userId: mockAdminUserId,
+        role: WorkspaceMemberRole.ADMIN,
+        joinedAt: new Date("2026-01-01"),
+      });
+
+      await expect(
+        service.addMember(mockWorkspaceId, mockAdminUserId, {
+          userId: mockMemberUserId,
+          role: WorkspaceMemberRole.OWNER,
+        })
+      ).rejects.toThrow(ForbiddenException);
+    });
+  });
+
+  describe("updateMemberRole", () => {
+    it("should update a member role", async () => {
+      const updatedMembership = {
+        workspaceId: mockWorkspaceId,
+        userId: mockMemberUserId,
+        role: WorkspaceMemberRole.ADMIN,
+        joinedAt: new Date("2026-01-02"),
+      };
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockMemberUserId,
+          role: WorkspaceMemberRole.MEMBER,
+          joinedAt: new Date("2026-01-02"),
+        });
+      mockPrismaService.workspaceMember.update.mockResolvedValueOnce(updatedMembership);
+
+      const result = await service.updateMemberRole(mockWorkspaceId, mockUserId, mockMemberUserId, {
+        role: WorkspaceMemberRole.ADMIN,
+      });
+
+      expect(result).toEqual(updatedMembership);
+      expect(mockPrismaService.workspaceMember.update).toHaveBeenCalledWith({
+        where: {
+          workspaceId_userId: {
+            workspaceId: mockWorkspaceId,
+            userId: mockMemberUserId,
+          },
+        },
+        data: {
+          role: WorkspaceMemberRole.ADMIN,
+        },
+      });
+    });
+
+    it("should throw NotFoundException when target member does not exist", async () => {
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce(null);
+
+      await expect(
+        service.updateMemberRole(mockWorkspaceId, mockUserId, mockMemberUserId, {
+          role: WorkspaceMemberRole.ADMIN,
+        })
+      ).rejects.toThrow(NotFoundException);
+    });
+
+    it("should throw BadRequestException when sole owner attempts self-demotion", async () => {
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        });
+      mockPrismaService.workspaceMember.count.mockResolvedValueOnce(1);
+
+      await expect(
+        service.updateMemberRole(mockWorkspaceId, mockUserId, mockUserId, {
+          role: WorkspaceMemberRole.ADMIN,
+        })
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it("should throw ForbiddenException when actor tries to change role of higher-ranked member", async () => {
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockAdminUserId,
+          role: WorkspaceMemberRole.ADMIN,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        });
+
+      await expect(
+        service.updateMemberRole(mockWorkspaceId, mockAdminUserId, mockUserId, {
+          role: WorkspaceMemberRole.MEMBER,
+        })
+      ).rejects.toThrow(ForbiddenException);
+    });
+  });
+
+  describe("removeMember", () => {
+    it("should remove a workspace member", async () => {
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockMemberUserId,
+          role: WorkspaceMemberRole.MEMBER,
+          joinedAt: new Date("2026-01-02"),
+        });
+      mockPrismaService.workspaceMember.delete.mockResolvedValueOnce({
+        workspaceId: mockWorkspaceId,
+        userId: mockMemberUserId,
+        role: WorkspaceMemberRole.MEMBER,
+        joinedAt: new Date("2026-01-02"),
+      });
+
+      await service.removeMember(mockWorkspaceId, mockUserId, mockMemberUserId);
+
+      expect(mockPrismaService.workspaceMember.delete).toHaveBeenCalledWith({
+        where: {
+          workspaceId_userId: {
+            workspaceId: mockWorkspaceId,
+            userId: mockMemberUserId,
+          },
+        },
+      });
+    });
+
+    it("should throw BadRequestException when trying to remove the last owner", async () => {
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        });
+      mockPrismaService.workspaceMember.count.mockResolvedValueOnce(1);
+
+      await expect(service.removeMember(mockWorkspaceId, mockUserId, mockUserId)).rejects.toThrow(
+        BadRequestException
+      );
+    });
+
+    it("should throw ForbiddenException when admin attempts to remove an owner", async () => {
+      mockPrismaService.workspaceMember.findUnique
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockAdminUserId,
+          role: WorkspaceMemberRole.ADMIN,
+          joinedAt: new Date("2026-01-01"),
+        })
+        .mockResolvedValueOnce({
+          workspaceId: mockWorkspaceId,
+          userId: mockUserId,
+          role: WorkspaceMemberRole.OWNER,
+          joinedAt: new Date("2026-01-01"),
+        });
+
+      await expect(
+        service.removeMember(mockWorkspaceId, mockAdminUserId, mockUserId)
+      ).rejects.toThrow(ForbiddenException);
+    });
+  });
+});

apps/api/src/workspaces/workspaces.service.ts

@@ -0,0 +1,345 @@
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import { Prisma, WorkspaceMemberRole } from "@prisma/client";
+import type { WorkspaceMember } from "@prisma/client";
+import { PrismaService } from "../prisma/prisma.service";
+import type { AddMemberDto, UpdateMemberRoleDto, WorkspaceResponseDto } from "./dto";
+
+const WORKSPACE_ROLE_RANK: Record<WorkspaceMemberRole, number> = {
+  [WorkspaceMemberRole.GUEST]: 1,
+  [WorkspaceMemberRole.MEMBER]: 2,
+  [WorkspaceMemberRole.ADMIN]: 3,
+  [WorkspaceMemberRole.OWNER]: 4,
+};
+
+@Injectable()
+export class WorkspacesService {
+  private readonly logger = new Logger(WorkspacesService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * Get all workspaces the user is a member of.
+   *
+   * Auto-provisioning: if the user has no workspace memberships (e.g. fresh
+   * signup via BetterAuth), a default workspace is created atomically and
+   * returned.  This is the only call site for workspace bootstrapping.
+   */
+  async getUserWorkspaces(userId: string): Promise<WorkspaceResponseDto[]> {
+    const memberships = await this.prisma.workspaceMember.findMany({
+      where: { userId },
+      include: {
+        workspace: {
+          select: { id: true, name: true, ownerId: true, createdAt: true },
+        },
+      },
+      orderBy: { joinedAt: "asc" },
+    });
+
+    if (memberships.length > 0) {
+      return memberships.map((m) => ({
+        id: m.workspace.id,
+        name: m.workspace.name,
+        ownerId: m.workspace.ownerId,
+        role: m.role,
+        createdAt: m.workspace.createdAt,
+      }));
+    }
+
+    // Auto-provision a default workspace for new users.
+    // Re-query inside the transaction to guard against concurrent requests
+    // both seeing zero memberships and creating duplicate workspaces.
+    this.logger.log(`Auto-provisioning default workspace for user ${userId}`);
+
+    const workspace = await this.prisma.$transaction(async (tx) => {
+      const existing = await tx.workspaceMember.findFirst({
+        where: { userId },
+        include: {
+          workspace: {
+            select: { id: true, name: true, ownerId: true, createdAt: true },
+          },
+        },
+      });
+      if (existing) {
+        return { ...existing.workspace, alreadyExisted: true as const };
+      }
+
+      const created = await tx.workspace.create({
+        data: {
+          name: "My Workspace",
+          ownerId: userId,
+          settings: {},
+        },
+      });
+      await tx.workspaceMember.create({
+        data: {
+          workspaceId: created.id,
+          userId,
+          role: WorkspaceMemberRole.OWNER,
+        },
+      });
+      return { ...created, alreadyExisted: false as const };
+    });
+
+    if (workspace.alreadyExisted) {
+      return [
+        {
+          id: workspace.id,
+          name: workspace.name,
+          ownerId: workspace.ownerId,
+          role: WorkspaceMemberRole.OWNER,
+          createdAt: workspace.createdAt,
+        },
+      ];
+    }
+
+    return [
+      {
+        id: workspace.id,
+        name: workspace.name,
+        ownerId: workspace.ownerId,
+        role: WorkspaceMemberRole.OWNER,
+        createdAt: workspace.createdAt,
+      },
+    ];
+  }
+
+  /**
+   * Add a member to a workspace.
+   */
+  async addMember(
+    workspaceId: string,
+    actorUserId: string,
+    addMemberDto: AddMemberDto
+  ): Promise<WorkspaceMember> {
+    const actorMembership = await this.prisma.workspaceMember.findUnique({
+      where: {
+        workspaceId_userId: {
+          workspaceId,
+          userId: actorUserId,
+        },
+      },
+      select: {
+        role: true,
+      },
+    });
+
+    if (!actorMembership) {
+      throw new ForbiddenException("You are not a member of this workspace");
+    }
+
+    this.assertCanAssignRole(actorMembership.role, addMemberDto.role);
+
+    const user = await this.prisma.user.findUnique({
+      where: { id: addMemberDto.userId },
+      select: { id: true },
+    });
+
+    if (!user) {
+      throw new NotFoundException(`User with ID ${addMemberDto.userId} not found`);
+    }
+
+    const existingMembership = await this.prisma.workspaceMember.findUnique({
+      where: {
+        workspaceId_userId: {
+          workspaceId,
+          userId: addMemberDto.userId,
+        },
+      },
+      select: {
+        workspaceId: true,
+        userId: true,
+      },
+    });
+
+    if (existingMembership) {
+      throw new ConflictException("User is already a member of this workspace");
+    }
+
+    try {
+      return await this.prisma.workspaceMember.create({
+        data: {
+          workspaceId,
+          userId: addMemberDto.userId,
+          role: addMemberDto.role,
+        },
+      });
+    } catch (error) {
+      if (this.isUniqueConstraintError(error)) {
+        throw new ConflictException("User is already a member of this workspace");
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Update the role of an existing workspace member.
+   */
+  async updateMemberRole(
+    workspaceId: string,
+    actorUserId: string,
+    targetUserId: string,
+    updateMemberRoleDto: UpdateMemberRoleDto
+  ): Promise<WorkspaceMember> {
+    return this.prisma.$transaction(async (tx) => {
+      const actorMembership = await tx.workspaceMember.findUnique({
+        where: {
+          workspaceId_userId: {
+            workspaceId,
+            userId: actorUserId,
+          },
+        },
+        select: {
+          role: true,
+        },
+      });
+
+      if (!actorMembership) {
+        throw new ForbiddenException("You are not a member of this workspace");
+      }
+
+      const targetMembership = await tx.workspaceMember.findUnique({
+        where: {
+          workspaceId_userId: {
+            workspaceId,
+            userId: targetUserId,
+          },
+        },
+        select: {
+          role: true,
+        },
+      });
+
+      if (!targetMembership) {
+        throw new NotFoundException(`User ${targetUserId} is not a member of this workspace`);
+      }
+
+      this.assertCanManageTargetMember(actorMembership.role, targetMembership.role);
+      this.assertCanAssignRole(actorMembership.role, updateMemberRoleDto.role);
+
+      if (targetMembership.role === WorkspaceMemberRole.OWNER) {
+        const isDemotion = updateMemberRoleDto.role !== WorkspaceMemberRole.OWNER;
+        if (isDemotion) {
+          const ownerCount = await tx.workspaceMember.count({
+            where: {
+              workspaceId,
+              role: WorkspaceMemberRole.OWNER,
+            },
+          });
+          if (ownerCount <= 1) {
+            if (actorUserId === targetUserId) {
+              throw new BadRequestException("Cannot self-demote if you are the sole owner");
+            }
+            throw new BadRequestException("Cannot remove the last owner from a workspace");
+          }
+        }
+      }
+
+      return tx.workspaceMember.update({
+        where: {
+          workspaceId_userId: {
+            workspaceId,
+            userId: targetUserId,
+          },
+        },
+        data: {
+          role: updateMemberRoleDto.role,
+        },
+      });
+    });
+  }
+
+  /**
+   * Remove a member from a workspace.
+   */
+  async removeMember(
+    workspaceId: string,
+    actorUserId: string,
+    targetUserId: string
+  ): Promise<void> {
+    await this.prisma.$transaction(async (tx) => {
+      const actorMembership = await tx.workspaceMember.findUnique({
+        where: {
+          workspaceId_userId: {
+            workspaceId,
+            userId: actorUserId,
+          },
+        },
+        select: {
+          role: true,
+        },
+      });
+
+      if (!actorMembership) {
+        throw new ForbiddenException("You are not a member of this workspace");
+      }
+
+      const targetMembership = await tx.workspaceMember.findUnique({
+        where: {
+          workspaceId_userId: {
+            workspaceId,
+            userId: targetUserId,
+          },
+        },
+        select: {
+          role: true,
+        },
+      });
+
+      if (!targetMembership) {
+        throw new NotFoundException(`User ${targetUserId} is not a member of this workspace`);
+      }
+
+      this.assertCanManageTargetMember(actorMembership.role, targetMembership.role);
+
+      if (targetMembership.role === WorkspaceMemberRole.OWNER) {
+        const ownerCount = await tx.workspaceMember.count({
+          where: {
+            workspaceId,
+            role: WorkspaceMemberRole.OWNER,
+          },
+        });
+        if (ownerCount <= 1) {
+          throw new BadRequestException("Cannot remove the last owner from a workspace");
+        }
+      }
+
+      await tx.workspaceMember.delete({
+        where: {
+          workspaceId_userId: {
+            workspaceId,
+            userId: targetUserId,
+          },
+        },
+      });
+    });
+  }
+
+  private assertCanAssignRole(
+    actorRole: WorkspaceMemberRole,
+    requestedRole: WorkspaceMemberRole
+  ): void {
+    if (WORKSPACE_ROLE_RANK[actorRole] < WORKSPACE_ROLE_RANK[requestedRole]) {
+      throw new ForbiddenException("You cannot assign a role higher than your own");
+    }
+  }
+
+  private assertCanManageTargetMember(
+    actorRole: WorkspaceMemberRole,
+    targetRole: WorkspaceMemberRole
+  ): void {
+    if (WORKSPACE_ROLE_RANK[actorRole] < WORKSPACE_ROLE_RANK[targetRole]) {
+      throw new ForbiddenException("You cannot manage a member with a higher role");
+    }
+  }
+
+  private isUniqueConstraintError(error: unknown): error is Prisma.PrismaClientKnownRequestError {
+    return error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002";
+  }
+}

apps/web/src/app/(authenticated)/profile/page.tsx

@@ -265,23 +265,8 @@ export default function ProfilePage(): ReactElement {
               </p>
             )}
 
-            {user?.workspaceRole && (
-              <span
-                style={{
-                  display: "inline-block",
-                  marginTop: 8,
-                  padding: "3px 10px",
-                  borderRadius: "var(--r)",
-                  background: "rgba(47, 128, 255, 0.1)",
-                  color: "var(--ms-blue-400)",
-                  fontSize: "0.75rem",
-                  fontWeight: 600,
-                  textTransform: "capitalize",
-                }}
-              >
-                {user.workspaceRole}
-              </span>
-            )}
+            {/* Workspace role badge — placeholder until workspace context API
+                provides role data via GET /api/workspaces */}
           </div>
         </div>
       </div>

apps/web/src/app/(authenticated)/settings/page.tsx

@@ -1,7 +1,10 @@
 "use client";
 
-import { useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import type { ReactElement, ReactNode } from "react";
+import { WorkspaceMemberRole } from "@mosaic/shared";
+import { useAuth } from "@/lib/auth/auth-context";
+import { fetchUserWorkspaces } from "@/lib/api/workspaces";
 import Link from "next/link";
 
 interface CategoryConfig {
@@ -11,6 +14,7 @@ interface CategoryConfig {
   accent: string;
   iconBg: string;
   icon: ReactNode;
+  adminOnly?: boolean;
 }
 
 interface SettingsCategoryCardProps {
@@ -196,6 +200,58 @@ const categories: CategoryConfig[] = [
       </svg>
     ),
   },
+  {
+    title: "Users",
+    description: "Invite, manage roles, and deactivate users across your workspaces.",
+    href: "/settings/users",
+    adminOnly: true,
+    accent: "var(--ms-green-400)",
+    iconBg: "rgba(34, 197, 94, 0.12)",
+    icon: (
+      <svg
+        width="20"
+        height="20"
+        viewBox="0 0 20 20"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <circle cx="8" cy="7" r="2.5" />
+        <circle cx="13.5" cy="8.5" r="2" />
+        <path d="M3.5 16c0-2.5 2-4.5 4.5-4.5s4.5 2 4.5 4.5" />
+        <path d="M12 13.8c.5-.8 1.4-1.3 2.5-1.3 1.7 0 3 1.3 3 3" />
+      </svg>
+    ),
+  },
+  {
+    title: "Teams",
+    description: "Create and manage teams within your active workspace.",
+    href: "/settings/teams",
+    adminOnly: true,
+    accent: "var(--ms-blue-400)",
+    iconBg: "rgba(47, 128, 255, 0.12)",
+    icon: (
+      <svg
+        width="20"
+        height="20"
+        viewBox="0 0 20 20"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <circle cx="7" cy="7" r="2.25" />
+        <circle cx="13" cy="7" r="2.25" />
+        <path d="M3 15c0-2.2 1.8-4 4-4s4 1.8 4 4" />
+        <path d="M9 15c0-2.2 1.8-4 4-4s4 1.8 4 4" />
+      </svg>
+    ),
+  },
   {
     title: "Workspaces",
     description:
@@ -227,7 +283,30 @@ const categories: CategoryConfig[] = [
   },
 ];
 
+const ADMIN_ROLES: WorkspaceMemberRole[] = [WorkspaceMemberRole.OWNER, WorkspaceMemberRole.ADMIN];
+
 export default function SettingsPage(): ReactElement {
+  const { user } = useAuth();
+  const [isAdmin, setIsAdmin] = useState<boolean>(false);
+
+  const checkRole = useCallback(async (): Promise<void> => {
+    if (user === null) return;
+    try {
+      const workspaces = await fetchUserWorkspaces();
+      const hasAdminRole = workspaces.some((ws) => ADMIN_ROLES.includes(ws.role));
+      setIsAdmin(hasAdminRole);
+    } catch {
+      // Fail open — show all items if we can't determine role
+      setIsAdmin(true);
+    }
+  }, [user]);
+
+  useEffect(() => {
+    void checkRole();
+  }, [checkRole]);
+
+  const visibleCategories = categories.filter((c) => c.adminOnly !== true || isAdmin);
+
   return (
     <div className="max-w-6xl mx-auto p-6">
       {/* Page header */}
@@ -255,7 +334,7 @@ export default function SettingsPage(): ReactElement {
 
       {/* Category grid */}
       <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-        {categories.map((category) => (
+        {visibleCategories.map((category) => (
           <SettingsCategoryCard key={category.href} category={category} />
         ))}
       </div>

apps/web/src/app/(authenticated)/settings/teams/page.test.tsx

@@ -0,0 +1,190 @@
+import type { ReactElement, ReactNode } from "react";
+import type { TeamRecord } from "@/lib/api/teams";
+
+import { WorkspaceMemberRole } from "@mosaic/shared";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createTeam, deleteTeam, fetchTeams, updateTeam } from "@/lib/api/teams";
+import { fetchUserWorkspaces } from "@/lib/api/workspaces";
+
+import TeamsSettingsPage from "./page";
+
+vi.mock("next/link", () => ({
+  default: function LinkMock({
+    children,
+    href,
+  }: {
+    children: ReactNode;
+    href: string;
+  }): ReactElement {
+    return <a href={href}>{children}</a>;
+  },
+}));
+
+vi.mock("@/lib/api/teams", () => ({
+  fetchTeams: vi.fn(),
+  createTeam: vi.fn(),
+  updateTeam: vi.fn(),
+  deleteTeam: vi.fn(),
+}));
+
+vi.mock("@/lib/api/workspaces", () => ({
+  fetchUserWorkspaces: vi.fn(),
+}));
+
+const fetchTeamsMock = vi.mocked(fetchTeams);
+const createTeamMock = vi.mocked(createTeam);
+const updateTeamMock = vi.mocked(updateTeam);
+const deleteTeamMock = vi.mocked(deleteTeam);
+const fetchUserWorkspacesMock = vi.mocked(fetchUserWorkspaces);
+
+const baseTeam: TeamRecord = {
+  id: "team-1",
+  workspaceId: "workspace-1",
+  name: "Platform Team",
+  description: "Owns platform services",
+  metadata: {},
+  createdAt: "2026-02-01T00:00:00.000Z",
+  updatedAt: "2026-02-01T00:00:00.000Z",
+  _count: {
+    members: 3,
+  },
+};
+
+describe("TeamsSettingsPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    fetchTeamsMock.mockResolvedValue([]);
+    fetchUserWorkspacesMock.mockResolvedValue([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.OWNER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+  });
+
+  it("shows access denied to non-admin users", async () => {
+    fetchUserWorkspacesMock.mockResolvedValueOnce([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.MEMBER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Access Denied")).toBeInTheDocument();
+    expect(fetchTeamsMock).not.toHaveBeenCalled();
+  });
+
+  it("loads and renders teams from the API", async () => {
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Team Directory")).toBeInTheDocument();
+    expect(screen.getByText("Platform Team")).toBeInTheDocument();
+    expect(fetchTeamsMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows empty state when the API returns no teams", async () => {
+    fetchTeamsMock.mockResolvedValue([]);
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("No Teams Yet")).toBeInTheDocument();
+    expect(screen.getByText("Create the first team to get started.")).toBeInTheDocument();
+  });
+
+  it("shows error state and does not show empty state", async () => {
+    fetchTeamsMock.mockRejectedValue(new Error("Unable to load teams"));
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Unable to load teams")).toBeInTheDocument();
+  });
+
+  it("creates a team from the create dialog", async () => {
+    const user = userEvent.setup();
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+    createTeamMock.mockResolvedValue({
+      ...baseTeam,
+      id: "team-2",
+      name: "Design Team",
+      description: "Owns design quality",
+    });
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Platform Team")).toBeInTheDocument();
+
+    const triggerButton = screen.getByRole("button", { name: "Create Team" });
+    await user.click(triggerButton);
+
+    await user.type(screen.getByLabelText("Name"), "Design Team");
+    await user.type(screen.getByLabelText("Description"), "Owns design quality");
+
+    const submitButton = screen.getAllByRole("button", { name: "Create Team" })[1];
+    if (!submitButton) {
+      throw new Error("Expected create-team submit button to be rendered");
+    }
+    await user.click(submitButton);
+
+    await waitFor(() => {
+      expect(createTeamMock).toHaveBeenCalledWith({
+        name: "Design Team",
+        description: "Owns design quality",
+      });
+    });
+  });
+
+  it("opens team details and updates name", async () => {
+    const user = userEvent.setup();
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+    updateTeamMock.mockResolvedValue({
+      ...baseTeam,
+      name: "Platform Engineering",
+    });
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Platform Team")).toBeInTheDocument();
+
+    await user.click(screen.getByText("Platform Team"));
+
+    const nameInput = await screen.findByLabelText("Name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Platform Engineering");
+    await user.click(screen.getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(updateTeamMock).toHaveBeenCalledWith("team-1", {
+        name: "Platform Engineering",
+      });
+    });
+  });
+
+  it("deletes a team from the confirmation dialog", async () => {
+    const user = userEvent.setup();
+    fetchTeamsMock.mockResolvedValue([baseTeam]);
+    deleteTeamMock.mockResolvedValue();
+
+    render(<TeamsSettingsPage />);
+
+    expect(await screen.findByText("Platform Team")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Delete" }));
+    await user.click(screen.getByRole("button", { name: "Delete Team" }));
+
+    await waitFor(() => {
+      expect(deleteTeamMock).toHaveBeenCalledWith("team-1");
+    });
+  });
+});

apps/web/src/app/(authenticated)/settings/teams/page.tsx

@@ -0,0 +1,582 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useState,
+  type ChangeEvent,
+  type KeyboardEvent,
+  type ReactElement,
+  type SyntheticEvent,
+} from "react";
+import Link from "next/link";
+import { Plus, Trash2, Users } from "lucide-react";
+import { WorkspaceMemberRole } from "@mosaic/shared";
+import { SettingsAccessDenied } from "@/components/settings/SettingsAccessDenied";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import {
+  createTeam,
+  deleteTeam,
+  fetchTeams,
+  updateTeam,
+  type CreateTeamDto,
+  type TeamRecord,
+  type UpdateTeamDto,
+} from "@/lib/api/teams";
+import { fetchUserWorkspaces } from "@/lib/api/workspaces";
+
+const INITIAL_CREATE_FORM = {
+  name: "",
+  description: "",
+};
+
+const INITIAL_DETAIL_FORM = {
+  name: "",
+  description: "",
+};
+
+interface DetailInitialState {
+  name: string;
+  description: string;
+}
+
+function toMemberLabel(count: number): string {
+  return `${String(count)} member${count === 1 ? "" : "s"}`;
+}
+
+export default function TeamsSettingsPage(): ReactElement {
+  const [teams, setTeams] = useState<TeamRecord[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [isRefreshing, setIsRefreshing] = useState<boolean>(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isAdmin, setIsAdmin] = useState<boolean | null>(null);
+
+  const [isCreateOpen, setIsCreateOpen] = useState<boolean>(false);
+  const [createForm, setCreateForm] = useState(INITIAL_CREATE_FORM);
+  const [createError, setCreateError] = useState<string | null>(null);
+  const [isCreating, setIsCreating] = useState<boolean>(false);
+
+  const [detailTarget, setDetailTarget] = useState<TeamRecord | null>(null);
+  const [detailForm, setDetailForm] = useState(INITIAL_DETAIL_FORM);
+  const [detailInitial, setDetailInitial] = useState<DetailInitialState | null>(null);
+  const [detailError, setDetailError] = useState<string | null>(null);
+  const [isSavingDetails, setIsSavingDetails] = useState<boolean>(false);
+
+  const [deleteTarget, setDeleteTarget] = useState<TeamRecord | null>(null);
+  const [isDeleting, setIsDeleting] = useState<boolean>(false);
+
+  const loadTeams = useCallback(async (showLoadingState: boolean): Promise<void> => {
+    try {
+      if (showLoadingState) {
+        setIsLoading(true);
+      } else {
+        setIsRefreshing(true);
+      }
+
+      const data = await fetchTeams();
+      setTeams(data);
+      setError(null);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Failed to load teams");
+    } finally {
+      setIsLoading(false);
+      setIsRefreshing(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchUserWorkspaces()
+      .then((workspaces) => {
+        const adminRoles: WorkspaceMemberRole[] = [
+          WorkspaceMemberRole.OWNER,
+          WorkspaceMemberRole.ADMIN,
+        ];
+
+        setIsAdmin(workspaces.some((workspace) => adminRoles.includes(workspace.role)));
+      })
+      .catch(() => {
+        setIsAdmin(true); // fail open
+      });
+  }, []);
+
+  useEffect(() => {
+    if (isAdmin !== true) {
+      return;
+    }
+
+    void loadTeams(true);
+  }, [isAdmin, loadTeams]);
+
+  function resetCreateForm(): void {
+    setCreateForm(INITIAL_CREATE_FORM);
+    setCreateError(null);
+  }
+
+  function openTeamDetails(team: TeamRecord): void {
+    const nextDetailForm = {
+      name: team.name,
+      description: team.description ?? "",
+    };
+
+    setDetailTarget(team);
+    setDetailForm(nextDetailForm);
+    setDetailInitial({
+      name: nextDetailForm.name,
+      description: nextDetailForm.description,
+    });
+    setDetailError(null);
+  }
+
+  function resetTeamDetails(): void {
+    setDetailTarget(null);
+    setDetailForm(INITIAL_DETAIL_FORM);
+    setDetailInitial(null);
+    setDetailError(null);
+  }
+
+  function handleTeamRowKeyDown(event: KeyboardEvent<HTMLDivElement>, team: TeamRecord): void {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      openTeamDetails(team);
+    }
+  }
+
+  async function handleCreateSubmit(event: SyntheticEvent): Promise<void> {
+    event.preventDefault();
+    setCreateError(null);
+
+    const name = createForm.name.trim();
+    if (!name) {
+      setCreateError("Name is required.");
+      return;
+    }
+
+    const description = createForm.description.trim();
+    const dto: CreateTeamDto = { name };
+    if (description) {
+      dto.description = description;
+    }
+
+    try {
+      setIsCreating(true);
+      await createTeam(dto);
+      setIsCreateOpen(false);
+      resetCreateForm();
+      await loadTeams(false);
+    } catch (err: unknown) {
+      setCreateError(err instanceof Error ? err.message : "Failed to create team");
+    } finally {
+      setIsCreating(false);
+    }
+  }
+
+  async function handleDetailSubmit(event: SyntheticEvent): Promise<void> {
+    event.preventDefault();
+
+    if (detailTarget === null || detailInitial === null) {
+      return;
+    }
+
+    const name = detailForm.name.trim();
+    if (!name) {
+      setDetailError("Name is required.");
+      return;
+    }
+
+    const nextDescription = detailForm.description.trim();
+    const normalizedNextDescription = nextDescription.length > 0 ? nextDescription : null;
+    const normalizedInitialDescription =
+      detailInitial.description.trim().length > 0 ? detailInitial.description.trim() : null;
+
+    const dto: UpdateTeamDto = {};
+
+    if (name !== detailInitial.name) {
+      dto.name = name;
+    }
+
+    if (normalizedNextDescription !== normalizedInitialDescription) {
+      dto.description = normalizedNextDescription;
+    }
+
+    if (Object.keys(dto).length === 0) {
+      resetTeamDetails();
+      return;
+    }
+
+    try {
+      setIsSavingDetails(true);
+      setDetailError(null);
+      await updateTeam(detailTarget.id, dto);
+      resetTeamDetails();
+      await loadTeams(false);
+    } catch (err: unknown) {
+      setDetailError(err instanceof Error ? err.message : "Failed to update team");
+    } finally {
+      setIsSavingDetails(false);
+    }
+  }
+
+  async function confirmDelete(): Promise<void> {
+    if (!deleteTarget) {
+      return;
+    }
+
+    try {
+      setIsDeleting(true);
+      await deleteTeam(deleteTarget.id);
+      setDeleteTarget(null);
+      await loadTeams(false);
+      setError(null);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Failed to delete team");
+    } finally {
+      setIsDeleting(false);
+    }
+  }
+
+  if (isAdmin === null) {
+    return (
+      <Card className="max-w-2xl mx-auto mt-8">
+        <CardContent className="py-12 text-center text-muted-foreground">
+          Checking permissions...
+        </CardContent>
+      </Card>
+    );
+  }
+
+  if (!isAdmin) {
+    return <SettingsAccessDenied message="You need Admin or Owner role to manage teams." />;
+  }
+
+  return (
+    <div className="max-w-6xl mx-auto p-6 space-y-6">
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <div className="flex items-center gap-3">
+            <h1 className="text-3xl font-bold">Teams</h1>
+            <Badge variant="outline">{teams.length} total</Badge>
+          </div>
+          <p className="text-muted-foreground mt-1">Create and manage workspace teams</p>
+        </div>
+
+        <div className="flex items-center gap-2">
+          <Button
+            variant="outline"
+            onClick={() => {
+              void loadTeams(false);
+            }}
+            disabled={isLoading || isRefreshing}
+          >
+            {isRefreshing ? "Refreshing..." : "Refresh"}
+          </Button>
+
+          <Dialog
+            open={isCreateOpen}
+            onOpenChange={(open) => {
+              if (!open && !isCreating) {
+                resetCreateForm();
+              }
+              setIsCreateOpen(open);
+            }}
+          >
+            <DialogTrigger asChild>
+              <Button>
+                <Plus className="h-4 w-4 mr-2" />
+                Create Team
+              </Button>
+            </DialogTrigger>
+            <DialogContent>
+              <DialogHeader>
+                <DialogTitle>Create Team</DialogTitle>
+                <DialogDescription>
+                  Create a team in the active workspace to organize members and permissions.
+                </DialogDescription>
+              </DialogHeader>
+
+              <form
+                onSubmit={(event) => {
+                  void handleCreateSubmit(event);
+                }}
+                className="space-y-4"
+              >
+                <div className="space-y-2">
+                  <Label htmlFor="create-name">Name</Label>
+                  <Input
+                    id="create-name"
+                    value={createForm.name}
+                    onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                      setCreateForm((prev) => ({ ...prev, name: event.target.value }));
+                    }}
+                    placeholder="Platform Team"
+                    maxLength={100}
+                    required
+                  />
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="create-description">Description</Label>
+                  <Textarea
+                    id="create-description"
+                    value={createForm.description}
+                    onChange={(event: ChangeEvent<HTMLTextAreaElement>) => {
+                      setCreateForm((prev) => ({ ...prev, description: event.target.value }));
+                    }}
+                    placeholder="Owns platform services and infrastructure"
+                    maxLength={500}
+                    rows={4}
+                  />
+                </div>
+
+                {createError ? (
+                  <p className="text-sm text-destructive" role="alert">
+                    {createError}
+                  </p>
+                ) : null}
+
+                <DialogFooter>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    onClick={() => {
+                      if (!isCreating) {
+                        setIsCreateOpen(false);
+                        resetCreateForm();
+                      }
+                    }}
+                    disabled={isCreating}
+                  >
+                    Cancel
+                  </Button>
+                  <Button type="submit" disabled={isCreating}>
+                    {isCreating ? "Creating..." : "Create Team"}
+                  </Button>
+                </DialogFooter>
+              </form>
+            </DialogContent>
+          </Dialog>
+        </div>
+      </div>
+
+      <div>
+        <Link href="/settings" className="text-sm text-blue-600 hover:text-blue-700">
+          ← Back to Settings
+        </Link>
+      </div>
+
+      {error ? (
+        <Card>
+          <CardContent className="py-4">
+            <p className="text-sm text-destructive" role="alert">
+              {error}
+            </p>
+          </CardContent>
+        </Card>
+      ) : null}
+
+      {isLoading ? (
+        <Card>
+          <CardContent className="py-12 text-center text-muted-foreground">
+            Loading teams...
+          </CardContent>
+        </Card>
+      ) : teams.length === 0 ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>No Teams Yet</CardTitle>
+            <CardDescription>Create the first team to get started.</CardDescription>
+          </CardHeader>
+        </Card>
+      ) : (
+        <Card>
+          <CardHeader>
+            <CardTitle>Team Directory</CardTitle>
+            <CardDescription>
+              Click a team to view details or edit name and description.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-3">
+            {teams.map((team) => {
+              const memberCount = team._count?.members ?? 0;
+              const description = team.description?.trim();
+
+              return (
+                <div
+                  key={team.id}
+                  className="rounded-md border p-4 flex flex-col gap-3 md:flex-row md:items-center md:justify-between cursor-pointer hover:bg-muted/30"
+                  role="button"
+                  tabIndex={0}
+                  onClick={() => {
+                    openTeamDetails(team);
+                  }}
+                  onKeyDown={(event) => {
+                    handleTeamRowKeyDown(event, team);
+                  }}
+                >
+                  <div className="space-y-1 min-w-0">
+                    <p className="font-semibold truncate">{team.name}</p>
+                    <p className="text-sm text-muted-foreground truncate">
+                      {description && description.length > 0 ? description : "No description"}
+                    </p>
+                  </div>
+
+                  <div className="flex items-center gap-2 flex-wrap md:justify-end">
+                    <Badge variant="outline">
+                      <Users className="h-3.5 w-3.5 mr-1" />
+                      {toMemberLabel(memberCount)}
+                    </Badge>
+                    <Badge variant="secondary">
+                      Created {new Date(team.createdAt).toLocaleDateString()}
+                    </Badge>
+                    <Button
+                      variant="destructive"
+                      size="sm"
+                      onClick={(event) => {
+                        event.stopPropagation();
+                        setDeleteTarget(team);
+                      }}
+                    >
+                      <Trash2 className="h-4 w-4 mr-2" />
+                      Delete
+                    </Button>
+                  </div>
+                </div>
+              );
+            })}
+          </CardContent>
+        </Card>
+      )}
+
+      <Dialog
+        open={detailTarget !== null}
+        onOpenChange={(open) => {
+          if (!open && !isSavingDetails) {
+            resetTeamDetails();
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Team Details</DialogTitle>
+            <DialogDescription>
+              Edit team details for {detailTarget?.name ?? "selected team"}.
+            </DialogDescription>
+          </DialogHeader>
+
+          <form
+            onSubmit={(event) => {
+              void handleDetailSubmit(event);
+            }}
+            className="space-y-4"
+          >
+            <div className="space-y-2">
+              <Label htmlFor="detail-name">Name</Label>
+              <Input
+                id="detail-name"
+                value={detailForm.name}
+                onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                  setDetailForm((prev) => ({ ...prev, name: event.target.value }));
+                }}
+                placeholder="Team name"
+                maxLength={100}
+                disabled={isSavingDetails}
+                required
+              />
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="detail-description">Description</Label>
+              <Textarea
+                id="detail-description"
+                value={detailForm.description}
+                onChange={(event: ChangeEvent<HTMLTextAreaElement>) => {
+                  setDetailForm((prev) => ({ ...prev, description: event.target.value }));
+                }}
+                placeholder="Describe this team"
+                maxLength={500}
+                rows={4}
+                disabled={isSavingDetails}
+              />
+            </div>
+
+            {detailError !== null ? (
+              <p className="text-sm text-destructive" role="alert">
+                {detailError}
+              </p>
+            ) : null}
+
+            <DialogFooter>
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => {
+                  if (!isSavingDetails) {
+                    resetTeamDetails();
+                  }
+                }}
+                disabled={isSavingDetails}
+              >
+                Cancel
+              </Button>
+              <Button type="submit" disabled={isSavingDetails}>
+                {isSavingDetails ? "Saving..." : "Save Changes"}
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+
+      <AlertDialog
+        open={deleteTarget !== null}
+        onOpenChange={(open) => {
+          if (!open && !isDeleting) {
+            setDeleteTarget(null);
+          }
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete Team</AlertDialogTitle>
+            <AlertDialogDescription>
+              Delete {deleteTarget?.name}? Team members will be removed from this team assignment.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={isDeleting}>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              disabled={isDeleting}
+              onClick={() => {
+                void confirmDelete();
+              }}
+            >
+              {isDeleting ? "Deleting..." : "Delete Team"}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}

apps/web/src/app/(authenticated)/settings/users/page.test.tsx

@@ -0,0 +1,352 @@
+import type { ReactElement, ReactNode } from "react";
+
+import { WorkspaceMemberRole } from "@mosaic/shared";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  type AdminUser,
+  deactivateUser,
+  fetchAdminUsers,
+  inviteUser,
+  updateUser,
+  type AdminUsersResponse,
+} from "@/lib/api/admin";
+import { useAuth } from "@/lib/auth/auth-context";
+import { fetchUserWorkspaces, updateWorkspaceMemberRole } from "@/lib/api/workspaces";
+import UsersSettingsPage from "./page";
+
+vi.mock("next/link", () => ({
+  default: function LinkMock({
+    children,
+    href,
+  }: {
+    children: ReactNode;
+    href: string;
+  }): ReactElement {
+    return <a href={href}>{children}</a>;
+  },
+}));
+
+vi.mock("@/lib/api/admin", () => ({
+  fetchAdminUsers: vi.fn(),
+  inviteUser: vi.fn(),
+  updateUser: vi.fn(),
+  deactivateUser: vi.fn(),
+}));
+
+vi.mock("@/lib/api/workspaces", () => ({
+  fetchUserWorkspaces: vi.fn(),
+  updateWorkspaceMemberRole: vi.fn(),
+}));
+
+vi.mock("@/lib/auth/auth-context", () => ({
+  useAuth: vi.fn(),
+}));
+
+const fetchAdminUsersMock = vi.mocked(fetchAdminUsers);
+const inviteUserMock = vi.mocked(inviteUser);
+const updateUserMock = vi.mocked(updateUser);
+const deactivateUserMock = vi.mocked(deactivateUser);
+const fetchUserWorkspacesMock = vi.mocked(fetchUserWorkspaces);
+const updateWorkspaceMemberRoleMock = vi.mocked(updateWorkspaceMemberRole);
+const useAuthMock = vi.mocked(useAuth);
+
+function makeAdminUser(overrides?: Partial<AdminUser>): AdminUser {
+  return {
+    id: "user-1",
+    name: "Alice",
+    email: "alice@example.com",
+    emailVerified: true,
+    image: null,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    deactivatedAt: null,
+    isLocalAuth: false,
+    invitedAt: null,
+    invitedBy: null,
+    workspaceMemberships: [
+      {
+        workspaceId: "workspace-1",
+        workspaceName: "Personal Workspace",
+        role: WorkspaceMemberRole.ADMIN,
+        joinedAt: "2026-01-01T00:00:00.000Z",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function makeAdminUsersResponse(options?: {
+  data?: AdminUser[];
+  page?: number;
+  totalPages?: number;
+  total?: number;
+  limit?: number;
+}): AdminUsersResponse {
+  const data = options?.data ?? [makeAdminUser()];
+  return {
+    data,
+    meta: {
+      total: options?.total ?? data.length,
+      page: options?.page ?? 1,
+      limit: options?.limit ?? 50,
+      totalPages: options?.totalPages ?? 1,
+    },
+  };
+}
+
+function makeAuthState(userId: string): ReturnType<typeof useAuth> {
+  return {
+    user: { id: userId, email: `${userId}@example.com`, name: "Current User" },
+    isLoading: false,
+    isAuthenticated: true,
+    authError: null,
+    sessionExpiring: false,
+    sessionMinutesRemaining: 0,
+    signOut: vi.fn(() => Promise.resolve()),
+    refreshSession: vi.fn(() => Promise.resolve()),
+  };
+}
+
+describe("UsersSettingsPage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    const adminUsersResponse = makeAdminUsersResponse();
+
+    fetchAdminUsersMock.mockResolvedValue(adminUsersResponse);
+    fetchUserWorkspacesMock.mockResolvedValue([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.OWNER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+    inviteUserMock.mockResolvedValue({
+      userId: "user-2",
+      invitationToken: "token-1",
+      email: "new@example.com",
+      invitedAt: "2026-01-02T00:00:00.000Z",
+    });
+    const firstUser = adminUsersResponse.data[0] ?? makeAdminUser();
+
+    updateUserMock.mockResolvedValue(firstUser);
+    deactivateUserMock.mockResolvedValue(firstUser);
+    updateWorkspaceMemberRoleMock.mockResolvedValue({
+      workspaceId: "workspace-1",
+      userId: "user-1",
+      role: WorkspaceMemberRole.ADMIN,
+      joinedAt: "2026-01-01T00:00:00.000Z",
+      user: {
+        id: "user-1",
+        email: "alice@example.com",
+        name: "Alice",
+        image: null,
+      },
+    });
+
+    useAuthMock.mockReturnValue(makeAuthState("user-current"));
+  });
+
+  it("shows access denied to non-admin users", async () => {
+    fetchUserWorkspacesMock.mockResolvedValueOnce([
+      {
+        id: "workspace-1",
+        name: "Personal Workspace",
+        ownerId: "owner-1",
+        role: WorkspaceMemberRole.MEMBER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("Access Denied")).toBeInTheDocument();
+    expect(fetchAdminUsersMock).not.toHaveBeenCalled();
+  });
+
+  it("invites a user with email and role from the dialog", async () => {
+    const user = userEvent.setup();
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("User Directory")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Invite User" }));
+    await user.type(screen.getByLabelText("Email"), "new@example.com");
+    await user.click(screen.getByRole("button", { name: "Send Invite" }));
+
+    await waitFor(() => {
+      expect(inviteUserMock).toHaveBeenCalledWith({
+        email: "new@example.com",
+        role: WorkspaceMemberRole.MEMBER,
+        workspaceId: "workspace-1",
+      });
+    });
+  });
+
+  it("opens user detail dialog from row click and saves edited profile fields", async () => {
+    const user = userEvent.setup();
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("alice@example.com")).toBeInTheDocument();
+
+    await user.click(screen.getByText("Alice"));
+
+    const nameInput = await screen.findByLabelText("Name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Alice Updated");
+
+    await user.click(screen.getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(updateUserMock).toHaveBeenCalledWith("user-1", { name: "Alice Updated" });
+    });
+
+    expect(updateWorkspaceMemberRoleMock).not.toHaveBeenCalled();
+  });
+
+  it("caps pagination to the last valid page after deactivation shrinks the dataset", async () => {
+    const user = userEvent.setup();
+    const pageOneUser = makeAdminUser({
+      id: "user-1",
+      name: "Alice",
+      email: "alice@example.com",
+    });
+    const pageTwoUser = makeAdminUser({
+      id: "user-2",
+      name: "Bob",
+      email: "bob@example.com",
+    });
+
+    fetchAdminUsersMock.mockReset();
+    const responses = [
+      {
+        expectedPage: 1,
+        response: makeAdminUsersResponse({
+          data: [pageOneUser],
+          page: 1,
+          totalPages: 2,
+          total: 2,
+        }),
+      },
+      {
+        expectedPage: 2,
+        response: makeAdminUsersResponse({
+          data: [pageTwoUser],
+          page: 2,
+          totalPages: 2,
+          total: 2,
+        }),
+      },
+      {
+        expectedPage: 2,
+        response: makeAdminUsersResponse({
+          data: [],
+          page: 2,
+          totalPages: 1,
+          total: 1,
+        }),
+      },
+      {
+        expectedPage: 1,
+        response: makeAdminUsersResponse({
+          data: [pageOneUser],
+          page: 1,
+          totalPages: 1,
+          total: 1,
+        }),
+      },
+    ];
+
+    fetchAdminUsersMock.mockImplementation((page = 1) => {
+      const next = responses.shift();
+      if (!next) {
+        throw new Error("Unexpected fetchAdminUsers call in pagination-cap test");
+      }
+
+      expect(page).toBe(next.expectedPage);
+      return Promise.resolve(next.response);
+    });
+
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("alice@example.com")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    expect(await screen.findByText("bob@example.com")).toBeInTheDocument();
+
+    const pageTwoRow = screen.getByText("bob@example.com").closest('[role="button"]');
+    if (!(pageTwoRow instanceof HTMLElement)) {
+      throw new Error("Expected Bob's row to exist");
+    }
+
+    await user.click(within(pageTwoRow).getByRole("button", { name: "Deactivate" }));
+    const deactivateButtons = await screen.findAllByRole("button", { name: "Deactivate" });
+    const confirmDeactivateButton = deactivateButtons[deactivateButtons.length - 1];
+    if (!confirmDeactivateButton) {
+      throw new Error("Expected confirmation deactivate button to be rendered");
+    }
+    await user.click(confirmDeactivateButton);
+
+    expect(await screen.findByText("alice@example.com")).toBeInTheDocument();
+    expect(screen.queryByText("No Users Yet")).not.toBeInTheDocument();
+    expect(deactivateUserMock).toHaveBeenCalledWith("user-2");
+    const requestedPages = fetchAdminUsersMock.mock.calls.map(([requestedPage]) => requestedPage);
+    expect(requestedPages.slice(-2)).toEqual([2, 1]);
+  });
+
+  it("shows the API error state without rendering the empty-state message", async () => {
+    fetchAdminUsersMock.mockRejectedValueOnce(new Error("Unable to load users"));
+
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("Unable to load users")).toBeInTheDocument();
+    expect(screen.queryByText("No Users Yet")).not.toBeInTheDocument();
+    expect(screen.queryByText("Invite the first user to get started.")).not.toBeInTheDocument();
+  });
+
+  it("prevents the current user from deactivating their own account", async () => {
+    useAuthMock.mockReturnValue(makeAuthState("user-1"));
+
+    const selfUser = makeAdminUser({
+      id: "user-1",
+      name: "Alice",
+      email: "alice@example.com",
+    });
+    const otherUser = makeAdminUser({
+      id: "user-2",
+      name: "Bob",
+      email: "bob@example.com",
+    });
+
+    fetchAdminUsersMock.mockResolvedValueOnce(
+      makeAdminUsersResponse({
+        data: [selfUser, otherUser],
+        page: 1,
+        totalPages: 1,
+        total: 2,
+      })
+    );
+
+    render(<UsersSettingsPage />);
+
+    expect(await screen.findByText("alice@example.com")).toBeInTheDocument();
+    expect(screen.getByText("bob@example.com")).toBeInTheDocument();
+
+    const selfRow = screen.getByText("alice@example.com").closest('[role="button"]');
+    if (!(selfRow instanceof HTMLElement)) {
+      throw new Error("Expected current-user row to exist");
+    }
+    expect(within(selfRow).queryByRole("button", { name: "Deactivate" })).not.toBeInTheDocument();
+
+    const otherRow = screen.getByText("bob@example.com").closest('[role="button"]');
+    if (!(otherRow instanceof HTMLElement)) {
+      throw new Error("Expected other-user row to exist");
+    }
+    expect(within(otherRow).getByRole("button", { name: "Deactivate" })).toBeInTheDocument();
+    expect(deactivateUserMock).not.toHaveBeenCalled();
+  });
+});